テーマと多言語対応

エディターの外観、ダークモード、言語リソースをアプリケーションに合わせます。

テーマと国際化は、共有ランタイムサービスです。6つの製品は、同じテーマサービス、ローカライズリソース、および地域の構成を使用しており、カスタムプラグインは同じ状態を観察できます。アプリケーションが実行中の間、ブランドの外観とユーザー設定は変更できます。コンテンツに格納されているデータやスタイルに影響を与えません。

SDKには、19 組み込みインターフェイス言語と地域オプションと7テーマパレットが含まれています。6つの製品は、外観、ロケール、地域構成、カスタムテーマ、アプリケーション翻訳を同じサービスで共有します。

同じ状態から UI と描画を更新する

ThemeService パレットとダークモードの状態を別々に保存し、変更を通した公開 currentTheme$ そして、 darkMode$. UI はパレットを拡大します。 --univer-* CSS変数と対応 univer-dark クラス。 レンダリング者は同じサービスに購読し、影響を受けたコンポーネントを塗り直します。 キャンバスカラーサービスは、トークンを解決し、ダークディスプレイ用の色をマップし、結果をキャッシュします。

この章では、@univerjs/*と@univerjs-pro/* 1.2.0の構成と例が適用されます。SDKの依存バージョンがアプリケーションに整列されていることを確認してください。

設定選択肢と範囲実行時 API
theme7つの組み込みパレット、または完全な習慣Theme。setTheme()
darkModetrue / false。既定値は false。パレットとは独立。toggleDarkMode()
locale19 組み込み LocaleType 値; マッチングリソースを最初に読み込む.setLocale()
localeslocale 識別子によって結合される製品、機能、およびアプリケーションリソース。loadLocales()
region同じ LocaleType 値; 明示的に設定されるまで UI のロケールに従ってください。setRegion()
directionltr / rtl、デフォルトltr; メニューと類似のUIのみに適用されます。 キャンバスコンテンツはまだRTLをサポートしていません。setDirection()
100%

完全なパレットからブランドテーマを作る

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

選択した製品統合にテーマを渡します。この例では、シートコアプリセット(UniverSheetsCorePreset)を使用し、アプリケーションが所有する翻訳キーを登録します。他の製品は、独自のプラグイン構成を使用します。プリセットは、次のオプションを受け入れます。

  • container
    string | HTMLElement既定値: 'app'
    エディターを配置する DOM 要素またはその 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' })],});

実行時に切り替え、表示設定へ追従する

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 と類似の統合では、既存のインスタンスを保持し、ファサードを介して更新します。

独自プラグインもテーマと言語へ追従させる

カスタム 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);}

キャンバスエクステンションは、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を注入しません。

ダークモード

シート、ドキュメント、スライド、リレーショナルテーブル、キャンバス、およびPDFはすべて共有テーマとダークモードを使用します。 下のスクリーンショットは、UIとコンテンツが英語であるローカル標準のデモから撮影されました。 ダークディスプレイは、マップされた色をスナップショットに書きません。 アプリケーション外観とPDFページの処理は別の懸念です。 ローカルPDF検証の結果は以下に説明されています。

製品共有テーマダークモードUI 国際化
Sheet✓✓✓
Doc✓✓✓
Slide✓✓✓
Relational Table✓✓✓
Canvases✓✓✓
PDF✓UI 対応・本文に表示問題あり✓

言語カバレッジは、選択した製品とインストールされた機能によって提供されるリソースバンドルによって異なります。 アプリケーションパレットは、製品を登録したり、ローカルをロードしたり、スタイルシートをインポートしたりしません。

19 の組み込み言語・地域オプション

LocaleTypeは、簡体字、繁体字、香港伝統の中国のバリエーションを含む、次の19オプションを提供しています。すべての6つの製品のメインUIパッケージには、これらのリソースが含まれます。拡張のカバレッジは、選択したパッケージによって異なります。バンドルタグはインポートパスで使用され、マッチングエンマ値は初期化とファサード構成で使用されます。

RTL スコープ: アラビア語 (ar-SA) と他の locale バンドルは、メニューやメッセージなどのインターフェイステキストを翻訳します。 direction: 'rtl' 現在、メニューと類似の UI のみを適応させます。 キャンバスのコンテンツエリアでのRTLレイアウトと編集は実装されていません。

言語(現地名)言語パックのタグ設定値
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 そしてプロ エディターは提供します 1,751 ロケールエントリーファイル 共有UI、製品エディタ、および式、数フォーマット、コメントなどの機能。各モジュールは、独自のリソースを維持し、公開し、アプリケーションは、ターゲットを絞ったロケールを有効にできる機能を統合します。

カウントは、テストと生成されたサブディレクトリを除く、両方のソースツリーのpackages/*/src/localeの下でローカルエントリー.tsファイルをカバーします。 すべてのモジュールは、すべての19オプションをカバーするという意味ではありません。 一部のモジュールには、追加の言語が含まれます。 LocaleTypeは、一般的な組み込みセットを定義します。

プラグインごとに言語リソースを組み合わせる

LocaleServiceは、ローカルでリソースを整理し、名前空間とキーパスを介してラベルを解決します。 mergeLocales() は、製品プリセット、機能プラグイン、およびアプリケーション翻訳を組み合わせたものです。 loadLocales()が実行時にリソースをマージし、setLocale()では言語を選択します。 ロケールを選択すると、そのバンドルはダウンロードしません。

100%

次の例では、以前紹介したSheetインスタンスに中国のリソースを追加し、UIを中国語に切り替え、ドイツ地域の慣行を明示的に保持します。 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')のように。モジュールの初期化で翻訳をキャッシュしないでください。リソースが初期化された後、現在のキー自体に戻ります。インターフェイス言語を切り替えると、コンテンツを翻訳したり、既存のユニットの名前を変更したりすることはありません。

言語、地域、コンテンツの書式を分ける

層影響
UI localeメニュー、メッセージ、プラグイン表示と、文書分かち書きなど一部の言語処理。
regionこの設定、コメント日時表示、統計フォーマットを使用する通貨アクション。通貨変換やタイムスタンプの変更はありません。
内容の数値書式保存されたシート番号/日付のフォーマットは、セル形式とそれらに適用されるコンテンツのロケールに従います。 領域の変更は、それらをすべて書き換えません。
direction独立したUIの方向;言語または地域を変えることは自動的にそれを転換しません。

領域が指定されていない場合、対応するデフォルトが適用されます。 領域が明示的に設定されると、インターフェイス言語の独立して選択できます。 regionはタイムゾーンの設定ではありません。 RTLは現在、メニューと類似のUIのみを適応させ、キャンバスコンテンツエリアでの右から左のレイアウトと編集は実装されていません。

コンテンツテーマとアプリテーマの境界

アプリケーションテーマは、ワークベンチとレンダリングのデフォルトを制御します。 これは、永続化されたセルの塗りつぶし、テキスト、図形、PDF注釈、または明示的なチャートの色を書き換えません。 範囲とテーブルのテーマ、スライドカラースキーム、およびキャンバスのコンテンツテーマは、対応するパブリック製品機能を介して管理されます。

プロチャートは、シート、ドキュメント、スライド、およびキャンバスチャートで共有される別のIEchartThemeレジストリを使用します。 アプリケーションThemeはチャートテーマではありません。 適切なチャートプラグインがインストールされているホストでは、チャートファサードをインポートし、完全な定義を登録します。

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')から登録名を選択します。 明示的に設定されたチャートパレットは、シリーズの色を上書きすることがあります。

現在のUI変数とuniver-darkクラスがドキュメントルートに書かれているため、外観は1つのブラウザの文書内で一貫しなければなりません。複数のエディタは1つの外観を共有したり、iframeなどの別の文書を使用する必要があります。別のコンテナはCSSのテーマを分離しません。

関連資料:テーマとダークモード · 国際化の詳細 · プラグインと Facade · チャート

機能一覧へ戻る

このガイドはいかがですか?

© 2026 DreamNum Co., Ltd.