Темы и локализация

Настройте внешний вид, тёмный режим и языковые ресурсы под приложение.

Темы и интернационализация являются общими службами времени выполнения. Все шесть продуктов используют один и тот же тематический сервис, локальные ресурсы и региональную конфигурацию, а пользовательские плагины могут наблюдать одно и то же состояние. Внешний вид бренда и предпочтения пользователя могут меняться во время работы приложения, не влияя на данные и стили, хранящиеся с контентом.

SDK включает в себя 19 встроенных вариантов языка интерфейса и региона и 7 тематических палитр. Все шесть продуктов имеют общую конфигурацию внешнего вида, локализации и региона, а пользовательские темы и переводы приложений используют одни и те же услуги.

Общее состояние для интерфейса и рендеринга

ThemeService хранит полную палитру и состояние темного режима отдельно, и публикует изменения через currentTheme$ и darkMode$. UI расширяет палитру в переменные --univer-* CSS и реагирует на класс univer-dark, Рендереры подписываются на одну и ту же услугу и помечают пораженные компоненты для перекраски. Цветовая служба Canvas разрешает токены, отображает цвета для темного дисплея и кэширует результаты.

Конфигурация и примеры в этой главе применяются к @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 по умолчанию; применяется только к меню и аналогичному пользовательскому интерфейсу.setDirection()
100%

Фирменная тема на основе полной палитры

@univerjs/themes предоставляет primary, gray функциональные цветовые шкалы, loop-color и highlight.background. Копировать встроенную тему, заменять ветви, требующие изменений, и сохранять структуру полной. setTheme() заменяет целую тему; он не заполняет частичный объект. Пример ниже обеспечивает непрерывную фиолетовую шкалу бренда.

7 встроенных палитр: blueTheme, darkBlueTheme, greenTheme, orangeTheme, purpleTheme, redTheme и yellowTheme.

defaultTheme является псевдонимом blueTheme. Палитра и состояние темного режима выбираются отдельно. Настраиваемые ветви следующие:

Раздел темыНастраиваемые варианты
primary10 фирменных оттенков: 50, затем от 100 до 900.
gray12 нейтральных оттенков: 0, 50, от 100 до 900 и 1000.
blue · red · orange · yellow · green · jiqing · indigo · purple · pink9 функциональных шкал, по 10 оттенков в каждой.
loop-color12 вращающиеся цветовые позиции, которые ссылаются на токены палитры.
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-элемент для редактора или его идентификатор.
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.

Поддержка темы и языка в своих плагинах

Custom 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 и получают цвета, используемые для рисования от 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')),      });    }));  }}

Зарегистрируйте ReportAppearance через DI и разрешите его в плагине. Контроллер просмотра или рисунка подписывается на state$ и обновляется. Потребитель владеет подпиской, а владелец сервиса звонит dispose(). Node.js также предоставляет тематические и локальные услуги, но не вводит браузер CSS.

Тёмный режим

Спецификация, Doc, Slide, Relational Table, Canvases и PDF используют общую тему и темный режим. Скриншоты ниже были взяты из локальных стандартных демо, пользовательский интерфейс и контент которых на английском языке. Темный дисплей не записывает отображаемые цвета обратно в Snapshot. Внешний вид приложения и обработка страницы PDF являются отдельными проблемами; результат локальной проверки PDF описан ниже.

ПродуктОбщая темаТёмный режимЛокализация UI
Sheet✓✓✓
Doc✓✓✓
Slide✓✓✓
Relational Table✓✓✓
Canvases✓✓✓
PDF✓UI поддержан; проблема отображения текста✓

Языковое покрытие зависит от пакетов ресурсов, предоставляемых выбранными продуктами и установленными функциями.Пакет приложений не регистрирует продукты, не загружает локализации или не импортирует таблицы стилей.

19 встроенных языковых и региональных вариантов

LocaleType предоставляет следующие 19 опций, в том числе упрощенный, традиционный и гонконгский традиционные китайские варианты. Основные пакеты пользовательского интерфейса всех шести продуктов включают эти ресурсы; покрытие в расширениях зависит от выбранного пакета. Бундле-теги используются в маршрутах импорта, а совпадающие числовые значения используются в инициализации и конфигурации Facade.

Область применения RTL: Арабский (ar-SA) и другие локальные пакеты переводят текст интерфейса, такой как меню и сообщения. direction: 'rtl' в настоящее время адаптирует меню и аналогичный только пользовательский интерфейс. Планировка и редактирование RTL в области контента Canvas не были реализованы.

Язык (родное название)Тег пакетаЗначение настройки
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 92 модуля в редакторах Web SDK и Pro предоставляет 1 751 файл локального ввода для общего пользовательского интерфейса, редакторов продуктов и функций, таких как формулы, форматы чисел и комментарии.Каждый модуль поддерживает и публикует свои собственные ресурсы, а приложение объединяет функции, которые оно позволяет, с локализациями, на которые оно нацелено.

Подсчет охватывает локальную запись .ts файлов под packages/*/src/locale в обоих деревьях-источниках, исключая тесты и сгенерированные подкаталоги. Это не означает, что каждый модуль охватывает все 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'). Не кэшируйте переводы при инициализации модуля. После инициализации ресурсов отсутствующий ключ в настоящее время возвращается к самому ключу. Переключение языка интерфейса не переводит контент или не переименовывает существующие блоки.

Разделяйте язык, регион и форматы контента

УровеньРеальное влияние
locale интерфейсаМеню, сообщения, подписи и часть языковых функций, например сегментация документа.
regionВалютные действия, которые используют эту настройку, отображение даты/времени комментариев и форматирование статистики; без конвертации валюты или изменения метки времени.
Числовые форматы контентаСохраненные форматы номера/даты листов следуют форматам ячеек и локальному содержанию, которое к ним относится; изменение региона не переписывает их все.
directionНезависимое направление пользовательского интерфейса; изменение языка или региона не переключает его автоматически.

Когда не указана область, применяется соответствующий по умолчанию. После того, как область установлена явно, она может быть выбрана независимо от языка интерфейса. region не является настройкой часового пояса. RTL в настоящее время адаптирует только меню и аналогичный пользовательский интерфейс, а право-левая компоновка и редактирование в области контента Canvas не были реализованы.

Границы тем контента и приложения

Тема приложения управляет рабочим столом и по умолчанию рендеринга. Она не переписывает сохраняющиеся заполнения ячеек, текст, формы, аннотации PDF или явные цвета диаграмм. Темы диапазона и таблицы, цветовые схемы Slide и темы контента Canvases управляются с помощью соответствующих возможностей общедоступного продукта.

Pro Charts используют отдельный реестр IEchartTheme, разделяемый Sheet, Doc, Slide и Canvases Charts. Приложение Theme не является темой Chart. В хосте с установленными соответствующими плагинами Chart импортируйте Chart 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);}

Выберите зарегистрированное имя через setTheme('sales-brand') сборщика диаграмм. Настроенная явно палитра диаграмм может переопределить цвета серии.

Внешний вид должен быть согласован в одном документе браузера, потому что текущие переменные пользовательского интерфейса и класс univer-dark написаны на корне документа.Множественные редакторы должны совместно использовать один внешний вид или использовать отдельные документы, такие как ифрамы; отдельные контейнеры сами по себе не изолируют темы CSS.

Подробнее: Темы и тёмный режим · Настройка i18n · Плагины и Facade · Диаграммы

Вернуться к обзору функций

Насколько полезно это руководство?

© 2026 DreamNum Co., Ltd.