E EmDash CMS Everything Guides, use cases, plugins, templates
简体中文

钩子参考

本页内容

钩子允许插件在内容、媒体、邮件、评论和页面生命周期的特定时间点拦截和修改 EmDash 的行为。

钩子概览

下表列出了每个钩子、触发它的条件、它可以修改什么，以及它是否是独占的：

钩子触发条件可修改内容独占
content:beforeSave内容保存之前内容数据否
content:afterSave内容保存之后无否
content:beforeDelete内容删除之前可取消否
content:afterDelete内容删除之后无否
content:afterPublish内容发布之后无否
content:afterUnpublish内容取消发布之后无否
content:afterRestore内容恢复之后无否
content:afterSchedule内容安排发布之后无否
content:afterUnschedule内容取消安排之后无否
media:beforeUpload文件上传之前文件元数据否
media:afterUpload文件上传之后无否
cron定时任务触发无否
email:beforeSend邮件发送之前消息，可取消否
email:deliver通过传输层发送邮件无是
email:afterSend邮件成功发送之后无否
comment:beforeCreate评论存储之前评论，可取消否
comment:moderate决定评论审核状态状态是
comment:afterCreate评论存储之后无否
comment:afterModerate管理员更改评论状态之后无否
page:metadata渲染公共页面 head贡献标签否
page:fragments渲染公共页面 body注入脚本否
plugin:install插件首次安装时无否
plugin:activate插件启用时无否
plugin:deactivate插件禁用时无否
plugin:uninstall插件移除时无否

内容钩子

content:beforeSave

在内容保存到数据库之前运行。用于验证、转换或丰富内容。沙盒钩子通过返回包含 SAVE_REJECTED 错误和 1–500 字符纯文本 reason 的版本 1 钩子结果来拒绝保存。API 以 SAVE_REJECTED 响应，管理面板会标识插件并以文本形式显示原因。空的、过长的、格式错误的和未知的错误结果会使保存因通用的 CONTENT_HOOK_ERROR 响应而失败。

从宿主进程中，抛出 ContentSaveRejectedError（从 emdash 导出）来拒绝保存。来自任一执行模式的任何其他异常都会使保存因不暴露异常消息的通用响应而失败。

import { definePlugin } from "emdash";

export default definePlugin({
	id: "my-plugin",
	version: "1.0.0",
	hooks: {
		"content:beforeSave": async (event, ctx) => {
			const { content, collection, isNew } = event;

			// 添加时间戳
			if (isNew) {
				content.createdBy = "system";
			}
			content.modifiedAt = new Date().toISOString();

			// 返回修改后的内容
			return content;
		},
	},
});

事件

interface ContentHookEvent {
	content: Record<string, unknown>; // 内容数据
	collection: string; // 集合 slug
	isNew: boolean; // 创建时为 true，更新时为 false
	id?: string; // 更新时现有项目的 ID；创建时不存在
}

在更新时，content 仅包含提交的字段值。当钩子需要与之比较时，使用 ctx.content.get(event.collection, event.id) 加载存储的项目。

返回值

  • 返回修改后的内容对象以应用更改
  • 返回沙盒钩子错误信封以带有限长纯文本原因拒绝保存
  • 返回 void 以不做更改通过

content:afterSave

在内容保存之后运行。用于通知、缓存失效或外部同步等副作用。

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

    if (collection === "posts" && content.status === "published") {
      // 通知外部服务
      await ctx.http?.fetch("https://api.example.com/notify", {
        method: "POST",
        body: JSON.stringify({ postId: content.id }),
      });
    }
  },
}

返回值

不期望返回值。

content:beforeDelete

在内容删除之前运行。用于验证删除或阻止删除。

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

    // 阻止删除受保护的内容
    const item = await ctx.content?.get(collection, id);
    if (item?.data.protected) {
      return false; // 取消删除
    }

    // 允许删除
    return true;
  },
}

事件

interface ContentDeleteEvent {
	id: string; // 条目 ID
	collection: string; // 集合 slug
}

返回值

  • 返回 false 取消删除
  • 返回 true 或 void 允许删除

content:afterDelete

在内容删除之后运行。用于清理任务。

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

    // 清理相关数据
    await ctx.storage.relatedItems.delete(`${collection}:${id}`);
  },
}

content:afterRestore

在回收站内容恢复之后运行。需要 content:read 能力。

hooks: {
  "content:afterRestore": async (event, ctx) => {
    ctx.log.info(`Restored ${event.collection}/${event.content.id}`);
  },
}

content:afterSchedule

在内容安排未来发布之后运行。需要 content:read 能力。

hooks: {
  "content:afterSchedule": async (event, ctx) => {
    ctx.log.info(`Scheduled ${event.collection}/${event.content.id}`);
  },
}

content:afterUnschedule

在已安排的内容取消安排之后运行。需要 content:read 能力。

hooks: {
  "content:afterUnschedule": async (event, ctx) => {
    ctx.log.info(`Unscheduled ${event.collection}/${event.content.id}`);
  },
}

事件

interface ContentStateChangeEvent {
	content: Record<string, unknown>;
	collection: string;
}

返回值

不期望返回值。

媒体钩子

media:beforeUpload

在文件上传之前运行。用于验证、重命名或拒绝文件。

hooks: {
  "media:beforeUpload": async (event, ctx) => {
    const { file } = event;

    // 拒绝超过 10MB 的文件
    if (file.size > 10 * 1024 * 1024) {
      throw new Error("File too large");
    }

    // 重命名文件
    return {
      name: `${Date.now()}-${file.name}`,
      type: file.type,
      size: file.size,
    };
  },
}

事件

interface MediaUploadEvent {
	file: {
		name: string; // 原始文件名
		type: string; // MIME 类型
		size: number; // 字节大小
	};
}

返回值

  • 返回修改后的文件元数据以应用更改
  • 返回 void 以不做更改通过
  • 抛出异常以拒绝上传

media:afterUpload

在文件上传之后运行。用于处理、缩略图或元数据提取。

hooks: {
  "media:afterUpload": async (event, ctx) => {
    const { media } = event;

    if (media.mimeType.startsWith("image/")) {
      // 存储图片元数据
      await ctx.kv.set(`media:${media.id}:analyzed`, {
        processedAt: new Date().toISOString(),
      });
    }
  },
}

事件

interface MediaAfterUploadEvent {
	media: {
		id: string;
		filename: string;
		mimeType: string;
		size: number | null;
		url: string;
		createdAt: string;
	};
}

生命周期钩子

plugin:install

在插件首次安装时运行。用于初始设置、创建存储集合或填充数据。

hooks: {
  "plugin:install": async (event, ctx) => {
    // 初始化默认设置
    await ctx.kv.set("settings:enabled", true);
    await ctx.kv.set("settings:threshold", 100);

    ctx.log.info("Plugin installed successfully");
  },
}

plugin:activate

在插件启用时运行（安装后或重新启用后）。

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

plugin:deactivate

在插件禁用时运行。

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

plugin:uninstall

在插件移除时运行。用于清理。

hooks: {
  "plugin:uninstall": async (event, ctx) => {
    const { deleteData } = event;

    if (deleteData) {
      // 清理所有插件数据
      const items = await ctx.kv.list("settings:");
      for (const { key } of items) {
        await ctx.kv.delete(key);
      }
    }

    ctx.log.info("Plugin uninstalled");
  },
}

事件

interface UninstallEvent {
	deleteData: boolean; // 用户选择删除数据
}

定时钩子

cron

在定时任务执行时触发。使用 ctx.cron.schedule() 安排任务。

hooks: {
  "cron": async (event, ctx) => {
    if (event.name === "daily-sync") {
      const data = await ctx.http?.fetch("https://api.example.com/data");
      ctx.log.info("Sync complete");
    }
  },
}

事件

interface CronEvent {
	name: string;
	data?: Record<string, unknown>;
	scheduledAt: string;
}

邮件钩子

邮件钩子按顺序运行：email:beforeSend，然后 email:deliver，然后 email:afterSend。

email:beforeSend

能力： hooks.email-events:register

在发送之前运行的中间件钩子。转换消息或取消发送。

hooks: {
  "email:beforeSend": async (event, ctx) => {
    // 为所有邮件添加页脚
    return {
      ...event.message,
      text: event.message.text + "\n\n—Sent from My Site",
    };

    // 或返回 false 取消发送
  },
}

事件

interface EmailBeforeSendEvent {
	message: { to: string; subject: string; text: string; html?: string };
	source: string;
}

返回值

  • 返回修改后的消息以进行转换
  • 返回 false 取消发送
  • 返回 void 以不做更改通过

email:deliver

能力： hooks.email-transport:register | 独占： 是

传输提供者。只有一个插件可以发送邮件。负责通过邮件服务实际发送消息。

hooks: {
  "email:deliver": {
    exclusive: true,
    handler: async (event, ctx) => {
      await sendViaSES(event.message);
    },
  },
}

email:afterSend

能力： hooks.email-events:register

成功发送后的即发即忘钩子。错误被记录但不会传播。

hooks: {
  "email:afterSend": async (event, ctx) => {
    await ctx.kv.set(`email:log:${Date.now()}`, {
      to: event.message.to,
      subject: event.message.subject,
    });
  },
}

评论钩子

评论钩子按顺序运行：comment:beforeCreate，然后 comment:moderate，然后 comment:afterCreate。comment:afterModerate 钩子在管理员更改评论状态时单独触发。

comment:beforeCreate

能力： users:read

评论存储之前的中间件钩子。丰富、验证或拒绝评论。

hooks: {
  "comment:beforeCreate": async (event, ctx) => {
    // 拒绝包含链接的评论
    if (event.comment.body.includes("http")) {
      return false;
    }
  },
}

事件

interface CommentBeforeCreateEvent {
	comment: {
		collection: string;
		contentId: string;
		parentId: string | null;
		authorName: string;
		authorEmail: string;
		authorUserId: string | null;
		body: string;
		ipHash: string | null;
		userAgent: string | null;
	};
	metadata: Record<string, unknown>;
}

返回值

  • 返回修改后的事件以进行转换
  • 返回 false 拒绝
  • 返回 void 以不做更改通过

comment:moderate

能力： users:read | 独占： 是

决定评论是批准、待审核还是垃圾评论。只有一个审核提供者处于活动状态。

hooks: {
  "comment:moderate": {
    exclusive: true,
    handler: async (event, ctx) => {
      const score = await checkSpam(event.comment);
      return {
        status: score > 0.8 ? "spam" : score > 0.5 ? "pending" : "approved",
        reason: `Spam score: ${score}`,
      };
    },
  },
}

事件

interface CommentModerateEvent {
	comment: { /* 与 beforeCreate 相同 */ };
	metadata: Record<string, unknown>;
	collectionSettings: {
		commentsEnabled: boolean;
		commentsModeration: "all" | "first_time" | "none";
		commentsClosedAfterDays: number;
		commentsAutoApproveUsers: boolean;
	};
	priorApprovedCount: number;
}

返回值

{ status: "approved" | "pending" | "spam"; reason?: string }

comment:afterCreate

能力： users:read

评论存储后的即发即忘钩子。用于通知。

hooks: {
  "comment:afterCreate": async (event, ctx) => {
    if (event.comment.status === "approved") {
      await ctx.email?.send({
        to: event.contentAuthor?.email,
        subject: `New comment on "${event.content.title}"`,
        text: `${event.comment.authorName} commented: ${event.comment.body}`,
      });
    }
  },
}

comment:afterModerate

能力： users:read

管理员手动更改评论状态时的即发即忘钩子。

事件

interface CommentAfterModerateEvent {
	comment: { id: string; /* ... */ };
	previousStatus: string;
	newStatus: string;
	moderator: { id: string; name: string | null };
}

页面钩子

页面钩子在渲染公共页面时运行。它们允许插件注入元数据和脚本。

page:metadata

能力： 无需要求

向页面 head 贡献 meta 标签、Open Graph 属性、JSON-LD 结构化数据或 link 标签。

hooks: {
  "page:metadata": async (event, ctx) => {
    return [
      { kind: "meta", name: "generator", content: "EmDash" },
      { kind: "property", property: "og:site_name", content: event.page.siteName },
      { kind: "jsonld", graph: { "@type": "WebSite", name: event.page.siteName } },
    ];
  },
}

贡献类型

type PageMetadataContribution =
	| { kind: "meta"; name: string; content: string; key?: string }
	| { kind: "property"; property: string; content: string; key?: string }
	| {
			kind: "link";
			rel: "canonical" | "alternate" | "author" | "license" | "nlweb" | "site.standard.document";
			href: string;
			hreflang?: string;
			key?: string;
	  }
	| {
			kind: "jsonld";
			id?: string;
			graph: Record<string, unknown> | Array<Record<string, unknown>>;
	  };

key 字段用于去重贡献——只使用具有给定 key 的最后一个贡献。

page:fragments

能力： hooks.page-fragments:register

向页面注入脚本或 HTML。仅对原生插件可用。

hooks: {
  "page:fragments": async (event, ctx) => {
    return [
      {
        kind: "external-script",
        placement: "body:end",
        src: "https://analytics.example.com/script.js",
        async: true,
      },
      {
        kind: "inline-script",
        placement: "head",
        code: `window.siteId = "abc123";`,
      },
    ];
  },
}

贡献类型

type PageFragmentContribution =
	| {
			kind: "external-script";
			placement: "head" | "body:start" | "body:end";
			src: string;
			async?: boolean;
			defer?: boolean;
			attributes?: Record<string, string>;
			key?: string;
		}
	| {
			kind: "inline-script";
			placement: "head" | "body:start" | "body:end";
			code: string;
			attributes?: Record<string, string>;
			key?: string;
		}
	| {
			kind: "html";
			placement: "head" | "body:start" | "body:end";
			html: string;
			key?: string;
		};

钩子配置

钩子接受处理函数或配置对象：

hooks: {
  // 简单处理函数
  "content:afterSave": async (event, ctx) => { ... },

  // 带配置
  "content:beforeSave": {
    priority: 50,        // 数值越低越先执行（默认：100）
    timeout: 10000,      // 最大执行时间（毫秒，默认：5000）
    dependencies: [],    // 在这些插件之后运行
    errorPolicy: "abort", // "continue" 或 "abort"（默认）
    handler: async (event, ctx) => { ... },
  },
}

配置选项

选项类型默认值描述
prioritynumber100执行顺序（越低越早）
timeoutnumber5000最大执行时间（毫秒）
dependenciesstring[][]必须先运行的插件 ID
errorPolicystring"abort""continue" 忽略错误
exclusivebooleanfalse只有一个插件可以是活动提供者（用于 email:deliver、comment:moderate 等提供者模式钩子）

插件上下文

所有钩子接收一个具有插件 API 访问权限的上下文对象：

interface PluginContext {
	plugin: { id: string; version: string };
	storage: PluginStorage;
	kv: KVAccess;
	content?: ContentAccess;
	media?: MediaAccess;
	http?: HttpAccess;
	log: LogAccess;
	site: { name: string; url: string; locale: string };
	url(path: string): string;
	users?: UserAccess;
	cron?: CronAccess;
	email?: EmailAccess;
}

参见插件概述 — 插件上下文了解能力要求和方法详情。

错误处理

钩子中的错误被记录并根据 errorPolicy 处理：

  • "abort"（默认）— 停止执行，如果适用则回滚事务
  • "continue" — 记录错误并继续执行下一个钩子
hooks: {
  "content:beforeSave": {
    errorPolicy: "continue", // 如果失败不阻止保存
    handler: async (event, ctx) => {
      try {
        await ctx.http?.fetch("https://api.example.com/validate");
      } catch (error) {
        ctx.log.warn("Validation service unavailable", error);
      }
    },
  },
}

执行顺序

钩子按以下顺序运行：

  1. 按 priority 排序（升序）
  2. 带有 dependencies 的插件在其依赖之后运行
  3. 在相同优先级内，顺序是确定性的但未指定
// 这个先执行（优先级 10）
{ priority: 10, handler: ... }

// 这个第二执行（优先级 50）
{ priority: 50, handler: ... }

// 这个最后执行（默认优先级 100）
{ handler: ... }