主题与国际化
统一编辑器外观、深色模式和语言资源,让扩展界面与应用一致。
主题与国际化是共享的运行时服务。六个产品使用同一套主题服务、语言资源和区域配置,自定义插件读取的也是这些状态。品牌外观和用户偏好在应用运行期间可以修改,内容自身保存的数据和样式不受影响。
SDK 内置 19 个界面语言与地区选项 和 7 套主题色板。六个产品共用外观、语言和区域配置,自定义主题和业务翻译也使用同一套服务。
一套状态,同时驱动界面与渲染
ThemeService 将完整色板与深色模式状态分开保存,变化分别通过 currentTheme$ 和 darkMode$ 发布。界面将色板展开为 --univer-* CSS 变量,并响应 univer-dark 类;渲染器订阅同一个服务,将受影响的组件标记为需要重绘。Canvas 的颜色服务负责解析 Token、为深色显示映射颜色,并缓存结果。
本章的配置和示例以 @univerjs/*、@univerjs-pro/* 1.2.0 为准。应用中各 SDK 依赖的版本应保持一致。
| 配置 | 可选值与范围 | 运行时 API |
|---|---|---|
theme | 7 套内置色板,或完整的自定义 Theme。 | setTheme() |
darkMode | true / false,默认 false;与色板相互独立。 | toggleDarkMode() |
locale | 19 个内置 LocaleType 值;需先加载对应资源。 | setLocale() |
locales | 按语言标识合并的产品、功能插件和应用翻译资源。 | loadLocales() |
region | 同一组 LocaleType 值;未显式设置时跟随界面语言。 | setRegion() |
direction | ltr / rtl,默认 ltr;仅影响菜单等界面 UI,Canvas 内容区尚不支持 RTL。 | setDirection() |
从完整色板构建品牌主题
@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 · pink | 9 组功能色,每组 10 级。 |
loop-color | 12 个循环配色位置,引用色阶 Token。 |
highlight.background | 16 个背景高亮位置,各自包含 color 和 alpha。 |
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),并注册应用自有的语言键;其他产品使用各自的插件组合。该预设接受以下配置项:
containerstring | HTMLElement默认值:'app'编辑器挂载的元素或其 DOM ID。
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()。
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 变量,并为深色类提供独立的样式。变量中保存的是色板值,因此组件仍须自行应用深色模式状态。
.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 获取实际用于绘制的颜色。下面的示例将主题、深色模式和语言变化合并为一个可观察状态。仅在状态变化时翻译文字并解析颜色,因此不会在每一绘制帧重复查找或分配。
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 正文在深色模式下存在文字可见性问题,浅色模式显示正常。本图展示的是深色模式下的编辑器界面。PDF 正文的深色适配仍需修复和验证。
可显示的语言取决于所选产品和已安装功能所提供的语言包。应用色板不会注册产品、加载语言资源,也不会导入样式表。
19 个内置语言/地区选项
LocaleType 提供以下 19 个选项,中文包括简体、繁体和香港繁体三种变体。六个产品的主 UI 包都包含这些资源,扩展插件的覆盖范围取决于所选的包。语言包标签用于导入路径,对应的枚举值用于初始化和 Facade 配置。
RTL 支持范围: 阿拉伯语(ar-SA)等语言包会翻译菜单、提示等界面文字。direction: 'rtl' 目前仅调整菜单等界面 UI 的方向。Canvas 内容区的 RTL 排版与编辑尚未实现。
| 语言(原文名称) | 语言包标签 | 配置值 |
|---|---|---|
| English | en-US | LocaleType.EN_US |
| 简体中文 | zh-CN | LocaleType.ZH_CN |
| 繁體中文 | zh-TW | LocaleType.ZH_TW |
| 繁體中文(香港) | zh-HK | LocaleType.ZH_HK |
| 日本語 | ja-JP | LocaleType.JA_JP |
| 한국어 | ko-KR | LocaleType.KO_KR |
| Tiếng Việt | vi-VN | LocaleType.VI_VN |
| Bahasa Indonesia | id-ID | LocaleType.ID_ID |
| Français | fr-FR | LocaleType.FR_FR |
| Deutsch | de-DE | LocaleType.DE_DE |
| Español | es-ES | LocaleType.ES_ES |
| Català | ca-ES | LocaleType.CA_ES |
| Italiano | it-IT | LocaleType.IT_IT |
| Português (Brasil) | pt-BR | LocaleType.PT_BR |
| Polski | pl-PL | LocaleType.PL_PL |
| Slovenčina | sk-SK | LocaleType.SK_SK |
| Русский | ru-RU | LocaleType.RU_RU |
| فارسی | fa-IR | LocaleType.FA_IR |
| العربية | ar-SA | LocaleType.AR_SA |
跨产品的国际化资源: 以当前 1.2.0 的源码为例,Web SDK 和 Pro 编辑器中的 92 个模块提供了 1,751 个语言入口文件,覆盖公共 UI、各产品编辑器,以及公式、数字格式、评论等功能。资源由各模块独立维护和发布,应用按启用的功能和目标语言组合资源。
该数字统计的是两套源码中 packages/*/src/locale 下的语言入口 .ts 文件,不包含测试和生成目录。这并不表示每个模块都完整覆盖 19 个选项。部分模块还包含额外的语言,公共的内置选项以 LocaleType 为准。
语言资源按插件组合,按需加载与切换
LocaleService 按语言标识组织资源,并通过命名空间和键路径解析文字。mergeLocales() 合并产品预设、功能插件和应用翻译。loadLocales() 在运行时合并资源,setLocale() 切换语言。选择语言本身不会下载对应的语言包。
下面的示例为前文介绍的 Sheet 实例添加中文资源,将界面切换为中文,并显式保留德国的地区习惯。LocaleType.ZH_CN 的值为 zhCN,zh-CN 则是语言包文件名和文档路由中使用的写法。
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 后即可注册完整定义:
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 · 图表能力
你觉得这篇文档如何?