文档反馈官招募中，报名立赚积分兑换代金券！> HOT
文档中心>即时通信 IM>聊天互动（含 UI）>自定义 UI 组件>自定义 UI 组件（React）>UIKit 容器组件>UIKitProvider

UIKitProvider

最近更新时间：2025-09-12 18:14:53

我的收藏

本页目录：

介绍

UIKitProvider 是一个 React Context Provider，用于为整个应用提供 UI 组件的主题、国际化等全局状态管理。它是 UIKit 组件系统的核心，通过统一的 Context 为子组件提供一致的样式主题、多语言支持和组件配置。
该 Provider 具备以下特色：
主题管理：支持明暗主题切换和自定义主题色。
国际化支持：内置多语言支持，可扩展自定义语言包。

UIKitProvider 组件

Props 参数

参数
类型
默认值
描述
language
string | 'zh-CN' | 'en-US' | 'zh-TW' | 'ja-JP' | 'ko-KR' | 'auto'
'auto'
语言设置
languageResources
LanguageResource[]
[]
自定义语言资源
theme
'light' | 'dark'
'light'
主题设置

语言资源类型定义

interface LanguageResource {
  lng: string;
  translation: Record<string, any>;
}

useUIKit Hook

返回值

字段
类型
描述
language
string
当前语言
setLanguage
(lng: string) => void
设置语言方法
t
i18n['t']
国际化翻译函数
i18n
i18n
i18next 实例
theme
ThemeType
当前主题
setTheme
React.Dispatch<React.SetStateAction<ThemeType>>
设置主题方法

使用示例

基础用法

最简单的使用方式，为应用提供基础的主题和语言支持，由于 UIKitProvider 是基于 React Context 实现的，因此必须在子组件内使用 useUIkit。
import React from 'react';
import { UIKitProvider, useUIKit } from '@tencentcloud/chat-uikit-react';

function App() {
  return (
    <UIKitProvider theme="light" language="zh-CN">
      <ChildComponent />
    </UIKitProvider>
  );
}

function ChildComponent() {
  const { theme, language } = useUIKit();
  
  return (
    <div>
      <p>当前主题: {theme}</p>
      <p>当前语言: {language}</p>
    </div>
  );
}

export default App;

多语言支持

示例1：如何在 UIKitProvider 外切换语言

import React, { useState } from 'react';
import { UIKitProvider, useUIKit } from '@tencentcloud/chat-uikit-react';

// 自定义语言资源
const customLanguageResources = [
  {
    lng: 'de',
    translation: {
      'Hello': 'Hallo',
      'Welcome': 'Willkommen',
      'Settings': 'Einstellungen',
    }
  },
  {
    lng: 'fr',
    translation: {
      'Hello': 'Bonjour',
      'Welcome': 'Bienvenue',
      'Settings': 'Paramètres',
    }
  }
];

// 语言切换器组件（在 UIKitProvider 外部）
function LanguageSwitcher({ currentLanguage, onLanguageChange }) {
  const languages = [
    { code: 'zh-CN', name: '中文' },
    { code: 'en-US', name: 'English' },
    { code: 'de', name: 'Deutsch' },
    { code: 'fr', name: 'Français' },
  ];

  return (
    <div style={{ marginBottom: '20px', padding: '10px', border: '1px solid #ccc' }}>
      <h3>语言切换器（组件外）</h3>
      <p>当前语言: {currentLanguage}</p>
      <div>
        {languages.map(lang => (
          <button 
            key={lang.code}
            onClick={() => onLanguageChange(lang.code)}
            style={{ 
              margin: '0 8px',
              padding: '4px 8px',
              fontWeight: currentLanguage === lang.code ? 'bold' : 'normal',
              backgroundColor: currentLanguage === lang.code ? '#007bff' : '#f8f9fa',
              color: currentLanguage === lang.code ? 'white' : 'black',
              border: '1px solid #ccc',
              borderRadius: '4px',
              cursor: 'pointer'
            }}
          >
            {lang.name}
          </button>
        ))}
      </div>
    </div>
  );
}

// 内部组件（在 UIKitProvider 内部，可以使用 useUIKit）
function LanguageDemo() {
  const { language, t } = useUIKit();

  return (
    <div style={{ padding: '10px', border: '1px solid #ddd' }}>
      <h2>{t('Settings')}</h2>
      <p>{t('Welcome')}</p>
      <p>组件内检测到的语言: {language}</p>
    </div>
  );
}

// 主应用组件
function App() {
  // 在组件外管理语言状态
  const [currentLanguage, setCurrentLanguage] = useState('zh-CN');

  // 语言切换处理函数
  const handleLanguageChange = (newLanguage) => {
    console.log('切换语言到:', newLanguage);
    setCurrentLanguage(newLanguage);
  };

  return (
    <div>
      {/* 在 UIKitProvider 外部的语言切换器 */}
      <LanguageSwitcher 
        currentLanguage={currentLanguage}
        onLanguageChange={handleLanguageChange}
      />
      
      {/* UIKitProvider 接收外部的语言状态 */}
      <UIKitProvider 
        language={currentLanguage}
        languageResources={customLanguageResources}
      >
        <LanguageDemo />
      </UIKitProvider>
    </div>
  );
}

export default App;


示例2：如何在 UIKitProvider 内切换语言

import React from 'react';
import { UIKitProvider, useUIKit } from '@tencentcloud/chat-uikit-react';

// 自定义语言资源
const customLanguageResources = [
  {
    lng: 'de',
    translation: {
      'Hello': 'Hallo',
      'Welcome': 'Willkommen',
      'Settings': 'Einstellungen',
    }
  },
  {
    lng: 'fr',
    translation: {
      'Hello': 'Bonjour',
      'Welcome': 'Bienvenue',
      'Settings': 'Paramètres',
    }
  }
];

function App() {
  return (
    <UIKitProvider 
      language="zh-CN" 
      languageResources={customLanguageResources}
    >
      <LanguageDemo />
    </UIKitProvider>
  );
}

function LanguageDemo() {
  const { language, setLanguage, t } = useUIKit();

  const languages = [
    { code: 'zh-CN', name: '中文' },
    { code: 'en-US', name: 'English' },
    { code: 'de', name: 'Deutsch' },
    { code: 'fr', name: 'Français' },
  ];

  return (
    <div>
      <h2>{t('Settings')}</h2>
      <p>{t('Welcome')}</p>
      <p>当前语言: {language}</p>
      <div>
        {languages.map(lang => (
          <button 
            key={lang.code}
            onClick={() => setLanguage(lang.code)}
            style={{ 
              margin: '0 8px',
              fontWeight: language === lang.code ? 'bold' : 'normal'
            }}
          >
            {lang.name}
          </button>
        ))}
      </div>
    </div>
  );
}

export default App;

实践教程

1. 可以把 UIKitProvider 放到应用最外层。
// 在应用根部使用 UIKitProvider
function App() {
  return (
    <UIKitProvider theme="light" language="zh-CN">
      <Router>
        <Routes>
          <Route path="/" element={<Home />} />
          <Route path="/chat" element={<Chat />} />
        </Routes>
      </Router>
    </UIKitProvider>
  );
}
如果 UIKit 只是您应用的一小部分，您也可以只将 UIKitProvider 包裹在 UIKit 的外层。
import React from 'react';
import { UIKitProvider, ConversationList, Chat, ChatHeader, MessageList, MessageInput } from '@tencentcloud/chat-uikit-react';

function App() {
  return (
    <div className="app">
      {/* 你的普通业务代码 */}
      <header>应用导航</header>
      
      <main>
        <h1>欢迎页面</h1>
        <p>这里是普通的 React 组件</p>
        
        {/* 只在需要 UIKit 的地方局部包裹 */}
        <UIKitProvider theme="light" language="zh-CN">
          <ConversationList />
          <Chat>
            <ChatHeader />
            <MessageList />
            <MessageInput />
          </Chat>
        </UIKitProvider>
        
        <p>这里又是普通的业务代码</p>
      </main>
      
      {/* 你的普通业务代码 */}
      <footer>版权信息</footer>
    </div>
  );
}
2. 主题持久化。
function App() {
  const [theme, setTheme] = useState(() => {
    return localStorage.getItem('theme') || 'light';
  });

  useEffect(() => {
    localStorage.setItem('theme', theme);
  }, [theme]);

  return (
    <UIKitProvider theme={theme}>
      <AppContent />
    </UIKitProvider>
  );
}
3. 根据 HTML 的 lang 属性自动检测语言。
function App() {
  const [language, setLanguage] = useState(() => {
    const saved = localStorage.getItem('language');
    if (saved) return saved;
    
    // 自动检测浏览器语言
    const browserLang = navigator.language;
    if (browserLang.startsWith('zh')) return 'zh-CN';
    if (browserLang.startsWith('en')) return 'en-US';
    return 'auto';
  });

  return (
    <UIKitProvider language={language} languageResources={customResources}>
      <App />
    </UIKitProvider>
  );
}

注意事项

提供者位置：UIKitProvider 必须位于使用 useUIKit 的组件的上层。
语言资源：自定义语言资源会与内置资源合并，相同 key 会覆盖内置资源。
配置更新：配置更新是响应式的，会立即影响所有相关组件。
类型安全：使用 TypeScript 时，确保传入的配置符合类型定义。

相关文档

自定义组件 - UIKitProvider
自定义组件 - ConversationList
自定义组件 - MessageList
自定义组件 - MessageInput
自定义组件 - ContactList
自定义组件 - Search
chat-uikit-react npm
GitHub Demo

交流与反馈

如遇任何问题，可联系 官网售后 反馈，享有专业工程师的支持，解决您的难题。
中国站
目录