鉤子 | EmDash CMS Everything

鉤子讓外掛能夠回應事件來執行程式碼。所有鉤子接收一個事件物件和外掛上下文，並在外掛定義時宣告——執行階段沒有動態註冊。

本頁涵蓋沙箱外掛。鉤子在原生外掛中的運作方式相同；原生外掛還可以註冊 page:fragments。

鉤子簽名

每個鉤子處理器接受兩個參數：

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`	只能有一個外掛作為活動提供者。用於 `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>