Темы и локализация
Настройте внешний вид, тёмный режим и языковые ресурсы под приложение.
Темы и интернационализация являются общими службами времени выполнения. Все шесть продуктов используют один и тот же тематический сервис, локальные ресурсы и региональную конфигурацию, а пользовательские плагины могут наблюдать одно и то же состояние. Внешний вид бренда и предпочтения пользователя могут меняться во время работы приложения, не влияя на данные и стили, хранящиеся с контентом.
SDK включает в себя 19 встроенных вариантов языка интерфейса и региона и 7 тематических палитр. Все шесть продуктов имеют общую конфигурацию внешнего вида, локализации и региона, а пользовательские темы и переводы приложений используют одни и те же услуги.
Общее состояние для интерфейса и рендеринга
ThemeService хранит полную палитру и состояние темного режима отдельно, и публикует изменения через currentTheme$ и darkMode$. UI расширяет палитру в переменные --univer-* CSS и реагирует на класс univer-dark, Рендереры подписываются на одну и ту же услугу и помечают пораженные компоненты для перекраски. Цветовая служба Canvas разрешает токены, отображает цвета для темного дисплея и кэширует результаты.
Конфигурация и примеры в этой главе применяются к @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 по умолчанию; применяется только к меню и аналогичному пользовательскому интерфейсу. | 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 вращающиеся цветовые позиции, которые ссылаются на токены палитры. |
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-элемент для редактора или его идентификатор.
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.
Поддержка темы и языка в своих плагинах
Custom 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 и получают цвета, используемые для рисования от 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')), }); })); }}Зарегистрируйте ReportAppearance через DI и разрешите его в плагине. Контроллер просмотра или рисунка подписывается на state$ и обновляется. Потребитель владеет подпиской, а владелец сервиса звонит dispose(). Node.js также предоставляет тематические и локальные услуги, но не вводит браузер CSS.
Тёмный режим
Спецификация, Doc, Slide, Relational Table, Canvases и PDF используют общую тему и темный режим. Скриншоты ниже были взяты из локальных стандартных демо, пользовательский интерфейс и контент которых на английском языке. Темный дисплей не записывает отображаемые цвета обратно в Snapshot. Внешний вид приложения и обработка страницы PDF являются отдельными проблемами; результат локальной проверки PDF описан ниже.
| Продукт | Общая тема | Тёмный режим | Локализация UI |
|---|---|---|---|
| Sheet | ✓ | ✓ | ✓ |
| Doc | ✓ | ✓ | ✓ |
| Slide | ✓ | ✓ | ✓ |
| Relational Table | ✓ | ✓ | ✓ |
| Canvases | ✓ | ✓ | ✓ |
| ✓ | UI поддержан; проблема отображения текста | ✓ |
Текущая локальная стандартная демо-версия имеет проблему текстовой видимости с PDF-контентом в темном режиме; световой режим отображается правильно. Этот скриншот показывает пользовательский интерфейс редактора в темном режиме. Поддержка темного режима для PDF-контента по-прежнему требует коррекции и проверки.
Языковое покрытие зависит от пакетов ресурсов, предоставляемых выбранными продуктами и установленными функциями.Пакет приложений не регистрирует продукты, не загружает локализации или не импортирует таблицы стилей.
19 встроенных языковых и региональных вариантов
LocaleType предоставляет следующие 19 опций, в том числе упрощенный, традиционный и гонконгский традиционные китайские варианты. Основные пакеты пользовательского интерфейса всех шести продуктов включают эти ресурсы; покрытие в расширениях зависит от выбранного пакета. Бундле-теги используются в маршрутах импорта, а совпадающие числовые значения используются в инициализации и конфигурации Facade.
Область применения RTL: Арабский (ar-SA) и другие локальные пакеты переводят текст интерфейса, такой как меню и сообщения. direction: 'rtl' в настоящее время адаптирует меню и аналогичный только пользовательский интерфейс. Планировка и редактирование RTL в области контента Canvas не были реализованы.
| Язык (родное название) | Тег пакета | Значение настройки |
|---|---|---|
| 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 92 модуля в редакторах Web SDK и Pro предоставляет 1 751 файл локального ввода для общего пользовательского интерфейса, редакторов продуктов и функций, таких как формулы, форматы чисел и комментарии.Каждый модуль поддерживает и публикует свои собственные ресурсы, а приложение объединяет функции, которые оно позволяет, с локализациями, на которые оно нацелено.
Подсчет охватывает локальную запись .ts файлов под packages/*/src/locale в обоих деревьях-источниках, исключая тесты и сгенерированные подкаталоги. Это не означает, что каждый модуль охватывает все 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'). Не кэшируйте переводы при инициализации модуля. После инициализации ресурсов отсутствующий ключ в настоящее время возвращается к самому ключу. Переключение языка интерфейса не переводит контент или не переименовывает существующие блоки.
Разделяйте язык, регион и форматы контента
| Уровень | Реальное влияние |
|---|---|
locale интерфейса | Меню, сообщения, подписи и часть языковых функций, например сегментация документа. |
region | Валютные действия, которые используют эту настройку, отображение даты/времени комментариев и форматирование статистики; без конвертации валюты или изменения метки времени. |
| Числовые форматы контента | Сохраненные форматы номера/даты листов следуют форматам ячеек и локальному содержанию, которое к ним относится; изменение региона не переписывает их все. |
direction | Независимое направление пользовательского интерфейса; изменение языка или региона не переключает его автоматически. |
Когда не указана область, применяется соответствующий по умолчанию. После того, как область установлена явно, она может быть выбрана независимо от языка интерфейса. region не является настройкой часового пояса. RTL в настоящее время адаптирует только меню и аналогичный пользовательский интерфейс, а право-левая компоновка и редактирование в области контента Canvas не были реализованы.
Границы тем контента и приложения
Тема приложения управляет рабочим столом и по умолчанию рендеринга. Она не переписывает сохраняющиеся заполнения ячеек, текст, формы, аннотации PDF или явные цвета диаграмм. Темы диапазона и таблицы, цветовые схемы Slide и темы контента Canvases управляются с помощью соответствующих возможностей общедоступного продукта.
Pro Charts используют отдельный реестр IEchartTheme, разделяемый Sheet, Doc, Slide и Canvases Charts. Приложение Theme не является темой Chart. В хосте с установленными соответствующими плагинами Chart импортируйте Chart 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);}Выберите зарегистрированное имя через setTheme('sales-brand') сборщика диаграмм. Настроенная явно палитра диаграмм может переопределить цвета серии.
Внешний вид должен быть согласован в одном документе браузера, потому что текущие переменные пользовательского интерфейса и класс univer-dark написаны на корне документа.Множественные редакторы должны совместно использовать один внешний вид или использовать отдельные документы, такие как ифрамы; отдельные контейнеры сами по себе не изолируют темы CSS.
Подробнее: Темы и тёмный режим · Настройка i18n · Плагины и Facade · Диаграммы
Насколько полезно это руководство?