E EmDash CMS Everything Guides, use cases, plugins, templates
繁體中文

Hook 參考

本頁內容

Hooks 讓外掛能在內容、媒體、電子郵件、留言與頁面生命週期的特定時間點攔截並修改 EmDash 行為。

Hook 總覽

Hook觸發時機可修改獨占
content:beforeSave儲存內容前內容資料否
content:afterSave儲存內容後無否
content:beforeDelete刪除內容前可取消否
content:afterDelete刪除內容後無否
media:beforeUpload上傳檔案前檔案中繼資料否
media:afterUpload上傳檔案後無否
cron排程工作觸發無否
email:beforeSend寄送電子郵件前訊息，可取消否
email:deliver透過 transport 遞送電子郵件無是
email:afterSend電子郵件成功遞送後無否
comment:beforeCreate儲存留言前留言，可取消否
comment:moderate決定留言核准狀態狀態是
comment:afterCreate儲存留言後無否
comment:afterModerate管理員變更留言狀態後無否
page:metadata渲染公開頁面 head貢獻標籤否
page:fragments渲染公開頁面 body注入指令碼否
plugin:install外掛首次安裝時無否
plugin:activate外掛啟用時無否
plugin:deactivate外掛停用時無否
plugin:uninstall外掛移除時無否

內容 Hooks

content:beforeSave

在內容儲存到資料庫前執行。用於驗證、轉換或擴充內容。

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
}

回傳值

  • 回傳修改後的內容物件以套用變更
  • 回傳 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}`);
  },
}

媒體 Hooks

media:beforeUpload

在檔案上傳前執行。用於驗證、重新命名或拒絕檔案。

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

    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;
	};
}

生命週期 Hooks

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 Hook

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;
}

電子郵件 Hooks

電子郵件 hooks 形成管線：email:beforeSend → email:deliver → email:afterSend。

email:beforeSend

Capability： email:intercept

在遞送前執行的中介 hook。轉換訊息或取消遞送。

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

Capability： email:provide | 獨占： 是

傳輸提供者。只有一個外掛可以遞送電子郵件。負責透過電子郵件服務實際傳送訊息。

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

email:afterSend

Capability： email:intercept

成功遞送後的發即忘 hook。錯誤會被記錄但不會傳播。

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

留言 Hooks

留言 hooks 形成管線：comment:beforeCreate → comment:moderate → comment:afterCreate。comment:afterModerate hook 在管理員手動變更留言狀態時獨立觸發。

comment:beforeCreate

Capability： read:users

留言儲存前的中介 hook。擴充、驗證或拒絕留言。

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

Capability： read:users | 獨占： 是

決定留言是核准、待審或垃圾。只有一個審核提供者會啟用。

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

Capability： read:users

留言儲存後的發即忘 hook。用於通知。

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

Capability： read:users

管理員手動變更留言狀態時的發即忘 hook。

事件

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

頁面 Hooks

頁面 hooks 在渲染公開頁面時執行。它們讓外掛注入中繼資料和指令碼。

page:metadata

Capability： page:inject

向頁面 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: string; href: string; hreflang?: string; key?: string }
	| { kind: "jsonld"; id?: string; graph: Record<string, unknown> };

key 欄位用於去重貢獻——同一 key 只使用最後一個貢獻。

page:fragments

Capability： page:inject

向頁面注入指令碼或 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;
		};

Hook 設定

Hooks 接受處理函式或設定物件：

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 等 provider 模式 hooks）

外掛脈絡

所有 hooks 接收一個可存取外掛 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;
}

Capability 需求與方法詳情見外掛系統概覽 — 外掛脈絡。

錯誤處理

hooks 中的錯誤會被記錄，並根據 errorPolicy 處理：

  • "abort"（預設）— 停止執行，如適用則回滾交易
  • "continue" — 記錄錯誤並繼續下一個 hook
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);
      }
    },
  },
}

執行順序

Hooks 依下列順序執行：

  1. 依 priority 升序排列
  2. 具有 dependencies 的外掛在其相依項之後執行
  3. 相同優先順序內，順序是確定的但未指定
// 最先執行（priority 10）
{ priority: 10, handler: ... }

// 其次執行（priority 50）
{ priority: 50, handler: ... }

// 最後執行（預設 priority 100）
{ handler: ... }