即时通信 IM HarmonyOS（定义外观）

一、核心能力

模式切换

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

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

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

主题色定制

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

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

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

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

二、API 说明

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

三、设置主题模式

方法	参数	返回值	说明
setThemeMode	ThemeMode	void	设置显示模式，自动保存并刷新。ThemeMode.system：跟随系统外观。ThemeMode.light：强制使用浅色模式。ThemeMode.dark：强制使用深色模式。

四、设置主题色

方法	参数	返回值	说明
setPrimaryColor	string	void	设置主题色，需要 Hex 格式（例如 "#1C66E5"）。
clearPrimaryColor()	无	void	清除自定义主题色，恢复默认蓝色。

注意：说明：

五、查询 ThemeState 信息

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

属性	类型	说明
currentMode	ThemeMode	当前主题模式。
currentPrimaryColor	string	当前主题色（Hex 格式）。
hasCustomPrimaryColor	boolean	是否设置了自定义主题色。
isDarkMode	boolean	当前是否为深色模式。

六、使用方式

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

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

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

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

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

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

1. 下载配置文件。

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

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" }}

配置选项说明

参数说明	类型	可选值	说明
mode	string	"system"、"light"、"dark"	主题模式
primaryColor	string	Hex 颜色值，例如 "#0ABF77"	主题色

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

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

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

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

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

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

import { ThemeState} from '@tencentcloud/atomicx';@Componentexport struct SettingsView { @StorageLink('ThemeState') themeState: ThemeState = ThemeState.getInstance(); build() { Column() { Button("跟随系统").onClick(() => { this.themeState.setThemeMode(ThemeMode.system); }); Button("浅色模式").onClick(() => { this.themeState.setThemeMode(ThemeMode.light); }); Button("深色模式").onClick(() => { this.themeState.setThemeMode(ThemeMode.dark); }); } }}

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

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

注意：使用建议：

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

if (this.themeState.currentMode == ThemeMode.dark) { // 当前应用内主题指定为 “深色模式”} else if (this.themeState.currentMode == ThemeMode.light) { // 当前应用内主题指定为 “浅色模式”} else { // 当前应用内主题指定为 “跟随系统模式” if (this.themeState.isDarkMode) { // 跟随系统，应用内也使用和系统一致的深色模式 } else { // 跟随系统，应用内也使用和系统一致的浅色模式 } }

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

不支持。主题色只支持 6 位 Hex 格式（RGB），不支持 8 位格式（RGBA）。

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

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

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

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

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

@StorageLink('ThemeState') themeState: ThemeState = ThemeState.getInstance();console.info("模式: " + this.themeState.currentMode)console.info("主题色: "+ this.themeState.currentPrimaryColor)

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

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

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

浅色 + 默认颜色	浅色 + 橘黄色	深色 + 默认颜色	深色 + 绿色主题