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

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

一、核心能力

模式切换

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

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

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

主题色定制

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

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

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

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

二、API 说明

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

三、设置主题模式

四、设置主题色

注意：说明：

五、查询 ThemeState 信息

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

六、使用方式

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

七、配置项目

首先需要在你的应用的主入口使用 ComponentTheme 包装，并在 MaterialApp 中做如下配置，可以参考 demo 实现：

@override Widget build(BuildContext context) { return ComponentTheme( child: MultiProvider( providers: [ ChangeNotifierProvider.value(value: LocaleProvider()), ], child: Builder(builder: (context) { final themeState = BaseThemeProvider.of(context); final isDarkMode = themeState.isDarkMode; // …… 省略其他配置 return MaterialApp( themeMode: isDarkMode ? ThemeMode.dark : ThemeMode.light, // …… 省略其他配置 ); }), ), );

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

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

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

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

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

1. 下载配置文件。

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

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 拖入你的项目中。以 GitHub 开源 Demo TUIKit Flutter 项目为例，appConfig.json 位于 demo 的 assets 文件夹下：

并在项目的 pubspec.yaml 文件中配置 assets 资源：

assets: – assets/

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

请在你的应用启动时设置 JSON 文件路径，加载配置文件。

class _MyAppState extends State<MyApp> { bool _isInitialized = false; @override void initState() { super.initState(); _initializeApp(); } Future<void> _initializeApp() async { await StorageUtil.init(); await AppBuilder.init(configPath: 'packages/uikit_next/assets/appConfig.json'); if (mounted) { setState(() { _isInitialized = true; }); } }}

至此，启动 App 后，TUIKit Flutter 组件的模式和主题色会自动显示成你在 appConfig.json 中设置的值。

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

你可以通过 API setThemeMode 直接设置主题模式。示例代码如下所示：

val themeState = ThemeState.sharedColumn { Button(onClick = { themeState.setThemeMode(ThemeMode.SYSTEM) }) { Text(text = "跟随系统") } Button(onClick = { themeState.setThemeMode(ThemeMode.LIGHT) }) { Text(text = "浅色模式") } Button(onClick = { themeState.setThemeMode(ThemeMode.DARK) }) { Text(text = "深色模式") }}

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

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

final themeState = BaseThemeProvider.of(context);themeState.setPrimaryColor('#1C66E5');

注意：使用建议：

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

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

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

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

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

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

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

存储在应用的持久化存储中。应用卸载后会丢失，重新安装后恢复默认配置。

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

final themeState = BaseThemeProvider.of(context);final config = themeState.currentTheme;print("模式: ${config.type}");print("主题色: ${config.primaryColor ?? "默认"}");

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

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

themeState.setThemeMode(ThemeType.DARK)themeState.setPrimaryColor("#0ABF77")