钩子 | 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>