SettingsBundleBuilder

SettingsBundleBuilder 提供了一种简便的方式，使用类似 SwiftUI 的语法为 iOS 应用程序生成设置包。

动机

处理属性列表文件是一件麻烦事 - 您可能不知道每个设置项目需要哪些键/值。使用 SwiftUI 风格的语法，可以获得类型检查和自动完成的好处。您可以准确地知道 plist 中的错误在哪里，而无需运行应用程序并检查它。

此外，对于大型设置屏幕，属性列表的使用会变得困难。同样，SwiftUI 风格的语法大大改善了这一点，因为它更容易看到分层视图结构。

快速入门

在您现有的项目中本地添加一个新的 Swift Package。
通过更改 Package.swift 文件，使其列出以下内容而不是库，将 Swift Package 标记为可执行文件

products: [
    .executable(name: "PackageName", targets: ["PackageName"])
]

通过添加以下内容，将 SettingsBundleBuilder 添加为依赖项

.package(
    name: "SettingsBundleBuilder", 
    url: "https://github.com/benrobinson16/SettingsBundleBuilder.git", 
    from: "1.0.0"
)

不要忘记在包的主目标中也添加 "SettingsBundleBuilder" 作为依赖项。

在 main.swift 中，使用 makeSettingsBundle 方法创建您的设置包。一个简单的例子

import SettingsBundleBuilder

makeSettingsBundle {
    Group("Main settings:") {
        TextField("Name", key: "username")
        Toggle("Personalized features", key: "personalization", defaultValue: false)
    }
}

运行 Swift Package（⌘ + R），它将生成设置包并在 Finder 窗口中打开它。将其拖到您的主项目中，您就可以开始了！

使用示例

下面是一个复杂的设置包示例，使用了包中的每个 SettingsBundleItem

import SettingsBundleBuilder

makeSettingsBundle {
    Group("Main settings:") {
        TextField("Name", key: "username")
        MultiValue(
            "Background music",
            key: "background_music",
            defaultValue: "ocean",
            possibleValues: ["ocean", "forest", "city", "cafe", "river"],
            readableVersions: ["Ocean", "Forest", "Bustling city", "Quiet cafe", "Gentle stream"]
        )
    }
    
    RadioGroup(
        "Color scheme:",
        key: "color_scheme",
        defaultValue: "blue",
        possibleValues: ["blue", "red", "green"],
        readableVersions: ["Blue", "Red", "Green"]
    )
    
    Group("Info") {
        Text("App name", constantValue: "My app")
        Text("App version", key: "version", defaultValue: "1.0.0")
        Page("Advanced") {
            Toggle("Experimental features", key: "experimental_features", defaultValue: false)
            Slider(key: "opacity", defaultValue: 50.0, min: 0.0, max: 100.0)
        }
        Page("Secrets", filename: "Secrets") {
            Text("This page needs a persistent name", constantValue: "because we will edit it manually")
        }
    }
}

SettingsBundleItem

此软件包中提供了许多项目，每个项目用于在设置页面上呈现特定的单元格。

以下是一些项目中常用的属性

title - 向用户显示的描述此设置/项目的字符串
key - 当此设置更改时要更改的 UserDefaults 键
defaultValue - 当在 UserDefaults 中找不到键时提供给 UI 的值

还有许多其他参数，但这些参数相当简单，并使用 Xcode 的文档工具进行了记录。要访问文档，请使用 command + click 单击方法/类型。

完整的项目列表是

Group
MultiValue
Page
RadioGroup
Slider
Text
TextField
Toggle

MultiValue, RadioGroup 和 Text

MultiValue、RadioGroup 和 Text 项目使用不同的策略向用户显示文本。为此，它们使用以下属性

possibleValues - 可以存储在 UserDefaults 中提供的键的可能字符串值
readableValues - possibleValues 到人类可读版本的映射；此数组应与可能的值的顺序相同

对于 MultiValue 和 RadioGroup，这用于显示用户可以选择的值列表。

对于 Text，这用于基于 UserDefaults 中的值显示动态内容。

Groups

Group 提供了一种组织多个项目的方法。可选择提供标题和页脚文本。

请注意，组不能相互嵌套。 RadioGroup 项目在 UI 中充当组，因此不能放置在 Group 中。

注意：如果一个非组项目在 Group 之后放置在根级别，由于 .plist 设置包的格式，它将出现在 UI 中的组中。为避免这种情况，请将此项目嵌入到一个组中。

Pages

Page 可以提供嵌套的设置页面。只需提供 title 和 content。 您还可以选择提供 filename

为了清晰起见，可以将代码分开，使用类似于以下的代码

@SettingsBundleBuilder
func mySecondPage() -> [SettingsBundleItem] {
    // second page content
}

makeSettingsBundle {
    Group("My Group") {
        Page("2nd page", content: mySecondPage)
    }
}

未来改进

未来我可能会对这个软件包进行的改进包括

支持本地化字符串
支持 SupportedUserInterfaceIdioms 以更改 iOS 和 iPadOS 的设置包
能够为 Slider 添加 MinimumValueImage 和 MaximumValueImage

法律

请参阅 LICENSE.md 了解许可证详细信息。