プラグインと Facade 拡張
必要な機能を組み合わせ、公開 API でコンテンツと業務 UI を拡張します。
Univerは、プラグインから製品と機能をビルドし、Facade APIを介してコンテンツの操作を公開します。アプリケーションは、コンテンツエンジン、機能、および必要なUIを選択するか、プラグインとして独自のビジネスロジックをパッケージ化し、アプリケーションとエージェントツールがコールするタイプされたメソッドを提供します。
必要なコンテンツ機能を組み合わせる
プリセットは、クイックスタートのために意図されているプラグインの事前組み立て済みコレクションです。 プラグインモードでは、ホストは製品、機能、および構成を明示的に選択します。 どちらのモードも同じプラグインメカニズムを使用します。
| 層 | 役割 | 主な構成要素 |
|---|---|---|
| 製品とコンテンツモデル | Unit、コンテンツ構造、基本操作を管理する。 | Sheet、Doc、Slide、Relational Table、Canvases、PDF の製品プラグイン。 |
| 機能プラグイン | 特定分野の機能を追加する。 | 数式、フィルター、チャート、コメントなど。 |
| UI と描画プラグイン | 表示と操作の入口を提供する。 | Canvas 描画、メニュー、ツールバー、ショートカット、コンポーネント。 |
| Facade 拡張 | 導入済みの機能を公開 API として提供する。 | ワークブック、範囲、文書、オブジェクトの操作と意味のあるイベント。 |
UI から製品ロジックを分離することで、Node.js、ワーカー、またはブラウザで実行する適切なコンテンツ機能が可能になります。 Headless ホストは、必要なコンテンツプラグインのみを登録します。メニュー、DOM、インタラクション API は、UI 環境を要求します。
依存関係、ライフサイクル、リソースの所有者
プラグインは、@DependentOn(...) と直接依存関係を宣言し、ランタイムはそれらを解決し、構造の順序を決定します。依存性プラグインが欠落しているとき、ランタイムがデフォルト設定でそれを登録します。依存性がカスタム設定を必要とするとき、最初にそれを登録し、設定します。このメカニズムはパッケージをインストールせず、スタイル、ロケール、ファサードエントリ、またはワーカーをインポートしません。
プラグイン内では、依存性インジェクション(DI)は、サービス、コントローラー、モデルをパブリックサービス識別子に接続します。プラットフォームの実装は、サポートされている構成やインジェクション境界に置き換えることができます。そのため、ビジネスロジックは、すべての依存関係自体の構築と管理する必要はありません。
| フック | 適した処理 |
|---|---|
onStarting() | 依存関係、コマンド、コントローラーを登録する。未作成の Unit や DOM を参照しない。 |
onReady() | 対応するコンテンツが準備完了したらモデルに依存するロジックを初期化します。 |
onRendered() | レンダラー、Canvas、DOM が必要な拡張を初期化する。 |
onSteady() | 初期レンダリングが要求されない作業を遅らせます。 |
所有者は、コマンド登録、イベントサブスクリプション、ショートカット、およびレンダーモジュールを管理します。 登録が使い捨てを返すと、プラグインまたはコントローラとともにリリースされるようにdisposeWithMe()を呼び出します。 mergeMenu()は現在、voidを返しますので、使い捨てではありません。
異なる入口でコンテンツ変更の仕組みを共有する
ツールバー、ショートカット、およびビジネス API は、同じビジネスコマンドを呼び出すことができます。Agent ホストは、必要な機能がインストールされた後、そのエントリ ポイントを再使用できます。コマンド システムは、ビジネスの意図、永続的な変更、および一時的なインタラクションを分離します。
| 種類 | 役割 | 例 |
|---|---|---|
COMMAND | 対象を検証し、業務手順、Mutation、Operation を組み立てる。 | 売上レポートの書き込み、行の削除。 |
MUTATION | コンテンツモデルを明示的、シリアライズ可能なパラメータで変更することで、変更が再再生され、コラボレーションによって処理することができます。 | セル内容の更新、行の挿入。 |
OPERATION | 一時的な操作状態を変更する。 | 選択範囲、スクロール位置、パネルの変更。 |
たとえば、SetRangeValuesMutation を生成し、undo データを準備する FRange.setValues() インボイス SetRangeValuesCommand。すべてのコンテンツの変更は、同じ実行パスに従います。そのため、異なるエントリ ポイントは、既存のバリデーション、インターセプター、および変更処理を再利用します。 意図しない、コラボレーション、および各メカニズムに応じて、図内の履歴は、それぞれ異なるメカニズムに依存します。 Mutation を単独で登録することはそれらを提供していません。
プラグインの機能を Facade API として公開する
ファサードは、コンテンツオブジェクト指向のパブリックインターフェイスを提供し、内部サービス外観とコマンドパラメータアセンブリを隠します。 拡張機能は、既存のファサードメソッドを構成したり、プラグイン自身のビジネスコマンドを呼び出したりすることができます。
以下の拡張子は、generateSalesReport() を FUniverに追加します。このコマンドは、次のセクションで実行されます。このファイルは、ランタイムメソッド、ランタイム登録、TypeScript タイプの3つの部分があります。
sales-report.facade.ts
import { FUniver } from '@univerjs/core/facade';import type { ISalesReportParams } from './sales-report.plugin';import { GenerateSalesReportCommand } from './sales-report.plugin';export interface IFUniverSalesReport { generateSalesReport(params: ISalesReportParams): Promise<boolean>;}export class FUniverSalesReport extends FUniver implements IFUniverSalesReport { override generateSalesReport(params: ISalesReportParams): Promise<boolean> { return this._commandService.executeCommand(GenerateSalesReportCommand.id, params); }}FUniver.extend(FUniverSalesReport);declare module '@univerjs/core/facade' { interface FUniver extends IFUniverSalesReport {}}FUniver.extend()はランタイムでメソッドをインストールし、モジュールの拡張はタイプを供給します。コンシューマーは、サイドエフェクトのインポートを通してエクステンションファイルを実行する必要があります。クラスをエクスポートしたり、プラグインを登録しても別のファサードエントリを実行しません。公開されたパッケージは、専用の/facadeサブパスを明示し、package.json#sideEffectsを通してその登録副作用を保存することができます。
このパターンは、extend()を明示的にサポートするファサードクラスのみに適用されます。 ファサードクラスがエクスポートされるという事実は、それがミックスインターゲットとして機能することができないという意味ではありません。 メソッド名は明確に意味して、既存のメソッドや他の拡張と衝突してはいけません。
例:アプリと Agent で同じ売上レポートを作る
この最小限のビジネスプラグインは、指定されたシートのA1:D5に英語のセールスデータ、要約式、およびヘッダースタイルを書き、その範囲を置き換えます。 ワークブックIDとワークシートIDは、現在の選択またはフォーカスから取られたのではなく、呼び出し側によって明示的に渡されます。
コマンドは、まず、ターゲットと範囲の寸法を確認し、そのコンテンツ変更と undo/redo ロジックが再使用されるように、既存の SetRangeValuesCommand を呼び出します。プラグインは、onStarting()でコマンドを登録し、使い捨てを所有しています。このデータは修正され、図としてのみ機能します。アプリケーションは、検証されたビジネス入力でそれを置き換える必要があります。
出力例。 プレゼンテーション色、数値の書式、および行と列の寸法は、読みやすさのために調整されました。
sales-report.plugin.ts
import type { ICellData, ICommand, Workbook } from '@univerjs/core';import { CommandType, DependentOn, ICommandService, Inject, Injector, IUniverInstanceService, Plugin, UniverInstanceType,} from '@univerjs/core';import { SetRangeValuesCommand, UniverSheetsPlugin } from '@univerjs/sheets';export interface ISalesReportParams { unitId: string; subUnitId: string;}export const GenerateSalesReportCommand: ICommand<ISalesReportParams> = { id: 'sales-report.command.generate', type: CommandType.COMMAND, handler: (accessor, params) => { if (!params) return false; const sheet = accessor.get(IUniverInstanceService) .getUnit<Workbook>(params.unitId, UniverInstanceType.UNIVER_SHEET) ?.getSheetBySheetId(params.subUnitId); if (!sheet || sheet.getRowCount() < 5 || sheet.getColumnCount() < 4) return false; const value: ICellData[][] = [ ['Region', 'Q1', 'Q2', 'H1 Total'].map((v) => ({ v, t: 1, s: { bg: { rgb: '#17324D' }, cl: { rgb: '#FFFFFF' }, bl: 1 }, })), [{ v: 'East', t: 1 }, { v: 128000, t: 2 }, { v: 142000, t: 2 }, { f: '=SUM(B2:C2)' }], [{ v: 'West', t: 1 }, { v: 96000, t: 2 }, { v: 118000, t: 2 }, { f: '=SUM(B3:C3)' }], [{ v: 'North', t: 1 }, { v: 110000, t: 2 }, { v: 125000, t: 2 }, { f: '=SUM(B4:C4)' }], [{ v: 'Total', t: 1 }, { f: '=SUM(B2:B4)' }, { f: '=SUM(C2:C4)' }, { f: '=SUM(D2:D4)' }], ]; return accessor.get(ICommandService).executeCommand(SetRangeValuesCommand.id, { ...params, range: { startRow: 0, endRow: 4, startColumn: 0, endColumn: 3 }, value, }); },};@DependentOn(UniverSheetsPlugin)export class SalesReportPlugin extends Plugin { static override pluginName = 'SALES_REPORT_PLUGIN'; static override type = UniverInstanceType.UNIVER_SHEET; constructor( _config: undefined, @Inject(Injector) protected override readonly _injector: Injector, @ICommandService private readonly _commands: ICommandService, ) { super(); } override onStarting(): void { this.disposeWithMe(this._commands.registerCommand(GenerateSalesReportCommand)); }}シートの設置ガイドで製品と式機能を設定し、ビジネスプラグインを登録し、ファサード拡張をインポートし、それを呼び出します。 この例では、univerは、その構成が既に完了したインスタンスです。 Node.jsの設定については、headless Univerを参照してください。
import { FUniver } from '@univerjs/core/facade';import '@univerjs/sheets/facade';import '@univerjs/engine-formula/facade';import { SalesReportPlugin } from './sales-report.plugin';import './sales-report.facade';univer.registerPlugin(SalesReportPlugin);const univerAPI = FUniver.newAPI(univer);const workbook = univerAPI.createWorkbook({ name: 'Quarterly Sales' });const worksheet = workbook.getActiveSheet();const target = { unitId: workbook.getId(), subUnitId: worksheet.getSheetId() };const generated = await univerAPI.generateSalesReport(target);if (!generated) throw new Error('Sales report could not be generated');await univerAPI.getFormula().onCalculationResultApplied();console.log(worksheet.getRange('D5').getValue()); // 719000成功したコマンド結果は、コンテンツの書き込みが完了したことを示します。 計算結果が、式の値を読む前に適用されるのを待ってください。 この例では、D5は719000です。
アプリケーションボタンは、クリックハンドラからgenerateSalesReport(target)を呼び出すことができます。 エージェントツールハンドラは、ヘッドレスホストが同じプラグインとファサード拡張をインストールした後、同じメソッドを呼び出すことができます。 ビジネスアクションとターゲットは同じままです。 UIはエントリポイントとフィードバックを供給します。 カスタムプラグインをインストールすると、メソッドをエージェントツールとして自動的に明示しません。 ツール登録とユニット認証は、アプリケーションの責任を保っています。
実装上の境界と関連資料
- この例では、
SetRangeValuesCommandを再利用します。新しい Mutation は、逆の操作と対応するコラボレーションの統合が必要です。新しい永続リソースはシリアライズも必要です。したがって、下書きモデルに直接書きません。 - 実行、計算、および送信は別のステップであり、複数のファサードコールは自動原子トランザクションを形成しません。 この例では、単一の範囲の書き込みを実行します。 共同ホストは、ランタイム契約の下で変更を提出し、確認します。
- 実行する環境に応じてプラグインをコンパイルします。 コンテンツプラグインとUIプラグインを別々にインストールし、Univerリリーストレインパッケージを同じバージョンに保ち、UIコピー用のローカライズリソースを使用します。 エージェントのエントリポイントは、アプリケーションが所有する認可とパラメータの検証を必要とします。
関連資料:Univer アーキテクチャ · Facade の導入 · Facade API リファレンス · UI カスタマイズ · Agent と自動化
このガイドはいかがですか?