univer-plugin-dev

Univer プラグイン開発

Univer の機能を拡張するカスタムプラグインの作成ガイドです。

互換性: このスキルは Univer v0.21.x 向けに記述されています。プラグインの基本的なパターン（ライフサイクル、DI、コマンド）は安定していますが、サービスのトークンやファサードクラスは変更される場合があります。ここにある例と異なる場合は、ユーザーの既存コードベースのパターンを優先してください。

クイックスタート

新しいプラグインのひな形を作成する

同梱のスクリプトを使って、最小限のプラグインのひな形を生成します。

# If installed to ~/.codex/skills/
npx tsx ~/.codex/skills/univer-plugin-dev/scripts/scaffold-plugin.ts my-plugin --path ./src/plugins

# Or from this repo directly
npx tsx ~/univer-sdk-skills/skills/univer-plugin-dev/scripts/scaffold-plugin.ts my-plugin --path ./src/plugins

次のものが作成されます。

my-plugin/
├── src/
│   ├── index.ts
│   ├── plugin.ts
│   ├── commands/
│   │   └── commands.my-command.ts
│   ├── controllers/
│   │   └── my-menu.controller.ts
│   └── facade/
│       └── f-univer.ts
├── package.json
└── tsconfig.json

アプリにプラグインを登録する

import { MyPlugin } from './plugins/my-plugin/src';
import './plugins/my-plugin/src/facade/f-univer'; // side-effect import for Facade extension

univer.registerPlugin(MyPlugin);

基本概念

プラグインのライフサイクル

プラグインは Plugin を継承し、ライフサイクルフックをオーバーライドします。

フック	タイミング	実行する処理
onStarting()	プラグインがマウントされた後、ユニットがまだない状態	コマンド、サービス、メニュー、ショートカットを登録する
onReady()	ビジネスユニットが作成されたとき	ワークブック／ドキュメントのインスタンスにアクセスする
onRendered()	UI がレンダリングされたとき	DOM に依存する初期化を行う
onSteady()	すべてが安定したとき	バックグラウンドタスクを実行する

リソースがプラグインの破棄時に自動的にクリーンアップされるよう、破棄可能なリソースの登録には必ず disposeWithMe() を使用してください。

コマンドシステム

コマンドには 3 種類あります。

• COMMAND — ビジネス上のエントリーポイントです。変更や操作を統括します。IUndoRedoService に手動で追加すれば、取り消し／やり直しに対応できます。
• MUTATION — アトミックなデータ変更です。スナップショットに保存され、自動的に取り消し可能になります。
• OPERATION — UI の状態変更です。保存されず、取り消しもできません。

各タイプと取り消し／やり直しの構築方法の完全な例については、references/command-system.md を参照してください。

依存性の注入

Univer はカスタム DI コンテナー（Injector）を使用します。サービスは次の方法で取得します。

// Constructor injection
@Inject(IMenuManagerService) private readonly _menuService: IMenuManagerService

// Accessor injection (in command handlers)
const service = accessor.get(IMenuManagerService);

一般的なサービスのトークン：

• ICommandService — コマンドの登録／実行
• IMenuManagerService — メニュー／ツールバー項目の追加
• IShortcutService — キーボードショートカットの登録
• IContextMenuService — コンテキストメニュー
• ComponentManager — React コンポーネント／アイコンの登録
• IUniverInstanceService — 現在のワークブック／ドキュメント／スライドの取得
• IUndoRedoService — 取り消し／やり直しのエントリーの追加

ファサードの拡張

Facade クラスを拡張して、プラグインの機能をエンドユーザーに公開します。

import { FWorksheet } from '@univerjs/sheets/facade';

class FWorksheetMyMixin extends FWorksheet {
  myMethod(): this {
    // implementation
    return this;
  }
}

FWorksheet.extend(FWorksheetMyMixin);

declare module '@univerjs/sheets/facade' {
  interface FWorksheet extends FWorksheetMyMixin {}
}

よくあるタスク

サブメニュー、コンテキストメニュー、Range Popup、コンポーネントの置き換え、ツールバー＋コマンド＋ショートカットの一連の処理など、完全な例については references/ui-customization.md を参照してください。

ツールバーボタンを追加する

this._menuManagerService.mergeMenu({
  [RibbonOthersGroup.OTHERS]: {
    ['my-button']: {
      order: 10,
      menuItemFactory: () => ({
        id: 'my-button',
        title: 'My Button',
        type: MenuItemType.BUTTON,
      }),
    },
  },
});

コマンドを登録する

const MyCommand: ICommand = {
  id: 'my.command.id',
  type: CommandType.COMMAND,
  handler: (accessor) => {
    // business logic
    return true;
  },
};

this._commandService.registerCommand(MyCommand);

ファサードを拡張する

class FWorksheetMyMixin extends FWorksheet {
  myMethod(): this { return this; }
}
FWorksheet.extend(FWorksheetMyMixin);
declare module '@univerjs/sheets/facade' {
  interface FWorksheet extends FWorksheetMyMixin {}
}

参考資料

• プラグインのアーキテクチャ: references/plugin-architecture.md — ライフサイクル、DI、サービスの登録、コントローラーパターン
• コマンドシステム: references/command-system.md — COMMAND／MUTATION／OPERATION、取り消し／やり直し、ミューテーションファクトリー、カスタムミューテーション
• ファサードの拡張: references/facade-extension.md — FUniver、FWorkbook、FWorksheet、FRange の拡張、複数の拡張をマージする方法
• UI のカスタマイズ: references/ui-customization.md — メニュー、サブメニュー、ショートカット、コンテキストメニュー、ポップアップ、コンポーネントの置き換え
• イベントシステム: references/event-system.md — イベント、フック、カスタムイベント、RxJS ストリーム

次の項目については、univer-integrate スキルも参照してください。

• カスタム数式関数（univer-integrate スキル）
• 権限（univer-integrate スキル）
• ネットワークレイヤー（univer-integrate スキル）

スクリプト

• ひな形生成: scripts/scaffold-plugin.ts — 新しいプラグインのひな形を生成します