Only the Chinese version of this page is provided currently. The English version will be provided soon.
Help & Documentation>实时音视频>视频会议 SDK>含 UI 集成>UI 自定义>主题及语言（Web）

主题及语言（Web）

Last updated: 2026-03-30 17:40:41

On this page:

本文档介绍如何将 TUIRoomKit 的默认会议室界面调整为品牌专属配色，并配置多语言以支持海外客户。大多数场景下只需修改一两行代码即可完成主题切换或语言设置。本文从最简单的场景出发，逐步介绍各级定制能力。
内置亮色主题及中文效果展示

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

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


前提条件

确保您的项目已成功集成并可以正常打开会议房间。若尚未完成接入，请先参考 多人会议 > 快速接入。
理解 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>
层级
对应元素
亮色透明度
暗色透明度
主要（primary）
姓名、标题
90%
93%
次要（secondary）
状态、描述
55%
55%
辅助（tertiary）
提示、占位符
40%
30%

场景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);
说明：
以上代码放在 main.ts 里执行，确保在任何页面渲染之前生效。
完整的语言词条 Key 列表，您可以查阅依赖包中的 @tencentcloud/roomkit-web-vue3/es/i18n/zh-CN/index.mjs 文件，其中枚举了需要翻译的所有文案条目。
常用文案 key 前缀速查：
前缀
覆盖范围
Room.*
进退房、错误提示、确认弹窗等通用文案
Microphone.*
麦克风相关
Camera.*
摄像头相关
ScreenShare.*
屏幕共享
Setting.*
设置面板
Participant.*
成员列表
RoomNotifications.*
房间内的各类通知提示
RoomChat.*
聊天功能
RoomInvitation.*
房间邀请相关

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

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

步骤1：注册翻译资源

建议在应用启动时（例如 main.ts）集中完成注册，以确保该逻辑早于任何页面组件的渲染：
// main.ts
import { 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 });

步骤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 层统一管理主题和语言状态，用户在进入房间前完成界面语言设置，在进房后仍然生效。

常见问题

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

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

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

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

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

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

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

建议您在每次调用 setTheme 或 setLanguage 时，同步将状态写入 localStorage；并在 App.vue 初始化挂载时优先读取本地缓存：
const initialTheme = ref(localStorage.getItem('tuiRoom-theme') || 'light');
const initialLanguage = ref(localStorage.getItem('tuiRoom-language') || '');
中国站 - English