フック | EmDash CMS Everything

フックはプラグインがイベントに応答してコードを実行できるようにします。すべてのフックはイベントオブジェクトとプラグインコンテキストを受け取り、プラグイン定義時に宣言されます — ランタイムでの動的な登録はありません。

このページではサンドボックスプラグインについて説明します。フックはネイティブプラグインでも同様に動作します。ネイティブプラグインはさらに page:fragments を登録できます。

フックシグネチャ

すべてのフックハンドラーは2つの引数を取ります：

async (event, ctx) => ReturnType;

event — 発生したことに関するデータ（コンテンツの保存、メディアのアップロード、ライフサイクルの遷移など）
ctx — ストレージ、KV、ロギング、および機能制御APIを持つ PluginContext

デフォルトエクスポートの satisfies SandboxedPlugin がフック名（完全な正規イベントタイプ）から event を推論し、ctx を PluginContext として推論するため、ハンドラーにはパラメータアノテーションが不要です。ヘルパーでイベントタイプを名前で参照するには、emdash/plugin からインポートしてください。

フック設定

フックはシンプルなハンドラーとして、または設定オブジェクトでラップして宣言できます：

シンプル

hooks: {
	"content:afterSave": async (event, ctx) => {
		ctx.log.info("Content saved");
	},
},

完全な設定

hooks: {
	"content:afterSave": {
		priority: 100,
		timeout: 5000,
		dependencies: ["audit-log"],
		errorPolicy: "continue",
		handler: async (event, ctx) => {
			ctx.log.info("Content saved");
		},
	},
},

設定オプション

オプション	型	デフォルト	説明
`priority`	`number`	`100`	実行順序。小さい数値が先に実行されます。
`timeout`	`number`	`5000`	最大実行時間（ミリ秒）。
`dependencies`	`string[]`	`[]`	このフックの前に実行する必要があるプラグインID。
`errorPolicy`	`"abort" \| "continue"`	`"abort"`	エラー時にパイプラインを停止するかどうか。
`exclusive`	`boolean`	`false`	アクティブなプロバイダーは1つのプラグインのみ。`email:deliver` と `comment:moderate` で使用。
`handler`	`function`	—	フックハンドラー関数。必須。

ライフサイクルフック

プラグインのインストール、アクティベーション、非アクティベーション、削除時に実行されます。

`plugin:install`

プラグインが初めてサイトに追加されたときに一度だけ実行されます。

"plugin:install": async (_event, ctx) => {
	ctx.log.info("Installing plugin...");
	await ctx.kv.set("settings:enabled", true);
	await ctx.storage.items.put("default", { name: "Default Item" });
},

イベント: {} — 戻り値: Promise<void>

`plugin:activate`

プラグインが有効化されたとき（インストール後または再有効化時）に実行されます。

"plugin:activate": async (_event, ctx) => {
	ctx.log.info("Plugin activated");
},

イベント: {} — 戻り値: Promise<void>

`plugin:deactivate`

プラグインが無効化されたとき（ただし削除されていない）に実行されます。

"plugin:deactivate": async (_event, ctx) => {
	ctx.log.info("Plugin deactivated");
},

イベント: {} — 戻り値: Promise<void>

`plugin:uninstall`

プラグインがサイトから削除されたときに実行されます。

"plugin:uninstall": async (event, ctx) => {
	ctx.log.info("Uninstalling plugin...");
	if (event.deleteData) {
		const result = await ctx.storage.items.query({ limit: 1000 });
		await ctx.storage.items.deleteMany(result.items.map((i) => i.id));
	}
},

イベント: { deleteData: boolean } — 戻り値: Promise<void>

コンテンツフック

サイトコンテンツの作成、更新、削除操作時に実行されます。

`content:beforeSave`

コンテンツが保存される前に実行されます。変更されたコンテンツを返すか、変更しない場合は void を返します。キャンセルするには例外をスローします。

"content:beforeSave": async (event, ctx) => {
	const { content, collection } = event;

	if (collection === "posts" && !content.title) {
		throw new Error("Posts require a title");
	}

	if (typeof content.slug === "string") {
		content.slug = content.slug.toLowerCase().replace(/\s+/g, "-");
	}

	return content;
},

イベント: { content, collection, isNew } — 戻り値: 変更されたコンテンツまたは void。

`content:afterSave`

コンテンツが正常に保存された後に実行されます。通知、ロギング、外部同期などの副作用に使用します。

"content:afterSave": async (event, ctx) => {
	ctx.log.info(`${event.isNew ? "Created" : "Updated"} ${event.collection}/${event.content.id}`);

	if (ctx.http) {
		await ctx.http.fetch("https://api.example.com/webhook", {
			method: "POST",
			body: JSON.stringify({ event: "content:save", id: event.content.id }),
		});
	}
},

イベント: { content, collection, isNew } — 戻り値: Promise<void>

`content:beforeDelete`

コンテンツが削除される前に実行されます。キャンセルするには false を返し、許可するには true または void を返します。

"content:beforeDelete": async (event, ctx) => {
	if (event.collection === "pages" && event.id === "home") {
		ctx.log.warn("Cannot delete home page");
		return false;
	}
	return true;
},

イベント: { id, collection } — 戻り値: boolean | void

`content:afterDelete`

コンテンツが正常に削除された後に実行されます。

"content:afterDelete": async (event, ctx) => {
	await ctx.storage.cache.delete(`${event.collection}:${event.id}`);
},

イベント: { id, collection } — 戻り値: Promise<void>