Thèmes et localisation
Adaptez apparence, mode sombre et langues à votre application.
Les six produits utilisent le même service thématique, les mêmes ressources locales et la même configuration régionale, et les plugins personnalisés peuvent observer le même état. L'apparence de la marque et les préférences des utilisateurs peuvent changer pendant que l'application fonctionne, sans affecter les données et les styles stockés avec le contenu.
Le SDK comprend 19 options de langue et de région d'interface intégrées et 7 palettes thématiques. Les six produits partagent l'apparence, la configuration locale et régionale, et les thèmes personnalisés et les traductions d'applications utilisent les mêmes services.
Un même état pour l’interface et le rendu
ThemeService stocke la palette complète et l'état en mode sombre séparément, et publie les modifications via currentTheme$ et darkMode$. L'interface utilisateur élargit la palette en --univer-* variables CSS et répond à la classe univer-dark . Les soumissionnaires s'abonnent au même service et marquent les composants affectés pour repeindre. Le service couleur Canvas résout les jetons, map les couleurs pour l'affichage sombre et cache les résultats.
La configuration et les exemples de ce chapitre s'appliquent à @univerjs/* et @univerjs-pro/* 1.2.0. Gardez les versions de dépendance SDK alignées dans votre application.
| Paramètre | Options et portée | API à l’exécution |
|---|---|---|
theme | 7 palettes intégrées, ou un Theme complet personnalisé. | setTheme() |
darkMode | true / false, valeur par défaut false ; indépendant de la palette. | toggleDarkMode() |
locale | 19 valeurs LocaleType intégrées; chargez d'abord les ressources correspondantes. | setLocale() |
locales | Ressources de produit, de fonctionnalité et d'application combinées par identifiant local. | loadLocales() |
region | Les mêmes valeurs LocaleType ; suit la locale de l'interface utilisateur jusqu'à ce qu'elle soit définie explicitement. | setRegion() |
direction | ltr / rtl, par défaut ltr; s'applique uniquement aux menus et à l'interface utilisateur similaire. | setDirection() |
Construire une marque à partir d’une palette complète
@univerjs/themes fournit primary, gray, les échelles de couleurs fonctionnelles, loop-color, et highlight.background. Copier un thème intégré, remplacer les branches qui nécessitent des changements, et garder la structure complète. setTheme() remplace un thème entier; il ne remplit pas un objet partiel. L'exemple ci-dessous fournit une échelle de marque violette continue.
Les 7 palettes intégrées sont blueTheme, darkBlueTheme, greenTheme, orangeTheme, purpleTheme, redTheme et yellowTheme.
defaultTheme est un alias de blueTheme. La palette et l'état en mode sombre sont sélectionnés séparément. Les branches configurables sont les suivantes:
| Branche du thème | Options configurables |
|---|---|
primary | 10 niveaux de marque : 50, puis 100 à 900. |
gray | 12 niveaux neutres : 0, 50, 100 à 900, et 1000. |
blue · red · orange · yellow · green · jiqing · indigo · purple · pink | 9 gammes fonctionnelles, chacune avec 10 niveaux. |
loop-color | Positions de couleur tournantes 12 qui marquent la palette de référence. |
highlight.background | 16 positions de surbrillance de fond, chacune avec color et 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', },};Passez le thème à l'intégration du produit sélectionné. Cet exemple utilise le préréglage du noyau de feuille (UniverSheetsCorePreset) et enregistre les clés de traduction appartenant à l'application; d'autres produits utilisent leur propre composition de plugin. Le préréglage accepte les options suivantes:
containerstring | HTMLElementValeur par défaut:'app'Élément DOM où monter l’éditeur, ou son identifiant.
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' })],});Changer l’apparence et suivre les préférences
setTheme() modifie la palette, et toggleDarkMode() modifie l'état en mode sombre. getCurrentTheme() et isDarkMode() lisent les valeurs actuelles. Le passage à darkBlueTheme seul ne permet pas le drapeau en mode foncé. Changer l'apparence ne nécessite pas de détruire et de recréer l'éditeur.
La fonction ci-dessous suit la préférence du système et retourne une fonction de nettoyage. Si l'application fournit un réglage d'apparence manuel, appelez toggleDarkMode() du gestionnaire pour ce réglage.
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);}Appelez la fonction après que l'éditeur a été configuré, et exécutez la fonction de nettoyage retournée lorsque le composant démonte ou s'arrête après le système. Dans React et des intégrations similaires, conservez l'instance existante et mettez-la à jour via Facade.
Adapter les plugins personnalisés au thème et à la langue
Custom DOM utilise les variables CSS injectées et fournit ses propres styles pour la classe sombre. Les variables contiennent des valeurs de palette, de sorte que le composant doit toujours appliquer l'état de mode sombre lui-même.
.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);}Les extensions de toile lisent les jetons en direct à travers ThemeService et obtiennent les couleurs utilisées pour dessiner à partir de ICanvasColorService. L'exemple ci-dessous combine le thème, le mode sombre et le local se transforme en un seul état observable. Il traduit les étiquettes et résout les couleurs lorsque l'état change, de sorte qu'aucune recherche ou allocation n'est répétée sur chaque cadre de dessin.
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')), }); })); }}Enregistrez ReportAppearance via DI et résolvez-le dans le plugin. Le contrôleur de vue ou de dessin s'inscrit à state$ et se rafraîchit. Le consommateur est propriétaire de l'abonnement, et le propriétaire du service appelle dispose(). Node.js fournit également des services thématiques et locaux, mais il n'injecte pas le navigateur CSS.
Mode sombre
Les captures d'écran ci-dessous ont été prises à partir des démos standard locales, dont l'interface utilisateur et le contenu sont en anglais. L'affichage sombre n'écrit pas les couleurs cartographiées à nouveau dans le Snapshot. L'apparence de l'application et le traitement de la page PDF sont des préoccupations distinctes; le résultat de la vérification PDF locale est décrit ci-dessous.
| Produit | Thème partagé | Mode sombre | UI multilingue |
|---|---|---|---|
| Sheet | ✓ | ✓ | ✓ |
| Doc | ✓ | ✓ | ✓ |
| Slide | ✓ | ✓ | ✓ |
| Relational Table | ✓ | ✓ | ✓ |
| Canvases | ✓ | ✓ | ✓ |
| ✓ | UI prise en charge ; problème d’affichage du contenu | ✓ |
La démo standard locale actuelle a un problème de visibilité du texte avec le contenu PDF en mode sombre; le mode lumineux s'affiche correctement. Cette capture d'écran affiche l'interface utilisateur de l'éditeur en mode sombre.
La couverture linguistique dépend des faisceaux de ressources fournis par les produits sélectionnés et les fonctionnalités installées. Une palette d'applications n'enregistre pas les produits, ne charge pas les locaux ou n'importe pas les feuilles de style.
19 options intégrées de langue et de région
LocaleType fournit les 19 options suivantes, y compris les variantes Chinoises traditionnelles, simplifiées et de Hong Kong. Les principaux paquets UI des six produits incluent ces ressources; la couverture dans les extensions dépend du paquet sélectionné. Les balises de bundle sont utilisées dans les chemins d'importation, et les valeurs d'enum correspondantes sont utilisées dans l'initialisation et la configuration Facade.
Portée du RTL: Arabe (ar-SA) et d'autres faisceaux locaux traduisent le texte de l'interface tels que les menus et les messages. direction: 'rtl' adapte actuellement des menus et une interface similaire seulement. La mise en page et l'édition de RTL dans la zone de contenu Canvas n'ont pas été mises en œuvre.
| Langue (nom natif) | Balise du paquet | Valeur de configuration |
|---|---|---|
| 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 |
Internationalisation des produits : Dans la source actuelle de 1.2.0, 92 modules dans les éditeurs Web SDK et Pro fournissent 1.751 fichiers d'entrée locale pour l'interface utilisateur partagée, les éditeurs de produits et les fonctionnalités telles que les formules, les formats de nombres et les commentaires. Chaque module maintient et publie ses propres ressources, et l'application combine les fonctionnalités qu'il permet avec les localités qu'il cible.
Le compte couvre les fichiers .ts d'entrée locale sous packages/*/src/locale dans les deux arbres sources, à l'exclusion des tests et des sous-répertoires générés. Cela ne signifie pas que chaque module couvre les 19 options. Certains modules incluent des langues supplémentaires; LocaleType définit l'ensemble intégré commun.
Composer les ressources par plugin, puis charger et sélectionner
LocaleService organise les ressources par locale et résout les étiquettes à travers des espaces de noms et des chemins de touches. mergeLocales() combine des préréglages de produits, des plugins de fonctionnalités et des traductions d'applications. loadLocales() fusionne les ressources à l'exécution et setLocale() sélectionne la langue.
L'exemple suivant ajoute des ressources chinoises à l'instance Sheet introduite plus tôt, commute l'interface utilisateur en chinois et conserve explicitement les conventions régionales allemandes. LocaleType.ZH_CN a la valeur zhCN; zh-CN est le formulaire utilisé dans les noms de fichiers groupés et les itinéraires de documentation.
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');}Les clés telles que sales-report.generate appartiennent au plugin qui les possède. Ecrivez des phrases traduites complètes et utilisez {0}, {1} pour les valeurs dynamiques, comme dans LocaleService.t('sales-report.ready', 'Alex'). Ne cachez pas les traductions lors de l'initialisation du module. Une fois les ressources initialisées, une clé manquante revient à la clé elle-même.
Distinguer langue, région et formats du contenu
| Couche | Effet réel |
|---|---|
locale d’interface | Menus, messages, libellés et certains comportements linguistiques, comme la segmentation documentaire. |
region | Actions de monnaie qui utilisent ce paramètre, affichage de la date/heure des commentaires et formatage des statistiques; aucune conversion de monnaie ou changement d'horodatage. |
| Formats numériques du contenu | Les formats de la feuille numéro/date sont des formats de cellules et la locale de contenu qui s'applique à eux; changer la région ne les réécrit pas tous. |
direction | Direction indépendante de l'assurance-chômage; changer la langue ou la région ne change pas automatiquement. |
Lorsqu'aucune région n'est spécifiée, la valeur par défaut correspondante s'applique. Une fois que la région est définie explicitement, elle peut être sélectionnée indépendamment du langage de l'interface. region n'est pas un paramètre de fuseau horaire. RTL adapte actuellement les menus et l'interface similaire uniquement, et la mise en page et l'édition de droite à gauche dans la zone de contenu Canvas n'ont pas été implémentées.
Frontières entre thèmes de contenu et d’application
Le thème de l'application contrôle le workbench et le rendu par défaut. Il ne réécrit pas les remplissages de cellules persistants, le texte, les formes, les annotations PDF, ou les couleurs de graphique explicite.
Les graphiques Pro utilisent un registre IEchartTheme séparé partagé par les graphiques Sheet, Doc, Slide et Canvas. Une application Theme n'est pas un thème graphique. Dans un hôte avec les plugins graphiques appropriés installés, importez le graphique Facade et enregistrez une définition complète:
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);}Sélectionnez le nom enregistré à travers setTheme('sales-brand') du constructeur de cartes. Une palette de cartes qui est définie explicitement peut surcharger les couleurs de la série.
L'apparence doit être cohérente dans un document de navigateur, car les variables d'interface utilisateur actuelles et la classe univer-dark sont écrites à la racine du document. Plusieurs éditeurs devraient partager une apparence ou utiliser des documents séparés comme les iframes; les conteneurs séparés à eux seuls n'isolent pas les thèmes CSS.
En savoir plus : Thèmes et mode sombre · Configuration i18n · Plugins et Facade · Graphiques
Que pensez-vous de ce guide ?