即时通信 IM iOS（SwiftUI）（定义外观）

以消息列表为例，自定义主题模式和主题色的效果如下：

一、核心能力

模式切换

·浅色模式（Light）：适合日间使用的明亮界面。

·深色模式（Dark）：适合夜间使用的暗色界面。

·跟随系统（System）：自动跟随系统外观设置。

主题色定制

·预设主题色：提供蓝、绿、红、橙等标准色。

·自定义主题色：支持任意 Hex 格式颜色。

·智能色板生成：自动生成 10 个色阶的完整色板。

·清除自定义：一键恢复默认主题色。

二、API 说明

以上功能基于 ThemeState 提供的一组简洁的 API，用于主题配置和信息查询。

三、设置主题模式

四、设置主题色

注意：说明：

注意：1. 调用 setThemeMode 或 setPrimaryColor 后，配置会自动保存到 UserDefaults，无需手动保存。下次启动应用时会自动加载。

注意：2. 修改主题配置时会自动清除缓存，确保色彩方案实时更新。开发者无需关心缓存管理。

注意：3. 使用设置 API 时需避免频繁切换主题（例如在循环中调用）。

五、查询 ThemeState 信息

通过以下只读属性可以查询当前的主题配置状态和信息：

六、使用方式

本章节介绍如何在你的应用中集成和使用主题、主题色定制功能，按照从简单到复杂的顺序提供三种方式。

七、方式一：使用 AppBuilder 配置（推荐）

AppBuilder 是一个便捷式功能及 UI 自定义配置工具，通过 JSON 配置文件统一管理，适用于 Web + Native 双端应用需要保持统一外观的场景。

你可以在 Chat Web 体验馆 体验 AppBuilder 功能，体验入口：

虽然 Chat Web 体验馆上暂时无法实时观看移动端的配置效果，但移动端已经预先支持了 AppBuilder 的配置能力。

接下来为你介绍在 Web 体验馆设置 AppBuilder 后，如何在移动端项目中应用该自定义配置。操作步骤比较简单，只有 3 步：

1. 下载配置文件。

2. 将配置文件 appConfig.json 拖入你的 iOS 项目中。

3. 在应用启动时加载配置文件。

八、步骤1：下载配置文件

访问 Chat Web 体验馆，下载配置文件 appConfig.json。下载路径为：

appConfig.json文件内容如下所示，与 AppBuilder 页面的配置项一一对应，与定义外观相关的配置是 theme及其子字段：

{ "theme": { "mode": "light", // 主题模式，light-浅色模式，dark-深色模式，system-自动跟随系统 "primaryColor": "#E65100" // 主色调，16 进制颜色值 }, "messageList": { "alignment": "two-sided", "enableReadReceipt": false, "messageActionList": [ "copy", "recall", "quote", "forward", "delete" ] }, "conversationList": { "enableCreateConversation": true, "conversationActionList": [ "delete", "mute", "pin", "markUnread" ] }, "messageInput": { "hideSendButton": false, "attachmentPickerMode": "collapsed" }, "search": { "hideSearch": false }, "avatar": { "shape": "circular" }}

配置选项说明

九、步骤2：将配置文件拖入项目中

将 appConfig.json 拖入你的项目中，确保选择了正确的 Target，以及正常勾选了 Copy Bundle Resources。

以 GitHub 开源 Demo TUIKit iOS SwiftUI 项目为例，appConfig.json 位于 demo/ChatDemo 的主 bundle 下：

十、步骤3：加载配置文件

请在你的应用启动时设置 JSON 文件路径，加载配置文件。如果你将 appConfig.json 也放置在应用的主 bundle 中，你可以像这样获取到 JSON 文件：

import AtomicX@mainstruct MyApp: App { init() { // 加载主题配置文件 if let path = Bundle.main.path(forResource: "appConfig", ofType: "json") { AppBuilderHelper.setJsonPath(path: path) } } var body: some Scene { WindowGroup { ContentView() // 将 ThemeState.shared 注入应用的根视图下 .environmentObject(ThemeState.shared) } }}

至此，无需编写额外代码，启动 App 后，TUIKit SwiftUI 组件的模式和主题色会自动显示成你在 appConfig.json 中设置的值。

十一、方式二：代码设置主题模式

你可以通过 API setThemeMode 直接设置主题模式，其中的 themeState 是从环境变量中获取的 ThemeState.shared 单例对象。示例代码如下所示：

import SwiftUIimport AtomicXstruct SettingsView: View { @EnvironmentObject var themeState: ThemeState var body: some View { List { Section("外观模式") { Button("跟随系统") { themeState.setThemeMode(.system) } Button("浅色模式") { themeState.setThemeMode(.light) } Button("深色模式") { themeState.setThemeMode(.dark) } } } .navigationTitle("设置") }}

十二、方式三：代码设置主题色

你可以通过 API setPrimaryColor 设置主题色，只需要传入一个主颜色值，整个 TUIKit SwiftUI 组件会自动根据该主颜色值，为不同的组件适配出一组相同色系里的相似色值渲染界面，你无需再手动适配界面 UI。示例代码如下所示：

struct CustomColorPicker: View { @EnvironmentObject var themeState: ThemeState @State private var customColor = "#1C66E5" var body: some View { VStack(spacing: 20) { TextField("输入颜色值", text: $customColor) .textFieldStyle(RoundedBorderTextFieldStyle()) .placeholder(when: customColor.isEmpty) { Text("#1C66E5").foregroundColor(.gray) } Button("应用主题色") { themeState.setPrimaryColor(customColor) } .disabled(!isValidHexColor(customColor)) } .padding() } private func isValidHexColor(_ hex: String) -> Bool { let pattern = "^#[0-9A-Fa-f]{6}$" return hex.range(of: pattern, options: .regularExpression) != nil }}

注意：使用建议：

十四、如何判断当前是否为深色模式？

if themeState.isDarkMode { // 当前是深色模式} else { // 当前是浅色模式}

十五、如何在设置主题色后立即看到效果？

主题色设置后会自动刷新 UI，因为 ThemeState 是 ObservableObject。确保你的视图使用了 @EnvironmentObject 或 @ObservedObject 来观察状态变化。

十六、可以设置透明度吗？

不支持。主题色只支持 6 位 Hex 格式（RGB），不支持 8 位格式（RGBA）。如需透明效果，请在使用颜色时添加 .opacity() 修饰符。

十七、如何恢复默认主题？

themeState.clearPrimaryColor() // 清除自定义主题色themeState.setThemeMode(.system) // 恢复跟随系统

十八、主题配置存储在哪里？

存储在 UserDefaults 中，key 为 "BaseComponentThemeKey"。应用卸载后会丢失，重新安装后恢复默认配置。

十九、如何获取当前主题的完整配置？

let config = themeState.currentThemeprint("模式: \\(config.mode)")print("主题色: \\(config.primaryColor ?? "默认")")

20、可以同时设置模式和主题色吗？

可以分别调用两个方法，系统会自动合并配置：

themeState.setThemeMode(.dark)themeState.setPrimaryColor("#0ABF77")