文档反馈官招募中，报名立赚积分兑换代金券！> HOT
文档中心>即时通信 IM>聊天互动（含 UI）>定义外观>HarmonyOS

HarmonyOS

最近更新时间：2025-11-17 11:28:42

我的收藏

本页目录：

TUIKit ArkUI 提供了强大的外观定制能力，支持自定义应用的主题模式（浅色/深色/跟随系统）和主题色。通过简单的配置，开发者可以轻松实现应用级别的主题切换和品牌色定制。
以消息列表为例，自定义主题模式和主题色的效果如下图所示：
浅色 + 默认颜色
浅色 + 橘黄色
深色 + 默认颜色
深色 + 绿色主题











核心能力

模式切换
浅色模式（Light）：适合日间使用的明亮界面。
深色模式（Dark）：适合夜间使用的暗色界面。
跟随系统（System）：自动跟随系统外观设置。
主题色定制
预设主题色：提供蓝、绿、红、橙等标准色。
自定义主题色：支持任意 Hex 格式颜色。
智能色板生成：自动生成 10 个色阶的完整色板。
清除自定义：一键恢复默认主题色。

API 说明

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

设置主题模式

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

设置主题色

方法
参数
返回值
说明
setPrimaryColor
string
void
设置主题色，需要 Hex 格式（例如 "#1C66E5"）。
clearPrimaryColor()
无
void
清除自定义主题色，恢复默认蓝色。
说明：
调用 setThemeMode 或 setPrimaryColor 后，配置会自动保存到 MMKV，无需手动保存。下次启动应用时会自动加载。
修改主题配置时会自动清除缓存，确保色彩方案实时更新。开发者无需关心缓存管理。
使用设置 API 时需避免频繁切换主题（例如在循环中调用）。

查询 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';

@Component
export 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。示例代码如下所示：
import { ThemeState} from '@tencentcloud/atomicx';

@Component
export struct SettingsView {
    @StorageLink('ThemeState') themeState: ThemeState = ThemeState.getInstance();
    build() {
      Column() {
        Button("修改主题颜色").onClick(() => {
          this.themeState.setPrimaryColor("#1C66E5")
        });
      }
    }
}

使用建议：
对于大多数应用，推荐使用 JSON 配置文件的方式，简单可靠且支持多端统一。
在整个应用中统一使用 themeState.colors 中的颜色，确保主题切换时界面保持一致。

常见问题

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

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")
中国站
目录