Temas y localización

Adapta apariencia, modo oscuro y recursos de idioma a tu aplicación.

Los temas y la internacionalización son servicios de tiempo de ejecución compartidos. Los seis productos utilizan el mismo servicio de tema, recursos locales y configuración regional, y los plugins personalizados pueden observar el mismo estado. La apariencia de marca y las preferencias de los usuarios pueden cambiar mientras la aplicación se ejecuta, sin afectar los datos y estilos almacenados con el contenido.

El SDK incluye 19 opciones de idioma y región de interfaz integrada y 7 paletas temáticas. Los seis productos comparten la configuración de apariencia, local y región, y los temas personalizados y las traducciones de aplicaciones utilizan los mismos servicios.

Un mismo estado para la interfaz y el renderizado

ThemeService almacena la paleta completa y el estado de movimiento oscuro por separado, y publica cambios a través de currentTheme$ y darkMode$. La UI expande la paleta a las variables --univer-* CSS y responde a la clase univer-dark . Los Renderers se suscriben al mismo servicio y marcan los componentes afectados para la repatura.

La configuración y los ejemplos en este capítulo se aplican a @univerjs/* y @univerjs-pro/* 1.2.0. Mantenga las versiones de dependencia SDK alineadas en su aplicación.

AjusteOpciones y alcanceAPI en ejecución
theme7 paletas incorporadas, o un Theme personalizado completo.setTheme()
darkModetrue / false; valor predeterminado false. Independiente de la paleta.toggleDarkMode()
locale19 valores incorporados LocaleType; cargar primero los recursos correspondientes.setLocale()
localesRecursos de productos, características y aplicaciones combinados por identificador local.loadLocales()
regionLos mismos valores de LocaleType; sigue el UI locale hasta que se establece explícitamente.setRegion()
directionltr / rtl, ltr predeterminado; se aplica a los menús y sólo UI similar. El contenido de las canvas no admite RTL todavía.setDirection()
100%

Crear la marca desde una paleta completa

@univerjs/themes proporciona primary, gray, las escalas de color funcional, loop-color, y highlight.background. Copiar un tema incorporado, reemplazar las ramas que requieren cambios, y mantener la estructura completa. setTheme() reemplaza un tema entero; no llena profundamente un objeto parcial. El ejemplo a continuación proporciona una escala de la marca violeta continua.

Las 7 paletas incorporadas son blueTheme, darkBlueTheme, greenTheme, orangeTheme, purpleTheme, redTheme, y yellowTheme.

defaultTheme es un alias de blueTheme. La paleta y el estado de la luna oscura se seleccionan por separado. Las ramas configurables son las siguientes:

Rama del temaOpciones configurables
primary10 niveles de marca: 50, y de 100 a 900.
gray12 niveles neutros: 0, 50, de 100 a 900, y 1000.
blue · red · orange · yellow · green · jiqing · indigo · purple · pink9 escalas funcionales, con 10 niveles cada una.
loop-color12 posiciones de color giratorio que referencia fichas de paleta.
highlight.background16 posiciones de resaltado de fondo, cada una con color y 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',  },};

Pase el tema a la integración del producto que seleccionó. Este ejemplo utiliza el preset básico de la hoja (UniverSheetsCorePreset) y registra las claves de traducción de propiedad de la aplicación; otros productos utilizan su propia composición del plugin.

  • container
    string | HTMLElementValor predeterminado: 'app'
    Elemento DOM donde se monta el editor, o su 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' })],});

Cambiar la apariencia y seguir las preferencias

setTheme() cambia la paleta, y toggleDarkMode() cambia el estado de la luna oscura. getCurrentTheme() y isDarkMode() leen los valores actuales. Cambiar a darkBlueTheme por sí solo no permite la bandera de la luna negra. Cambiar la apariencia no requiere destruir y recrear el editor.

La función siguiente sigue la preferencia del sistema y devuelve una función de limpieza. Si la aplicación proporciona un ajuste de apariencia manual, llame a toggleDarkMode() del controlador para ese ajuste en su lugar.

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);}

Llame a la función después de que el editor haya sido creado, y ejecute la función de limpieza devuelta cuando el componente desmonte o detenga después del sistema. En React e integraciones similares, mantenga la instancia existente y actualice a través de Facade.

Adaptar plugins personalizados al tema y al idioma

DOM personalizado utiliza las variables CSS inyectadas y proporciona sus propios estilos para la clase oscura. Las variables contienen valores de paleta, por lo que el componente debe aplicar el estado de movimiento oscuro en sí.

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);}

Las extensiones de lienzos leen fichas en vivo a través de ThemeService y obtienen los colores utilizados para dibujar desde ICanvasColorService. El ejemplo a continuación combina tema, movimiento oscuro y cambios locales en un solo estado observable. Traduce etiquetas y resuelve los colores cuando el estado cambia, por lo que no se repite ninguna búsqueda o asignación en cada marco de dibujo.

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')),      });    }));  }}

Registrar ReportAppearance a través de DI y resolverlo en el plugin. El controlador de vista o dibujo se suscribe a state$ y refrescos. El consumidor posee la suscripción, y el propietario del servicio llama dispose(). Node.js también proporciona servicios de tema y local, pero no inyecta el navegador CSS.

Modo oscuro

Hoja, Doc, Diapositiva, Tabla Relacional, Canvases y PDF todos utilizan el tema compartido y modo oscuro. Las imágenes a continuación fueron tomadas de los demos estándar locales, cuya interfaz de usuario y contenido están en inglés. La pantalla oscura no escribe los colores mapeados de nuevo en el Snapshot. La apariencia de aplicación y el procesamiento de páginas PDF son preocupaciones separadas; el resultado de la verificación PDF local se describe a continuación.

ProductoTema compartidoModo oscuroUI internacional
Sheet✓✓✓
Doc✓✓✓
Slide✓✓✓
Relational Table✓✓✓
Canvases✓✓✓
PDF✓UI compatible; problema al mostrar contenido✓

La cobertura de idiomas depende de los paquetes de recursos proporcionados por los productos seleccionados y las características instaladas. Una paleta de aplicaciones no registra productos, locales de carga o hojas de estilo de importación.

19 opciones integradas de idioma y región

LocaleType ofrece las siguientes 19 opciones, incluyendo las variantes chinas tradicionales simplificadas, tradicionales y de Hong Kong. Los principales paquetes de UI de los seis productos incluyen estos recursos; cobertura en extensiones depende del paquete seleccionado. Las etiquetas de los envases se utilizan en las rutas de importación, y los valores de enum coincidentes se utilizan en la inicialización y configuración de Facade.

Alcance RTL: Árabe (ar-SA) y otros paquetes locales traducen texto de interfaz como menús y mensajes. direction: 'rtl' actualmente adapta menús y solo UI similar. No se han implementado diseños y edición de RTL en el área de contenido de Canvas.

Idioma (nombre nativo)Etiqueta del paqueteValor de configuración
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

Internacionalización de productos: En la actual fuente 1.2.0, 92 módulos en los editores Web SDK y Pro proporcionan 1,751 archivos de entrada local para interfaz de usuario compartida, editores de productos y características tales como fórmulas, formatos de números y comentarios. Cada módulo mantiene y publica sus propios recursos, y la aplicación combina las características que permite con los locales que se dirige.

El recuento cubre los archivos .ts de entrada local bajo packages/*/src/locale en ambos árboles fuente, excluyendo las pruebas y subdirectorios generados. No significa que cada módulo cubra todas las 19 opciones. Algunos módulos incluyen idiomas adicionales; LocaleType define el conjunto integrado común.

Componer recursos por plugin, cargarlos y seleccionar idioma

LocaleService organiza recursos por locale y resuelve etiquetas a través de espacios de nombres y rutas clave. mergeLocales() combina presets de productos, plugins de características y traducciones de aplicaciones. loadLocales() fusiona recursos a tiempo de ejecución, y setLocale() selecciona el idioma. Elegir un local no descarga su paquete.

100%

El siguiente ejemplo añade recursos chinos a la instancia de hoja introducida anteriormente, cambia la interfaz de usuario a chino, y conserva explícitamente convenciones regionales alemanas. LocaleType.ZH_CN tiene el valor zhCN; zh-CN es el formulario utilizado en nombres de archivo de paquetes y rutas de documentación.

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');}

Las claves como sales-report.generate pertenecen al plugin que las posee. Escribe frases completas traducidas y usa {0}, marcadores de posición {1} para valores dinámicos, como en LocaleService.t('sales-report.ready', 'Alex'). No caché traducciones en la inicialización del módulo. Después de que se hayan inicializado los recursos, una clave que falta actualmente se remonta a la propia clave.

Distinguir idioma, región y formatos del contenido

CapaEfecto real
locale de interfazMenús, mensajes, etiquetas y algunos comportamientos lingüísticos, como segmentación de documentos.
regionAcciones monetarias que utilizan este ajuste, fecha/hora de comentarios, y el formato de estadísticas; no hay conversión de divisas o cambios de horario.
Formato numérico del contenidoLos formatos guardados del número de hoja/fecha siguen los formatos de celda y el contenido local que se aplica a ellos; cambiar la región no reescribirlos a todos.
directionDirección independiente de la interfaz de usuario; cambiar el idioma o región no lo cambia automáticamente.

Cuando no se especifica ninguna región, se aplica el defecto correspondiente. Una vez que la región se establece explícitamente, se puede seleccionar independientemente del idioma de interfaz. region no es un ajuste de la zona horaria. RTL actualmente adapta menús y sólo UI similares, y el diseño y edición de derecha a izquierda en el área de contenido de Canvas no se han implementado.

Límites entre temas del contenido y de la aplicación

El tema de la aplicación controla el banco de trabajo y los defectos de renderización. No reescribe los rellenos de celdas persistentes, texto, formas, anotaciones PDF, o colores de cartulina explícitos. Temas de gama y tabla, esquemas de color deslizante, y los temas de contenido de Canvases se gestionan a través de las capacidades de producto público correspondientes.

Pro Charts utiliza un registro IEchartTheme separado compartido por Sheet, Doc, Slide y Canvases Charts. Una aplicación Theme no es un tema de Chart. En un host con los plugins de Chart apropiados instalados, importar el Chart Facade y registrar una definición completa:

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);}

Seleccione el nombre registrado a través del setTheme('sales-brand') del constructor de Chart. Una paleta de Chart que se establece explícitamente puede anular los colores de la serie.

La apariencia debe ser consistente dentro de un documento del navegador, ya que las variables actuales de la UI y la clase univer-dark están escritas a la raíz del documento. Múltiples editores deben compartir una apariencia o utilizar documentos separados como iframes; contenedores separados por sí solos no aíslan los temas CSS.

Más información: Temas y modo oscuro · Configuración i18n · Plugins y Facade · Gráficos

Volver al resumen de funciones

¿Cómo es esta guía?

© 2026 DreamNum Co., Ltd.