プラグイン開発チートシート

プラグインを書いていると「これはどのファイルに書けばいいの？どの API を呼べばいいの？」と迷うことがよくあります。このチートシートで素早く確認できます。

プラグインのディレクトリ構成

yarn pm create @my-project/plugin-name でプラグインを作成すると、以下のディレクトリ構成が自動生成されます。手動でディレクトリを作成しないでください。登録手順の漏れでプラグインが動作しなくなります。詳しくははじめてのプラグインを書くをご覧ください。

plugin-name/
├── src/
│   ├── client-v2/              # クライアントコード（v2）
│   │   ├── plugin.tsx          # クライアントプラグインエントリ
│   │   ├── locale.ts           # useT / tExpr 翻訳 hook
│   │   ├── models/             # FlowModel（ブロック、フィールド、操作）
│   │   └── pages/              # ページコンポーネント
│   ├── client/                 # クライアントコード（v1、互換性用）
│   │   ├── plugin.tsx
│   │   ├── locale.ts
│   │   ├── models/
│   │   └── pages/
│   ├── server/                 # サーバーサイドコード
│   │   ├── plugin.ts           # サーバープラグインエントリ
│   │   └── collections/        # データテーブル定義
│   └── locale/                 # 多言語翻訳ファイル
│       ├── zh-CN.json
│       └── en-US.json
├── client-v2.js                # ルートエントリ（ビルド成果物の参照先）
├── client-v2.d.ts
├── client.js
├── client.d.ts
├── server.js
├── server.d.ts
└── package.json

クライアント：やりたいこと → 書き方

やりたいこと	どのファイルに書くか	呼び出す API	ドキュメント
ページルートを登録する	`plugin.tsx` の `load()`	`this.router.add()`	Router
プラグイン設定ページを登録する	`plugin.tsx` の `load()`	`pluginSettingsManager.addMenuItem()` + `addPageTabItem()`	Router
カスタムブロックを登録する	`plugin.tsx` の `load()`	`this.flowEngine.registerModelLoaders()`	FlowEngine → ブロック拡張
カスタムフィールドを登録する	`plugin.tsx` の `load()`	`this.flowEngine.registerModelLoaders()`	FlowEngine → フィールド拡張
カスタム操作を登録する	`plugin.tsx` の `load()`	`this.flowEngine.registerModelLoaders()`	FlowEngine → 操作拡張
内部テーブルをブロックのデータテーブル選択に表示する	`plugin.tsx` の `load()`	`mainDS.addCollection()`	Collections データテーブル
プラグインのテキストを翻訳する	`locale/zh-CN.json` + `locale/en-US.json`	—	i18n 国際化

サーバーサイド：やりたいこと → 書き方

やりたいこと	どのファイルに書くか	呼び出す API	ドキュメント
データテーブルを定義する	`server/collections/xxx.ts`	`defineCollection()`	Collections データテーブル
既存のデータテーブルを拡張する	`server/collections/xxx.ts`	`extendCollection()`	Collections データテーブル
カスタム API を登録する	`server/plugin.ts` の `load()`	`this.app.resourceManager.define()`	ResourceManager
API の権限を設定する	`server/plugin.ts` の `load()`	`this.app.acl.allow()`	ACL アクセス制御
プラグインインストール時に初期データを投入する	`server/plugin.ts` の `install()`	`this.db.getRepository().create()`	Plugin プラグイン

FlowModel チートシート

やりたいこと	継承する基底クラス	主な API
純粋な表示ブロックを作る	`BlockModel`	`renderComponent()` + `define()`
データテーブルにバインドするブロックを作る（カスタムレンダリング）	`CollectionBlockModel`	`createResource()` + `renderComponent()`
完全なテーブルブロックを作る（組み込みテーブルをベースにカスタマイズ）	`TableBlockModel`	`filterCollection()` + `customModelClasses`
フィールド表示コンポーネントを作る	`ClickableFieldModel`	`renderComponent(value)` + `bindModelToInterface()`
操作ボタンを作る	`ActionModel`	`static scene` + `registerFlow({ on: 'click' })`

翻訳メソッドチートシート

シーン	使うもの	インポート元
Plugin `load()` 内	`this.t('key')`	Plugin 基底クラスに組み込み済み
React コンポーネント内	`const t = useT(); t('key')`	`locale.ts`
FlowModel 静的定義（`define()`、`registerFlow()`）	`tExpr('key')`	`locale.ts`

よく使う API チートシート

やりたいこと	Plugin 内	コンポーネント内
API リクエストを送る	`this.context.api.request()`	`ctx.api.request()`
翻訳を取得する	`this.t()`	`useT()`
ログを出力する	`this.context.logger`	`ctx.logger`
ルートを登録する	`this.router.add()`	—
ページ遷移する	—	`ctx.router.navigate()`
ダイアログを開く	—	`ctx.viewer.dialog()`

#プラグイン開発チートシート

#プラグインのディレクトリ構成

#クライアント：やりたいこと → 書き方

#サーバーサイド：やりたいこと → 書き方

#FlowModel チートシート

#翻訳メソッドチートシート

#よく使う API チートシート

#関連リンク