OKit

适用于 Swift 的简单易用的应用程序框架，用于通过 (几乎) 无代码创建基于模型和 storyboards 的应用程序。

核心功能

• 模型和实体
• JSON 存储（文件，http）
• 部分（分割）
• 引用
• 复杂绑定
• 失效
• 数据和图像（包括内联）
• 加密
• 应用程序外壳
• 滑动菜单
• 设置
• 面容识别
• 保护 + 超时
• 主题（包括暗黑主题）
• 备份（加密）
• 帮助视图
• 复用单元格
• 自动密钥生成

核心技术

• Storyboard：应用程序流程使用 storyboards 和模型控制器、模型控制进行设计
• 模型：模型被命名为数据对象，并继承自 Model
• 模型实体：模型实体是模型的一部分，并继承自 ModelEntity
• Codable：模型和模型实体将自动（反）序列化为 Codable 协议
• Context：模型和模型实体可以用于模型控制器和模型控制中的上下文
• Binding：模型控制器和模型控制的属性可以绑定到模型绑定路径
• KVC：使用 @objc 注解更新模型对象时，使用键值编码
• Controller：模型控制器已启用绑定，并继承自 ModelListTableController、ModelDetailTableController 或其子类
• Control：模型控制和模型单元格已启用绑定，其中后者继承自 ModelTableCell 或其子类
• Inspectable：模型控制器和模型控制已扩展为具有 @IBInspectable 属性，在 Interface Builder 中可维护

用法

安装：CocoaPods

OKit 通过 CocoaPods 提供。要安装它，请将以下行添加到您的 Podfile 中

  use_frameworks!
  pod 'OKit'

参考示例：书店

完整的OKit示例项目书店可供获取，展示了OKit框架的所有功能。

模型

模型定义

模型定义基于Swift类，继承自Model，可能包括继承自ModelEntity的嵌套实体。模型隐式地也是一个（根）模型实体，并继承了所有绑定功能。

以下模型类型存在：

• Model：模型以JSON格式读取/存储到文件系统中的文档目录的okit/data文件夹中，使用模型名和.json扩展名。
• ModelTransient：模型不读取/存储（因此使用临时处理）。
• ModelEncrypted：模型以加密的二进制格式读取/存储到文件系统中的文档目录的okit/data文件夹中，使用模型名和.json扩展名。
• ModelHttp：模型以JSON格式通过HTTP配置的端点读取/存储（端点URL可以通过在Info.plist中配置密钥OKitModelEndpointUrl进行配置）。
• ModelEncryptedHttp：模型以加密的二进制格式通过HTTP到配置的端点读取/存储（端点URL可以通过在Info.plist中配置密钥OKitModelEndpointUrl进行配置）。

示例

@objc(Shop)
class Shop: Model, Codable {
    var id: String!
    var books: [Book] = []
}

@objc(Book)
class Book: ModelEntity, Codable {
    var id: String!
    var name: String = ""
    var date: Date = Date()
    var marked: Bool = false
    var icon: ModelImage?
    var authors: [Author] = []
}

@objc(Author)
class Author: ModelEntity, Codable {
    var id: String!
    var name: String = "<New Author>"
}

解释

• 为了允许由模型控制器在Swift中进行动态实例化和键值观察（KVO）以支持绑定，应使用@objc关键字。
• 必须遵循Codable协议，以便将模型和模型实体反序列化为JSON。
• 使用Codable协议进行自动JSON反序列化对于继承的属性不起作用，需要手动使用Encoder和Decoder协议处理。
• 属性var id: String!将由框架自动填充UUID，且对于支持模型实体的引用是必需的。

模型注册

模型可以通过Model类和一个可选的名称进行注册。

Model.initialize(window, secure: true) {
    self.shop = Model.register(Shop.self)
    self.catalog = Model.register(Catalog.self, "catalog")
}

如果省略名称，则该模型将以隐含名称 default 注册为默认模型。注册应在 AppDelegate 的 application:didFinishLaunchingWithOptions 中完成。模型实例可以存储在应用程序上下文中以便稍后访问。

存储模型

通过在模型实例上调用 Model.store(...) 来存储模型

Model.store(self.shop)

定义模型状态

为了在状态中一起更新所有模型，需进行以下注册

Model.state() {
    Model.store(self.shop)
    Model.store(self.settings)
}

状态定义应在 AppDelegate 的 application:didFinishLaunchingWithOptions 中完成。这支持在加密/非加密持久化之间切换，并启用备份/导入功能。

存储模型状态

可以使用以下方式存储模型状态

Model.storeState()

例如，可以在 AppDelegate 的 applicationDidEnterBackground 中进行存储。

恢复模型状态

可以使用以下方式恢复模型状态

Model.restoreState()

例如，可以在 AppDelegate 的 applicationWillEnterForeground 中进行存储。

模型实体

模型实体定义要存储的属性和相应的类型。可遵守 Codable 协议的模型实体可以序列化和反序列化到JSON。
模型实体可以递归包含数组、映射、集合或模型实体的单一引用。支持对模型实体与控制器和控件进行绑定。

模型绑定

可以使用以下绑定定义将UI控制器和UI控件绑定到模型实体（上下文）：

一个复杂的绑定示例如下：

m1>/a/$b/../c()/d[1]/e(/a)/[email protected]

要在文本字符串中使用特殊绑定字符，可以先用Unicode表示法来转义这些字符。例如，逗号表示为\u{002c}。

扩展函数绑定

可以访问核心数据类型（例如Number、String、Date...）的函数和属性

示例

• authors.@count/suffixPlural(#entry)：使用可翻译且可复数的字符串给@count返回的数字添加后缀。
• %Price: ,price/round2, %EUR：多部分绑定将货币添加到价格值中
• name/initial：字符串扩展返回名字的第一个字符
• date/formatRelativeDate：日期扩展将日期格式化为相对日期

任何Swift/Obj-C类型都可以扩展额外的函数和属性，并在绑定表达式中使用。

模型实体失效

通过绑定或相应的 get、set、call 函数以编程方式更新模型实体将触发一个失效机制（除非指定了 suppressInvalidate）。失效将通知所有已绑定的控制器和控件更新其内容。

模型实体重用

• ModelRef：重用模型实体以存储实体引用
• ModelData：重用模型实体以存储任意二进制数据。数据根据模型类型（文件、http、加密、临时）分别存储，并懒加载
• ModelImage：重用模型实体以存储模型图像。图像数据根据模型类型（文件、http、加密、临时）分别存储，并懒加载
• ModelInlineData：重用模型实体以存储任意数据。数据直接存储在模型实体 JSON 数据中
• ModelInlineImage：重用模型实体以存储模型图像。图像数据直接存储在模型实体 JSON 数据中
• ModelSettings：重用模型实体以存储应用程序模型设置（例如，主题、加密、保护等）

模型实体引用

可以使用模型实体库 ModelRef 来引用模型实体。

示例

@objc(Book)
class Book: ModelEntity, Codable {

    var id: String!
    var name: String = ""
    var author: ModelRef = ModelRef()
    
}

模型实体 Book 通过其键（ID）引用模型实体 Author。因此，Author 并不是作为组合存储，而是在 Book 中存储引用键作为外键。这两个实体必须位于相同的模型实体部分（参见下一节）中，才能能够通过属性 book.author.ref 懒加载地解析引用。

模型实体部分

可以通过继承 ModelPartial 并实现 sync 和 store 函数来建立模型分区（部分）。

示例

@objc(GroupDefer)
class GroupDefer: ModelPartial, Codable {
    var id: String!
    var name: String = "" {
        didSet {
            group?.name = name
        }
    }
    var group: Group? {
        get {
            return try? retrieve(Group.self)
        }
        set {
            assign(newValue)
        }
    }

    override func sync(entity: ModelEntity) {
        name = (entity as! Group).name
    }

    override func store() {
        try? store(group)
    }
}

@objc(Group)
class Group: ModelEntity, Codable {
    var id: String!
    var name: String = ""
}

实体 Group 在部分 GroupDefer 中通过从不同的 URL 中读取/存储来懒加载地解决。可以使用 sync 和 didSet 来同步两个实体中可用的属性（例如 name）。通过调用 store 来存储分区数据。

模型实体生命周期钩子

管理钩子

回调函数 managed 可以被覆盖以实现生命周期钩子，当模型实体是上下文的一部分时，即父实体或父实体的集合属性。

open dynamic func managed(_ context: Any? = nil) {
    // ...
}

上下文可以是父实体或父实体的集合。

未管理钩子

回调函数 unmanaged 可以被覆盖以实现生命周期钩子，当模型实体从上下文中移除时。

open dynamic func unmanaged(_ context: Any? = nil) {
    // ...
}

上下文可以是父实体或父实体的集合。

故事板/控制器

使用以下模型类作为自定义类，通过故事板构建用户界面，使用标准 View Controllers 和 Table View Controller

• ModelListTableController：表示模型实体的列表控制器
• ModelDetailTableController：表示模型实体的详情控制器
• ModelSelectionTableController：显示单选或复选模型实体的选择列表控制器
• ModelApplicationController：表示滑动菜单和保护支持的程序环境
• ModelMenuTableController：表示滑动菜单容器中可见的菜单控制器
• ModelSettingsTableController：表示设置控制器，以显示模型设置
• ModelBackupTableController：表示备份控制器，用于创建和导入备份
• ModelSecureBackupTableController：表示安全备份控制器，用于创建和导入安全备份

模型控制器定义了 @IBInspectable 属性，这些属性被 Interface Builder 解释，以增强属性的侧边栏。

模型控制器可以继承自 ModelBaseTableController 以获得公共绑定功能。当然，每个模型控制器都可以进一步子类化以实现更多用例特定的功能。

建议使用故事板，也可以编程方式使用模型控制器直接在代码中构建 UI。

故事板标识符

模型单元格

始终使用 model 单元标识符用于在故事板中使用模型类动态原型单元格。

模型转场

始终使用 model 转场标识符在故事板中进行模型表格与模型详细表格之间的转场。

<abstract> 模型基本表格

模型基本表格控制器包含适用于所有模型控制器公共的绑定逻辑等。

以下 @IBInspectable 属性存在于模型表格 ModelBaseTableController 中

模型列表表

模型列表表控制器 ModelListTableController 在表格视图中显示模型实体的列表。

以下 @IBInspectable 属性存在于模型表 ModelListTableController 上

模型详情表

模型详情表控制器 ModelDetailTableController 以表格视图控制器的方式显示一个模型实体的详细信息。

模型表中 ModelDetailTableController 存在以下 @IBInspectable 属性

模型选择表（模型列表表）

模型选择表控制器 ModelSelectionTableController 以表格视图控制器的方式显示模型实体列表，用于选择单个或多个模型实体。

模型表中 ModelSelectionTableController 存在以下 @IBInspectable 属性

模型应用

模型应用控制器 ModelApplicationController 显示应用环境，包括内容和滑入菜单区域。它显示模型菜单表并根据故事板标识符控制内容显示。

在模型表 ModelApplicationController 中存在以下 @IBInspectable 属性

保护

如果模型设置中激活，应用可以通过面部识别进行保护。当保护激活时，会显示保护覆盖，以在退出应用时隐藏下面的敏感应用程序数据。指定的分钟数内的保护超时，如果需要使用面部识别重新认证以挂起保护覆盖。

模型菜单表（模型列表表）

模型菜单表控制器 ModelMenuTableController 显示在模型应用控制器中的菜单。它用于根据菜单选择通过故事板标识符显示内容。

在模型菜单表控制器 ModelMenuTableController 中存在以下 @IBInspectable 属性

模型菜单栏按钮项

表示菜单按钮（包括汉堡图标）的 UIBarButtonItem，可直接使用。

菜单设置表（模型详情表）

模型设置表控制器 ModelSettingsTableController 在模型应用程序控制器中显示模型设置。模型详情表控制器与 ModelSettings 实体的绑定应使用 ModelSettingsTableController 基类，因为这样会自动处理主题、加密、保护等设置的无效化。

模型备份表

模型备份表 ModelBackupTableController 显示模型备份列表。此外，可以创建新的备份或删除现有备份。在备份期间，导出所有模型。选择备份会触发导入现有备份的操作，并在显示确认弹窗后覆盖当前模型。

备份存储在文档目录的 okit/backup 文件夹中。

模型安全备份表

模型安全备份表 ModelSecureBackupTableController 允许一个安全弹窗，用于输入备份创建和备份导入的密码。

open func dataToBackup(sourceURL: URL, targetURL: URL, name: String, password: String) throws -> Bool

函数 dataToBackup 可以在子类中重写，以创建和复制受密码保护的.zip文件。

open func backupToData(sourceURL: URL, targetURL: URL, name: String, password: String) throws -> Bool

导出被暂时存储在文档目录的 okit/export 文件夹中，以供备份逻辑进一步处理。例如，函数 backupToData 可以在子类中重写，以提取受密码保护的.zip文件并将其复制到目标位置。

模型主题

提供了一个内置的主题概念。中心类是 ModelTheme。有两个内置的主题

• ModelTheme.defaultTheme：iOS默认主题
• ModelTheme.darkTheme：框架提供的默认暗色主题

自定义主题

可以创建并注册自己的自定义主题到 ModelTheme 类中

public static func register(theme: ModelTheme, name: String)

可以通过模型绑定或通过显式使用 func applyTheme(_ theme: ModelTheme?) 设置模型应用中的主题。

模型控件

<abstract> 模型视图

基于视图的控件的抽象基类，支持模型绑定。

模型帮助视图

可以为列表和详细模型控制器连接一个可帮助视图到 IBOutlet helpView。它处理模态帮助视图的显示和丢弃。帮助视图内容可以在故事板中静态建模或通过子类化模型帮助视图动态建模。

模型标签

UILabel的可绑定表示。以下存在以下 @IBInspectable 属性：

模型按钮

用于表示 UIButton 的可绑定表示。以下存在以下 @IBInspectable 属性：

模型工具栏按钮项

用于表示 UIBarButtonItem 的可绑定表示。以下存在以下 @IBInspectable 属性：

模型菜单栏按钮项

表示菜单按钮（包括汉堡图标）的 UIBarButtonItem，可以直接使用。

模型单元格

表格单元格

用于表示 UITableViewCell 的可绑定表示。以下存在以下 @IBInspectable 属性：

<abstract> 编辑单元格（表格单元格）

可绑定表示可编辑的 UITableViewCell。存在以下 @IBInspectable 属性

开关单元格（编辑单元格）

包含 UISwitch 控件的 UITableViewCell 的可绑定表示。存在以下 @IBInspectable 属性

文本单元格（编辑单元格）

包含 UITextField 控件的 UITableViewCell 的可绑定表示。存在以下 @IBInspectable 属性

日期单元格（编辑单元格）

包含 UIDatePicker 控件的 UITableViewCell 的可绑定表示。以下存在以下 @IBInspectable 属性

多行单元格（编辑单元格）

包含 UITextView 控件的 UITableViewCell 的可绑定表示。以下存在以下 @IBInspectable 属性

分段单元格（编辑单元格）

包含 UISegmentedControl 控件的 UITableViewCell 的可绑定表示。以下存在以下 @IBInspectable 属性

选择器单元格（编辑单元格）

包含 UIPickerView 控件的 UITableViewCell 的可绑定表示。以下存在以下 @IBInspectable 属性

滑动单元格（编辑单元格）

包含 UISlider 控件的 UITableViewCell 的可绑定表示。存在以下 @IBInspectable 属性：

步进单元格（编辑单元格）

包含 UIStepper 控件的 UITableViewCell 的可绑定表示。存在以下 @IBInspectable 属性：

模型帮助视图

可以通过 IBOutlet helpView 连接帮助视图。

模型继承

任何模型实体、控制器及其派生类都可以继承，并且可以重写函数以更改默认行为，因为大多数定义都被标记为 open 和 public。