主題與國際化

統一編輯器外觀、深色模式與語言資源。

主題與國際化是共享的執行時服務。六個產品使用同一套主題服務、語言資源和區域配置,自定義外掛讀取的也是這些狀態。品牌外觀和使用者偏好在應用執行期間可以修改,內容自身儲存的資料和樣式不受影響。

SDK 內建 19 個介面語言與地區選項 和 7 套主題色板。六個產品共用外觀、語言和區域配置,自定義主題和業務翻譯也使用同一套服務。

同一套狀態驅動介面與渲染

ThemeService 將完整色板與深色模式狀態分開儲存,變化分別透過 currentTheme$ 和 darkMode$ 釋出。介面將色板展開為 --univer-* CSS 變數,並響應 univer-dark 類;渲染器訂閱同一個服務,將受影響的元件標記為需要重繪。Canvas 的顏色服務負責解析 Token、為深色顯示對映顏色,並快取結果。

本章的配置和範例以 @univerjs/*、@univerjs-pro/* 1.2.0 為準。應用中各 SDK 依賴的版本應保持一致。

設定可選值與範圍執行時 API
theme7 套內建色板,或完整的自定義 Theme。setTheme()
darkModetrue / false,預設 false;與色板相互獨立。toggleDarkMode()
locale19 個內建 LocaleType 值;需先載入對應資源。setLocale()
locales按語言標識合併的產品、功能外掛和應用翻譯資源。loadLocales()
region同一組 LocaleType 值;未顯式設定時跟隨介面語言。setRegion()
directionltr / rtl,預設 ltr;僅影響選單等介面 UI,Canvas 內容區尚不支援 RTL。setDirection()
100%

從完整色板建立品牌主題

@univerjs/themes 提供 primary、gray、各功能色階、loop-color 和 highlight.background。建置自定義主題時,複製一份內建主題,替換需要修改的分支,並保留完整結構。setTheme() 替換整份主題,不會深度補齊區域性物件。下面的範例提供了一組連續的紫色品牌色階。

7 套內建色板分別是 blueTheme、darkBlueTheme、greenTheme、orangeTheme、purpleTheme、redTheme 和 yellowTheme。

defaultTheme 是 blueTheme 的別名。色板與深色模式分別選擇。可配置的分支如下:

主題分支可設定選項
primary品牌色 10 級:50,以及 100 至 900。
gray中性色 12 級:0、50、100 至 900 和 1000。
blue · red · orange · yellow · green · jiqing · indigo · purple · pink9 組功能色,每組 10 級。
loop-color12 個循環配色位置,參照色階 Token。
highlight.background16 個背景高亮位置,各自包含 color 和 alpha。
TypeScript
import type { Theme } from '@univerjs/themes';import { defaultTheme } from '@univerjs/themes';export const brandTheme: Theme = {  ...defaultTheme,  primary: {    ...defaultTheme.primary,    50: '#F5F3FF', 100: '#EDE9FE', 200: '#DDD6FE', 300: '#C4B5FD',    400: '#A78BFA', 500: '#8B5CF6', 600: '#7C3AED', 700: '#6D28D9',    800: '#5B21B6', 900: '#4C1D95',  },};

將主題傳入所選的產品整合。下面的範例使用 Sheet 核心預設(UniverSheetsCorePreset),並註冊應用自有的語言鍵;其他產品使用各自的外掛組合。該預設接受以下配置項:

  • container
    string | HTMLElement預設值: 'app'
    編輯器掛載的元素或其 DOM ID。
TypeScript
import { LocaleType, mergeLocales } from '@univerjs/core';import { UniverSheetsCorePreset } from '@univerjs/preset-sheets-core';import SheetsCoreEnUS from '@univerjs/preset-sheets-core/locales/en-US';import { createUniver } from '@univerjs/presets';import { brandTheme } from './brand-theme';import '@univerjs/preset-sheets-core/lib/index.css';export const { univer, univerAPI } = createUniver({  theme: brandTheme,  darkMode: false,  locale: LocaleType.EN_US,  locales: {    [LocaleType.EN_US]: mergeLocales(SheetsCoreEnUS, {      'sales-report': { generate: 'Generate report', ready: 'Ready for {0}' },    }),  },  presets: [UniverSheetsCorePreset({ container: 'app' })],});

執行時切換並跟隨應用偏好

setTheme() 用於切換色板,toggleDarkMode() 用於切換深色模式,getCurrentTheme() 和 isDarkMode() 用於讀取當前值。僅切換到 darkBlueTheme 不會同時啟用深色模式標記。修改外觀不需要銷燬並重建編輯器。

下面的函式跟隨系統偏好,並返回一個清理函式。如果應用提供了手動外觀設定,應改為在該設定的處理函式中呼叫 toggleDarkMode()。

TypeScript
import type { FUniver } from '@univerjs/core/facade';import { brandTheme } from './brand-theme';export function followSystemAppearance(univerAPI: FUniver): () => void {  univerAPI.setTheme(brandTheme);  const preference = window.matchMedia('(prefers-color-scheme: dark)');  const update = () => univerAPI.toggleDarkMode(preference.matches);  update();  preference.addEventListener('change', update);  return () => preference.removeEventListener('change', update);}

在編輯器初始化完成後呼叫該函式,並在元件解除安裝或不再跟隨系統時執行返回的清理函式。在 React 等整合中,應保留已有例項,並透過 Facade 更新外觀。

讓自訂插件跟隨主題與語言

自定義 DOM 使用注入的 CSS 變數,併為深色類提供獨立的樣式。變數中儲存的是色板值,因此元件仍須自行應用深色模式狀態。

CSS
.report-panel {  color: var(--univer-gray-900);  background: var(--univer-gray-0);  border: 1px solid var(--univer-gray-200);}.univer-dark .report-panel {  color: var(--univer-gray-100);  background: var(--univer-gray-800);  border-color: var(--univer-gray-700);}

Canvas 擴充套件透過 ThemeService 讀取即時 Token,再透過 ICanvasColorService 取得實際用於繪製的顏色。下面的範例將主題、深色模式和語言變化合併為一個可觀察狀態。僅在狀態變化時翻譯文字並解析顏色,因此不會在每一繪製幀重複查詢或分配。

TypeScript
import { Disposable, Inject, LocaleService, ThemeService, toDisposable } from '@univerjs/core';import { ICanvasColorService } from '@univerjs/engine-render';import { combineLatest, ReplaySubject } from 'rxjs';export interface IReportAppearance {  label: string;  accent: string;}export class ReportAppearance extends Disposable {  readonly state$ = new ReplaySubject<IReportAppearance>(1);  constructor(    @Inject(ThemeService) theme: ThemeService,    @Inject(LocaleService) locale: LocaleService,    @ICanvasColorService colors: ICanvasColorService,  ) {    super();    this.disposeWithMe(toDisposable(() => this.state$.complete()));    this.disposeWithMe(combineLatest([      theme.currentTheme$, theme.darkMode$, locale.currentLocale$,    ]).subscribe(() => {      this.state$.next({        label: locale.t('sales-report.generate'),        accent: colors.getRenderColor(theme.getColorFromTheme('primary.600')),      });    }));  }}

在業務外掛中透過 DI 註冊並取得 ReportAppearance。檢視或繪製控制器訂閱 state$ 並重新整理介面。訂閱由使用方管理,服務擁有者負責呼叫 dispose()。Node.js 也提供主題和語言服務,但不會注入瀏覽器 CSS。

深色模式(Dark Mode)

Sheet、Doc、Slide、Relational Table、Canvases 和 PDF 均使用共享的主題與深色模式。下面的截圖來自本地標準演示,介面和內容均為英文。深色顯示不會將對映後的顏色寫回 Snapshot。應用外觀與 PDF 頁面內容的處理彼此獨立,PDF 的本地驗證結果見下文。

產品共用主題深色模式介面國際化
Sheet✓✓✓
Doc✓✓✓
Slide✓✓✓
Relational Table✓✓✓
Canvases✓✓✓
PDF✓介面支援;正文有顯示問題✓

可顯示的語言取決於所選產品和已安裝功能所提供的語言套件。應用色板不會註冊產品、載入語言資源,也不會匯入樣式表。

19 個內建語言/地區選項

LocaleType 提供以下 19 個選項,中文包括簡體、繁體和香港繁體三種變體。六個產品的主 UI 包都包含這些資源,擴充套件外掛的覆蓋範圍取決於所選的包。語言套件標籤用於匯入路徑,對應的列舉值用於初始化和 Facade 配置。

RTL 支援範圍: 阿拉伯語(ar-SA)等語言套件會翻譯選單、提示等介面文字。direction: 'rtl' 目前僅調整選單等介面 UI 的方向。Canvas 內容區的 RTL 排版與編輯尚未實現。

語言(原文名稱)語言包標籤設定值
Englishen-USLocaleType.EN_US
简体中文zh-CNLocaleType.ZH_CN
繁體中文zh-TWLocaleType.ZH_TW
繁體中文(香港)zh-HKLocaleType.ZH_HK
日本語ja-JPLocaleType.JA_JP
한국어ko-KRLocaleType.KO_KR
Tiếng Việtvi-VNLocaleType.VI_VN
Bahasa Indonesiaid-IDLocaleType.ID_ID
Françaisfr-FRLocaleType.FR_FR
Deutschde-DELocaleType.DE_DE
Españoles-ESLocaleType.ES_ES
Catalàca-ESLocaleType.CA_ES
Italianoit-ITLocaleType.IT_IT
Português (Brasil)pt-BRLocaleType.PT_BR
Polskipl-PLLocaleType.PL_PL
Slovenčinask-SKLocaleType.SK_SK
Русскийru-RULocaleType.RU_RU
فارسیfa-IRLocaleType.FA_IR
العربيةar-SALocaleType.AR_SA

跨產品的國際化資源: 以當前 1.2.0 的原始碼為例,Web SDK 和 Pro 編輯器中的 92 個模組提供了 1,751 個語言入口檔案,覆蓋公共 UI、各產品編輯器,以及公式、數字格式、評論等功能。資源由各模組獨立維護和釋出,應用按啟用的功能和目標語言組合資源。

該數字統計的是兩套原始碼中 packages/*/src/locale 下的語言入口 .ts 檔案,不包含測試和生成目錄。這並不表示每個模組都完整覆蓋 19 個選項。部分模組還包含額外的語言,公共的內建選項以 LocaleType 為準。

按插件組合語言資源,再載入與切換

LocaleService 按語言標識組織資源,並透過名稱空間和鍵路徑解析文字。mergeLocales() 合併產品預設、功能外掛和應用翻譯。loadLocales() 在執行時合併資源,setLocale() 切換語言。選擇語言本身不會下載對應的語言套件。

100%

下面的範例為前文介紹的 Sheet 例項新增中文資源,將介面切換為中文,並顯式保留德國的地區習慣。LocaleType.ZH_CN 的值為 zhCN,zh-CN 則是語言套件檔名和文件路由中使用的寫法。

TypeScript
import type { FUniver } from '@univerjs/core/facade';import { LocaleType, mergeLocales } from '@univerjs/core';import SheetsCoreZhCN from '@univerjs/preset-sheets-core/locales/zh-CN';export function switchInterface(univerAPI: FUniver): void {  univerAPI.loadLocales(LocaleType.ZH_CN, mergeLocales(SheetsCoreZhCN, {    'sales-report': { generate: '生成报告', ready: '已为 {0} 就绪' },  }));  univerAPI.setLocale(LocaleType.ZH_CN);  univerAPI.setRegion(LocaleType.DE_DE);  univerAPI.setDirection('ltr');}

sales-report.generate 這類鍵歸屬於對應的外掛。翻譯應寫成完整的句子,動態值使用 {0}、{1} 佔位,例如 LocaleService.t('sales-report.ready', 'Alex')。不要在模組初始化時快取翻譯。資源初始化完成後,當前實現中缺失的鍵會回退為鍵名本身。切換介面語言不會翻譯正文,也不會重新命名已有的 Unit。

區分語言、地區與內容格式

層次實際影響
介面 locale選單、提示、外掛文字,以及文件分詞等部分與語言相關的行為。
region使用該設定的貨幣操作、評論時間顯示和統計數字格式;不換算貨幣金額,也不修改時間戳。
內容數字格式Sheet 中已儲存的數字和日期格式取決於單元格格式以及適用於該內容的內容 locale;切換地區不會統一重寫這些格式。
direction獨立的介面方向設定,切換語言或地區不會自動改變該方向。

未指定地區時使用對應的預設值。顯式設定 region 後,它可以與介面語言分開選擇。region 不是時區配置。RTL 目前僅調整選單等介面 UI 的方向,Canvas 內容區的從右到左排版與編輯尚未實現。

內容主題與應用主題各有邊界

應用主題控制工作臺和渲染預設值,不會重寫已儲存的單元格填充、文字、圖形、PDF 標註或顯式指定的圖表顏色。範圍與表格主題、Slide 色彩方案和 Canvases 內容主題,透過各產品對應的公開能力管理。

Pro 圖表使用獨立的 IEchartTheme 登錄檔,由 Sheet、Doc、Slide 和 Canvases 的圖表共享。應用的 Theme 不能作為圖表主題使用。在安裝了相應圖表外掛的宿主中,匯入圖表 Facade 後即可註冊完整定義:

TypeScript
import type { IEchartTheme } from '@univerjs-pro/engine-chart';import type { FUniver } from '@univerjs/core/facade';import { UniverTheme1 } from '@univerjs-pro/engine-chart';import '@univerjs-pro/engine-chart/facade';export function registerBrandChartTheme(univerAPI: FUniver): void {  const chartTheme: IEchartTheme = {    ...UniverTheme1,    themeName: 'sales-brand',    theme: {      ...UniverTheme1.theme,      color: ['#7C3AED', '#0EA5E9', '#10B981', '#F59E0B'],    },  };  univerAPI.registerTheme('sales-brand', chartTheme);}

在圖表建立時透過 builder 的 setTheme('sales-brand') 選擇註冊的名稱。顯式設定的圖表調色盤可能覆蓋其中系列的顏色。

同一個瀏覽器文件內的外觀必須保持一致,因為當前 UI 的 CSS 變數和 univer-dark 類都寫入文件根節點。多個編輯器應共用一套外觀,或使用 iframe 等獨立文件;僅分開容器無法隔離 CSS 主題。

延伸閱讀:主題與深色模式 · 國際化詳細配置 · 外掛與 Facade · 圖表能力

返回功能總覽

你覺得這篇文檔如何?

© 2026 DreamNum Co., Ltd.