默认 3.0.0

Default 3.0.0

测试已测试
语言语言 SwiftSwift
许可证 MIT
发布最新发布2019年4月
SPM支持 SPM

Nicholas Maccharoli 管理。



Default 3.0.0

  • 作者
  • Nicholas Maccharoli

Default

Build Status platforms Swift 4.2 CocoaPods compatible Carthage compatible License

UserDefaults 的现代接口 + Codable 支持

什么是 Default?

Default 是一个库,通过提供对符合 Codable 的自定义对象的扩展来扩展 UserDefaults 的功能,同时也提供了一个新的通过 DefaultStorable 协议描述的UserDefaults接口。您可以选择只使用 Codable 支持的扩展、DefaultStorable 协议的扩展,或者两者都使用。(或者都不使用,这也是可以的)

功能

  • 直接读写符合 Codable 的自定义对象到 UserDefaults
  • 提供通过 DefaultStorable 的替代 API 到 UserDefaults

没有看到您需要的功能?

随时开启一个 Issue 请求您想要的功能或者发送一个 pull request!

为什么是默认值?

这个库将键值存储在默认值中,以常规方式容易出错,因为每次手动键入键的字符串值都可能导致输入错误,并且难以跟踪使用的键及其在 UserDefaults 中的存储情况。为存储在用户默认值中专门定义对象可以使跟踪存储在 UserDefaults 中的当前内容变得和搜索项目源代码中的 DefaultStorable 实例一样简单。使用专门的对象以存储在 UserDefaults 中的数据集可以使特定数据设置逻辑地组合在一起。

使用说明

DefaultStorable - 与 UserDefaults 交互的更好方法

您不必手动将密钥值添加到密钥存储中,也不必手动实现 NSCoding 并膨胀对象代码,只需简单地定义具有明确使用默认存储作为存储手段目的的默认对象。

正如遵守 Codable 可以让您免费获得很多好处一样,遵守 DefaultStorable 也是如此。**符合 DefaultStorable 的对象也必须符合 Codable

假设我们想将主题设置存储在 UserDefaults 中(这很合理,不是吗?),我们首先定义我们的符合 CodableDefaultStorable 的对象。

定义符合 DefaultStorable 的对象

struct VisualSettings: Codable, DefaultStorable {
    let themeName: String
    let backgroundImageURL: URL?
}

创建并将对象保存到 UserDefaults

let settings = VisualSettings(themeName: "bright", backgroundImageURL: URL(string: "https://..."))
settings.write()

如果你需要将数据保存在除默认键(类型名,在本例中是 "VisualSettings")之外的其他键下,可以通过为 write(withKey:) 提供 Optional 参数来实现。

let settings = VisualSettings(themeName: "bright", backgroundImageURL: URL(string: "https://..."))
settings.write(withKey: "someUniqueKey")

以后需要时再读取!

if let settings = VisualSettings.read() {
    // Do something
}

如果您在城市唯一的键下保存了默认值,则可以通过提供给 read(forKey:) 的可选参数来读取它。

if let settings = VisualSettings.read(forKey: "someUniqueKey") {
    // Do something
}

Swift 4 Codable 支持

此库提供了直接在 UserDefaults 中存储符合 Codable 协议的自定义对象的支持。 随着 Swift 4 的发布,引入了 Codable 协议,该协议提供对序列化对象的支持。 由于 UserDefaults 未更新以与 Swift 4 的 Codable 协议配合工作,因此如果需要将自定义对象直接保存到 UserDefaults,则该对象必须支持 NSCoding 并继承自 NSObject

// 1: Declare object (just conform to Codable, getting default encoder / decoder implementation for free)
struct VolumeSetting: Codable {
    let sourceName: String
    let value: Double
}

let setting = VolumeSetting(sourceName: "Super Expensive Headphone Amp", value: 0.4)
let key: String = String(describing: VolumeSetting.self)

// 2: Write
UserDefaults.standard.df.store(setting, forKey: key)

// 3: Read
UserDefaults.standard.df.fetch(forKey: key, type: VolumeSetting.self)

定制

如果 Default 的默认行为不符合您的需求,则可以替换任何默认实现细节。

常见的被覆盖属性有 defaultIdentifierdefaults

defaultIdentifier

defaultIdentifier 是您对象将被存储的键。默认情况下,它将保留要存储的对象的类型名。

  public static var defaultIdentifier: String {
        return String(describing: type(of: self))
    }

defaults

defaults 将返回您的应用将要存储默认对象的应用程序 UserDefaults 数据库。默认实现返回 UserDefaults.standard

    public static var defaults: UserDefaults {
        return UserDefaults.standard
    }

这个库是如何工作的?

UserDefaults 需要自定义的类型与 NSCoding 符合,并且是 NSObject 的子类。这样做可能有点耗时,并且符合 NSCoding 需要实现解码/编码方法,这需要一些代码来实现。好消息是 DataNSCoding 符合,所以如果你可以找到一种方法将你的对象转换为 Data,那么你就可以将其存储在 UserDefaults 中,《Swift 4 中的 Codable 协议》正是这样做的!这个库利用了 Swift 4 中引入的 Codable 协议。其工作方式是通过获取一个与 Codable 符合的对象,将其编码到一个 Data 对象中,该对象可以存储到 UserDefaults 中,然后当你要再次读取它时,只需使用 Codable 重新进行转换即可!

就这么简单!

安装

Carthage

如果你使用 Carthage 来管理你的依赖项,只需将 Default 添加到你的 Cartfile

github "Nirma/Default"

如果你使用 Carthage 来构建你的依赖项,请确保你已经将 Default.framework 添加到目标的 "Linked Frameworks and Libraries" 部分,并且已经在 Carthage 框架复制构建阶段中包含了 Default.framework

CocoaPods

如果您使用CocoaPods来管理依赖项,只需将Default添加到您的Podfile

pod 'Default'

需求

  • Xcode 9.0
  • Swift 4.0+

贡献

非常欢迎贡献!

许可证

Default是自由软件,可以在LICENSE文件中指定的条款下重新分配。