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.
| Ajuste | Opciones y alcance | API en ejecución |
|---|---|---|
theme | 7 paletas incorporadas, o un Theme personalizado completo. | setTheme() |
darkMode | true / false; valor predeterminado false. Independiente de la paleta. | toggleDarkMode() |
locale | 19 valores incorporados LocaleType; cargar primero los recursos correspondientes. | setLocale() |
locales | Recursos de productos, características y aplicaciones combinados por identificador local. | loadLocales() |
region | Los mismos valores de LocaleType; sigue el UI locale hasta que se establece explícitamente. | setRegion() |
direction | ltr / 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() |
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 tema | Opciones configurables |
|---|---|
primary | 10 niveles de marca: 50, y de 100 a 900. |
gray | 12 niveles neutros: 0, 50, de 100 a 900, y 1000. |
blue · red · orange · yellow · green · jiqing · indigo · purple · pink | 9 escalas funcionales, con 10 niveles cada una. |
loop-color | 12 posiciones de color giratorio que referencia fichas de paleta. |
highlight.background | 16 posiciones de resaltado de fondo, cada una con color y 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', },};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.
containerstring | HTMLElementValor predeterminado:'app'Elemento DOM donde se monta el editor, o su 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' })],});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.
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í.
.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.
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.
| Producto | Tema compartido | Modo oscuro | UI internacional |
|---|---|---|---|
| Sheet | ✓ | ✓ | ✓ |
| Doc | ✓ | ✓ | ✓ |
| Slide | ✓ | ✓ | ✓ |
| Relational Table | ✓ | ✓ | ✓ |
| Canvases | ✓ | ✓ | ✓ |
| ✓ | UI compatible; problema al mostrar contenido | ✓ |
La actual demo estándar local tiene un problema de visualización de texto con contenido PDF en modo oscuro; el modo de luz muestra correctamente. Esta captura muestra al editor UI en modo oscuro. El soporte de movimiento oscuro para contenido PDF todavía requiere corrección y verificación.
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 paquete | Valor de configuración |
|---|---|---|
| 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 |
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.
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.
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
| Capa | Efecto real |
|---|---|
locale de interfaz | Menús, mensajes, etiquetas y algunos comportamientos lingüísticos, como segmentación de documentos. |
region | Acciones 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 contenido | Los 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. |
direction | Direcció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:
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
¿Cómo es esta guía?