即时通信 IM 主题及语言（Web）

·内置亮色主题及中文效果展示

·内置暗色主题及英文效果展示

·自定义清新绿主题，新增日文效果展示

一、前提条件

·确保你的项目已成功集成并可以正常打开会议房间。若尚未完成接入，请先参考 多人会议 > 快速接入。

·理解 UIKitProvider 的作用：它是主题和语言功能的统一容器，必须包裹在应用的最外层。在其子节点任意位置进行的主题或语言配置，均会在整个应用范围内生效。

若业务项目的 App.vue 中尚未添加该容器，可参考以下代码进行初始化配置：

<template> <UIKitProvider :theme="initialTheme" :language="initialLanguage"> <router-view /> </UIKitProvider></template><script setup lang="ts">import { ref } from 'vue';import { UIKitProvider } from '@tencentcloud/uikit-base-component-vue3';// 读取用户上次的偏好设置；若无记录，则默认使用亮色，语言跟随浏览器设置const initialTheme = ref(localStorage.getItem('tuiRoom-theme') || 'light');const initialLanguage = ref(localStorage.getItem('tuiRoom-language') || '');</script>

注意：说明：

注意：initialLanguage 传空字符串时，UIKitProvider 会自动读取浏览器语言，中文环境显示中文，英文环境显示英文，无需额外配置。

三、场景1：切换亮色 / 暗色模式

RoomKit 内置了亮色（light）和暗色（dark）两套完整的配色方案。你只需通过 UIKitProvider 的 theme 属性传入对应的值即可实现切换：

<UIKitProvider theme="dark"> <ConferenceMainView /></UIKitProvider><script setup>import { UIKitProvider } from '@tencentcloud/uikit-base-component-vue3';import { ConferenceMainView } from '@tencentcloud/roomkit-web-vue3';</script>

如需在应用运行期间提供主题切换能力，可在任意子组件中调用 useUIKit() API：

import { useUIKit } from '@tencentcloud/uikit-base-component-vue3';const { theme, setTheme } = useUIKit();function toggleTheme() { const next = theme.value === 'dark' ? 'light' : 'dark'; setTheme(next); // 建议写入 localStorage，以便用户下次打开页面时自动恢复偏好 localStorage.setItem('tuiRoom-theme', next);}

四、场景2：自定义品牌色

如果默认配色无法满足你的产品品牌需求，你可以传入一个十六进制颜色值作为核心品牌色。RoomKit 会自动以该颜色为基准，推导出完整的 10 级色阶，并统一覆盖界面内的所有按钮、链接、选中态及高亮等交互元素。

<UIKitProvider :theme="{ themeStyle: 'light', primaryColor: '#FF6B35' }"> <ConferenceMainView /></UIKitProvider>

注意：颜色格式必须是 #RRGGBB 的标准 6 位十六进制，不支持 #RGB、rgb()、hsl() 等其他写法。

如需动态更新品牌色，可调用 setTheme() 完成：

const { setTheme } = useUIKit();setTheme({ themeStyle: 'light', primaryColor: '#07C160' });

五、场景3：自定义背景色

当品牌设计稿的背景色并非标准黑白，而是带有特定色调（如浅灰、深蓝）时，你无需逐一调整各个模块。只需传入 backgroundColor，UIKitProvider 将自动遵循当前模式的明暗层级规则，推导出顶栏、底栏、弹窗、输入框等多达 10 个区域的背景色。

<UIKitProvider :theme="{ themeStyle: 'dark', backgroundColor: '#1a1a2e' }"> <ConferenceMainView /></UIKitProvider>

六、场景4：自定义文字色

若设计规范要求文字使用特定颜色（例如深蓝色），你可以传入 textColor 属性。RoomKit 会以此为基础，自动生成深浅三级文字色，并分别应用于标题、描述、提示等不同层级的文本：

<UIKitProvider :theme="{ themeStyle: 'light', textColor: '#1a2742' }"> <ConferenceMainView /></UIKitProvider>

七、场景5：替换内置的主题切换按钮

RoomKit PC 端顶栏左侧默认提供了一个主题切换按钮。若你希望将其替换为自定义的 UI 组件，需先将内置按钮隐藏，随后注册你自己的组件实现。

八、步骤1：隐藏内置【切换主题】按钮

import { conference, BuiltinWidget } from '@tencentcloud/roomkit-web-vue3';conference.setWidgetVisible({ [BuiltinWidget.ThemeWidget]: false });

九、步骤2：注册自定义主题切换组件

import { conference } from '@tencentcloud/roomkit-web-vue3';import MyThemeToggle from './MyThemeToggle.vue';conference.registerWidget({ id: 'my-theme-toggle', zone: { pc: 'top-left' }, // 指定 MyThemeToggle 自定义组件渲染的位置 component: MyThemeToggle,});

自定义组件内部通过 useUIKit() 调用设置主题的 API 即可：

<!– MyThemeToggle.vue –><script setup lang="ts">import { useUIKit } from '@tencentcloud/uikit-base-component-vue3';const { theme, setTheme } = useUIKit();const toggle = () => { const next = theme.value === 'dark' ? 'light' : 'dark'; setTheme(next); localStorage.setItem('tuiRoom-theme', next);};</script><template> <button @click="toggle">{{ theme === 'dark' ? '黑暗主题' : '明亮主题' }}</button></template>

注意：说明：

注意：ConferenceMainViewH5（移动端视图）不包含内置的主题切换按钮。推荐在 App.vue 层统一管理主题和语言状态，用户在进入房间前完成界面语言设置，在进房后仍然生效。

十、综合示例：应用全套品牌定制

若你的设计稿包含完整的品牌色体系，你可以将多个配置项合并在一个对象中集中传入：

<template> <UIKitProvider :theme="customTheme" :language="lang"> <ConferenceMainView /> </UIKitProvider></template><script setup lang="ts">import { ref } from 'vue';import { UIKitProvider } from '@tencentcloud/uikit-base-component-vue3';import { ConferenceMainView } from '@tencentcloud/roomkit-web-vue3';const customTheme = ref({ themeStyle: 'light', primaryColor: '#07C160', // 活力绿，覆盖所有按钮、链接、选中态 backgroundColor: '#F2FAF5', // 微绿调背景，自动推导顶栏/弹窗/输入框等层级 textColor: '#122B1C', // 深林绿文字，自动派生主/次/三级层级});const lang = ref('zh-CN');</script>

十二、场景1：指定初始语言

通过在 UIKitProvider 上传入 language 属性，你可以直接指定界面的显示语言。RoomKit 目前内置支持 'zh-CN'（简体中文）和 'en-US'（英文）：

<UIKitProvider language="en-US"> <ConferenceMainView /></UIKitProvider>

注意：说明：

注意：若不传递该参数，RoomKit 默认会自动探测并使用浏览器语言环境。

十三、场景2：运行时切换语言

若应用需要提供语言切换功能，在任意子组件中调用 setLanguage() 即可，界面文案会即时响应更新：

import { useUIKit } from '@tencentcloud/uikit-base-component-vue3';const { language, setLanguage } = useUIKit();function toggleLanguage() { const nextLang = language.value === 'zh-CN' ? 'en-US' : 'zh-CN'; setLanguage(nextLang); // 建议记录用户偏好，下次打开时自动恢复 localStorage.setItem('tuiRoom-language', nextLang);}

十四、场景3：局部修改或替换界面文案

在一些场景下，你可能并不需要切换整体语言，而是希望将部分默认文案替换为具有特定业务属性的词汇。例如：将“房间”改为“频道”，将“成员”改为“参会人”。你无需创建全新的语言包，只需覆盖对应的词条 Key 即可：

import { i18next } from '@tencentcloud/uikit-base-component-vue3';i18next.addResourceBundle('zh-CN', 'translation', { 'Room.TemporaryMeeting': '的临时频道', // 原来是"的临时房间" 'Room.End': '结束会议', // 原来是"结束" 'Participant.Title': '参会人', // 原来是"成员"}, true, true);

注意：说明：

常用文案 key 前缀速查：

十五、场景4：扩展全新语种支持

如果你的产品需要支持日语、韩语等更多语言市场，你可以先通过 i18next.addResourceBundle() 注册全新的翻译资源，随后调用 setLanguage() 即可完成语种切换。

十六、步骤1：注册翻译资源

建议在应用启动时（例如 main.ts）集中完成注册，以确保该逻辑早于任何页面组件的渲染：

// main.tsimport { i18next } from '@tencentcloud/uikit-base-component-vue3';i18next.addResourceBundle('ja-JP', 'translation', { 'Room.End': '終了', 'Room.LeaveRoom': '退室', 'Microphone.Mute': 'ミュート', 'Camera.Start': 'カメラON', // 请参考 zh-CN 的完整词条列表补充其余 Key…}, true, false);

注意：说明：

注意：完整的语言词条 Key 列表，你可以查阅依赖包中的 @tencentcloud/roomkit-web-vue3/es/i18n/zh-CN/index.mjs 文件，其中枚举了需要翻译的所有文案条目。

十七、步骤2：切换至新语言

资源注册完成后，你可以在 <UIKitProvider> 任意子组件中通过 useUIKit() 调用 setLanguage()完成动态切换：

import { useUIKit } from '@tencentcloud/uikit-base-component-vue3';const { setLanguage } = useUIKit();// 切换为日文setLanguage('ja-JP');// 建议同步写入 localStorage，以便用户下次打开页面时自动恢复偏好localStorage.setItem('tuiRoom-language', 'ja-JP');

十八、场景5：替换内置的语言切换按钮

RoomKit PC 端界面的顶栏右侧默认配置了「中文 / English」的语言切换功能。若你希望将其替换为自定义的 UI 组件，需先将内置按钮隐藏，随后注册你自己的组件实现。

十九、步骤1：隐藏内置【切换语言】按钮

import { conference, BuiltinWidget } from '@tencentcloud/roomkit-web-vue3';// 隐藏内置按钮conference.setWidgetVisible({ [BuiltinWidget.LanguageWidget]: false });

20、步骤2: 注册自定义语言切换组件

import { conference } from '@tencentcloud/roomkit-web-vue3';import MyLanguageToggle from './MyLanguageToggle.vue';// 注册自定义组件conference.registerWidget({ id: 'my-language-toggle', zone: { pc: 'top-right' }, // 指定 MyLanguageToggle 自定义组件渲染的位置 component: MyLanguageToggle,});

自定义组件内部通过 useUIKit() 调用设置语言的 API 即可：

<!– MyLanguageToggle.vue –><script setup lang="ts">import { useUIKit } from '@tencentcloud/uikit-base-component-vue3';const { language, setLanguage } = useUIKit();const toggleLanguage = () => { // 判断当前语言并切换到另一种语言 const nextLang = language.value === 'zh-CN' ? 'en-US' : 'zh-CN'; setLanguage(nextLang); // 写入 localStorage，确保用户刷新页面后语言偏好依然生效 localStorage.setItem('tuiRoom-language', nextLang);};</script><template> <button @click="toggleLanguage"> {{ language === 'zh-CN' ? 'English' : '中文' }} </button></template>

注意：说明：

注意：ConferenceMainViewH5（移动端视图）不包含内置的语言切换按钮。推荐在 App.vue 层统一管理主题和语言状态，用户在进入房间前完成界面语言设置，在进房后仍然生效。

22、配置了 primaryColor，但界面的按钮颜色未发生变化？

按钮颜色未发生变化通常是由于颜色格式不符合要求。primaryColor 仅接受 #RRGGBB 格式的 6 位十六进制字符串（例如 #FF6B35），不支持 #RGB、rgb()、hsl() 等其他格式

23、调用 setLanguage() 后，界面上部分文字没有随之切换？

未发生变化的文字通常属于业务动态数据。例如你传入的“房间名称（roomName）”、“用户昵称（userName）”等。这类属于用户生成内容或通过接口获取的业务侧数据，不在 RoomKit 的静态多语言词典管理范围内，需由你在业务侧自行维护多语言状态。

24、注册了全新的语言包，但调用 setLanguage('ja-JP') 后不生效？

请确保 i18next.addResourceBundle() 或组件绑定的执行时机早于 setLanguage() 的调用。我们强烈建议将语言包的注册逻辑统一放在 main.ts 初始化阶段完成。

25、刷新页面后，之前设置的主题和语言都恢复成了默认状态？

建议你在每次调用 setTheme 或 setLanguage 时，同步将状态写入 localStorage；并在 App.vue 初始化挂载时优先读取本地缓存：

const initialTheme = ref(localStorage.getItem('tuiRoom-theme') || 'light');const initialLanguage = ref(localStorage.getItem('tuiRoom-language') || '');