univer-customize-theme

Univer のテーマをカスタマイズする

公開 Facade やランタイムのテーマサービスを迂回せずに、完全な Univer テーマを作成して適用します。

ソースの基準：現在の Univer OSS および Pro のソースでは、マニフェスト上のバージョンは 1.0.0-beta.0 です。対象アプリケーションにインストールされている宣言を先に確認してください。同じバージョン表記の npm リリースでは、現在のソース API がまだ反映されていない場合があります。

ワークフロー

1. リクエストがアプリケーションのパレット、ダークモード、プラグインのスタイル、Pro Chart のテーマのどれに関するものか判断します。これらはそれぞれ別の仕様です。
2. 正確なインストールバージョンと統合モードを確認します。プリセットではプラグインと Facade 拡張機能が組み合わされます。Plugin Mode では、プラグインと /facade の明示的なインポートが必要です。
3. 組み込みテーマから完全な Theme を導出します。部分的なオブジェクトを手書きしたり、型アサーションで済ませたりしないでください。
4. 初期テーマを createUniver に渡します。対象の宣言に存在する場合に限り、現在の FUniver テーマメソッドを使用します。
5. プラグインやレンダリングのコードでは ThemeService を使い、ブラウザーの CSS では --univer-* 変数を使って、最新の色を取得します。
6. 有効になっているすべての製品ホストで、ライトとダークの表示を確認します。

完全なブランドパレットを作成する

所有パッケージからインポートし、対象アプリケーションと完全に同じバージョンの Univer を使用します。

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

現在のソーススキーマには、gray、セマンティックカラーのランプ、loop-color、highlight.background も含まれています。デザイン上、意図的に置き換える場合を除き、すべての分岐を保持してください。スキーマ、組み込みテーマ、リリース時の確認事項については、Theme API and migration を参照してください。

テーマを適用する

既存の createUniver 設定に初期テーマを追加します。その統合のロケール、プリセット、コンテナー、明示的なスタイルシートのインポートは変更しないでください。

const { univer, univerAPI } = createUniver({
  locale: LocaleType.EN_US,
  locales,
  presets,
  theme: brandTheme,
  darkMode: false,
});

現在のソースでは、ベース Facade を通じたランタイムでの変更がサポートされています。

univerAPI.setTheme(brandTheme);
univerAPI.toggleDarkMode(true);

const currentTheme = univerAPI.getCurrentTheme();
const darkMode = univerAPI.isDarkMode();

テーマの選択とダークモードは独立しています。setTheme() はダークモードを切り替えず、toggleDarkMode() はパレットを置き換えません。

Preset Mode ではベース Facade が構築されます。手動の Plugin Mode では、プラグインを登録した後に、公開コアエントリから Facade を構築します。

import { FUniver } from '@univerjs/core/facade';

const univerAPI = FUniver.newAPI(univer);

@univerjs/themes/facade パッケージはありません。インストール済みの FUniver 宣言に setTheme()、getCurrentTheme()、または isDarkMode() がない場合は、初期化時に完全なテーマを設定するか、アップグレードしてください。univer.__getInjector() にアクセスしてはいけません。

カスタムコードをテーマに対応させる

カスタム DOM には、UI ワークベンチが挿入する変数を使用します。

.brand-action {
  color: var(--univer-gray-0);
  background: var(--univer-primary-600);
  border-color: var(--univer-primary-700);
}

プラグインサービス、Canvas レンダリング、モデルコードでは、組み込みパレットをランタイムの状態としてインポートするのではなく、ThemeService を注入して、最新のトークンを解決します。

import { Inject, ThemeService } from '@univerjs/core';

export class SelectionColorProvider {
  constructor(
    @Inject(ThemeService) private readonly _themeService: ThemeService
  ) {}

  getColor(): string {
    return this._themeService.getColorFromTheme('primary.600');
  }
}

派生色をキャッシュする場合は currentTheme$ または darkMode$ を監視し、所有者のライフサイクルに合わせて購読を解除します。ヘッドレスランタイムには ThemeService はありますが、ブラウザーの CSS 変数は挿入されません。

6 つの製品と Pro Charts

1 つの Univer ランタイムでは、Sheets、Docs、Slides、Bases、Boards、PDFs 間でコアの ThemeService が共有されます。テーマの設定では、製品プラグインの登録、ロケールの読み込み、CSS の読み込みは行われません。集約プリセットの CSS、または Plugin Mode で選択したすべてのスタイルシートを維持してください。

Slides、Boards、PDF テーブル、Sheet 範囲、Pro Charts にも、コンテンツレベルのテーマ／スタイルシステムがあります。これらはアプリケーションのパレットとは同じ仕様ではありません。コンテンツやチャートの色を変更する前に、Products and Pro themes を確認してください。

ブラウザー全体に適用される境界

現在の UI ワークベンチは、1 つの :root スタイル要素にフラット化した変数を書き込み、document.documentElement の univer-dark を切り替えます。そのため、同じドキュメント内に複数のブラウザー UI インスタンスがあっても、CSS パレットやダークモードのクラスは分離されません。最後に行われたドキュメントレベルの更新が適用されます。また、現在の破棄処理では、以前のドキュメントレベルのスタイルやルートクラスは復元されません。共通の外観を使用するか、iframe など別のドキュメント内にエディターを分離してください。univer.dispose() によってホストページの外観が復元されると保証してはいけません。

検証

• すべての Univer パッケージで、対象アプリケーションと同じリリースが使われていることを確認します。
• Theme 全体の型をチェックします。一部だけのオブジェクトをキャストしないでください。
• 必須のプリセット／プラグインスタイルが引き続き読み込まれることを確認します。
• ワークベンチのマウント後に、初期テーマ設定と、サポートされているランタイム切り替えをテストします。
• ライトモードとダークモードの両方で、DOM UI とキャンバスの内容を確認します。
• 有効化されているすべての製品ホストと Pro Charts を個別にテストします。
• テキスト、フォーカス、選択、エラー、無効状態のコントラストを確認します。

避けること

• 組み込みテーマオブジェクトを変更しないでください。ネストしたスプレッド構文でコピーしてください。
• document.head を変更したり、自分で ThemeSwitcherService をインスタンス化したりしないでください。
• 生成された --univer-* の値を信頼できる情報源として上書きしないでください。次のテーマ出力で置き換えられます。
• プラグイン内で、ランタイムの最新カラーを defaultTheme から読み取らないでください。
• アプリケーションのテーマを変更すると、永続化された製品コンテンツのカラーも書き換えられると思い込まないでください。
• 0.25.0 のコードを、バージョン文字列だけ変えて移行しないでください。スキーマ、組み込み機能、Facade の公開 API が変更されています。

参考資料

• テーマ API と移行 — 正確なスキーマ、組み込み機能、Facade／ThemeService API、CSS のフラット化、ダークモード、リリース条件、0.25.0 での変更点
• 製品と Pro のテーマ — 6 製品の動作、CSS の管理、製品コンテンツのテーマ、独立した Pro Chart テーマ API