UIKitProvider

介绍
UIKitProvider 是一个 React Context Provider，用于为整个应用提供 UI 组件的主题、国际化等全局状态管理。它是 UIKit 组件系统的核心，通过统一的 Context 为子组件提供一致的样式主题、多语言支持和组件配置。
该 Provider 具备以下特色：
主题管理 - 支持明暗主题切换和自定义主题色
国际化支持 - 内置多语言支持，可扩展自定义语言包
UIKitProvider 组件
Props 参数
参数
类型
默认值
描述
language
string
'auto'
语言设置
languageResources
LanguageResource[]
[]
自定义语言资源
theme
'light' | 'dark'
'light'
主题设置
类型定义
interface UIKitProviderProps {
  language?: string;
  languageResources?: LanguageResource[];
  theme?: 'light' | 'dark';
}
语言资源类型定义
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>>
设置主题方法
使用示例
基础使用
最简单的使用方式，为应用提供基础的主题和语言支持：
import React from 'react';
import { UIKitProvider, useUIKit } from '@tencentcloud/chat-uikit-react';
﻿
function App() {
  return (
    <UIKitProvider theme="light" language="zh-CN">
      <ChatApp />
    </UIKitProvider>
  );
}
﻿
function ChatApp() {
  const { theme, language } = useUIKit();
  
  return (
    <div>
      <p>当前主题: {theme}</p>
      <p>当前语言: {language}</p>
    </div>
  );
}
﻿
export default App;
主题切换
展示如何实现主题切换功能：
import React from 'react';
import { UIKitProvider, useUIKit } from '@tencentcloud/uikit-base-component-react';
﻿
function App() {
  return (
    <UIKitProvider theme="light">
      <ThemeDemo />
    </UIKitProvider>
  );
}
﻿
function ThemeDemo() {
  const { theme, setTheme } = useUIKit();
﻿
  const toggleTheme = () => {
    setTheme(theme === 'light' ? 'dark' : 'light');
  };
﻿
  return (
    <div>
      <h2>主题切换示例</h2>
      <p>当前主题: {typeof theme === 'string' ? theme : `${theme.mode} (${theme.primaryColor})`}</p>
      <button onClick={toggleTheme}>
        切换到 {theme === 'light' ? '暗色' : '亮色'} 主题
      </button>
    </div>
  );
}
﻿
export default App;
多语言支持
展示如何使用多语言功能：
import React from 'react';
import { UIKitProvider, useUIKit } from '@tencentcloud/uikit-base-component-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
function App() {
  return (
    <UIKitProvider theme="light" language="zh-CN">
      <Router>
        <Routes>
          <Route path="/" element={<Home />} />
          <Route path="/chat" element={<Chat />} />
        </Routes>
      </Router>
    </UIKitProvider>
  );
}
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. 语言检测
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>
  );
}
注意事项
1. 提供者位置: UIKitProvider 必须位于使用 useUIKit 的组件的上层。
2. 主题切换: 主题切换会触发 CSS 变量更新，可能影响性能。
3. 语言资源: 自定义语言资源会与内置资源合并，相同 key 会覆盖内置资源。
4. 配置更新: 配置更新是响应式的，会立即影响所有相关组件。
5. 类型安全: 使用 TypeScript 时，确保传入的配置符合类型定义。
参数	类型	默认值	描述
language	string	'auto'	语言设置
languageResources	LanguageResource[]	[]	自定义语言资源
theme	'light' \| 'dark'	'light'	主题设置
字段	类型	描述
language	string	当前语言
setLanguage	(lng: string) => void	设置语言方法
t	i18n['t']	国际化翻译函数
i18n	i18n	i18next 实例
theme	ThemeType	当前主题
setTheme	React.Dispatch<React.SetStateAction<ThemeType>>	设置主题方法