Hook 系统

17+ 种 Hook — filter、action 和 render override 类型。优先级排序、Content Type 过滤和派发流程。

Hook 是插件的事件系统。在 manifest 中注册 Hook，在入口文件中实现函数，RaisFast 会在正确的时机调用它。

Hook 类型

类型	行为
Filter	链式转换。接收输入，返回修改后的数据。结果传递给下一个插件。
Action	即发即忘。返回值被忽略。所有插件按顺序执行。
Render Override	先到先得。第一个返回数据的插件胜出，其余插件跳过。

所有 Hook

内容生命周期

Hook	类型	时机
`on-content-creating`	Filter	内容创建前（可修改数据）
`on-content-created`	Action	内容创建后
`on-content-updating`	Filter	内容更新前（可修改数据）
`on-content-updated`	Action	内容更新后
`on-content-deleted`	Action	内容删除后
`on-content-viewed`	Action	单条记录被获取时

文章生命周期

Hook	类型	时机
`on-post-creating`	Filter	文章创建前
`on-post-created`	Action	文章创建后
`on-post-updating`	Filter	文章更新前
`on-post-updated`	Action	文章更新后
`on-post-deleted`	Action	文章删除后

评论生命周期

Hook	类型	时机
`on-comment-creating`	Filter	评论创建前
`on-comment-created`	Action	评论创建后
`on-comment-updated`	Action	评论更新后
`on-comment-deleted`	Action	评论删除后

商品与订单

Hook	类型	时机
`on-product-created`	Action	商品创建后
`on-product-updated`	Action	商品更新后
`on-product-deleted`	Action	商品删除后
`on-order-created`	Action	订单创建后
`on-order-paid`	Action	订单支付后
`on-order-shipped`	Action	订单发货后
`on-order-completed`	Action	订单完成后
`on-order-cancelled`	Action	订单取消后

支付与钱包

Hook	类型	时机
`on-payment-order-created`	Action	支付订单创建后
`on-payment-paid`	Action	支付成功后
`on-payment-refunded`	Action	支付退款后
`on-wallet-credited`	Action	钱包充值后
`on-wallet-debited`	Action	钱包扣款后

标签 / 分类 / 页面 / 媒体

Hook	类型	时机
`on-tag-created`	Action	标签创建后
`on-tag-updated`	Action	标签更新后
`on-tag-deleted`	Action	标签删除后
`on-category-created`	Action	分类创建后
`on-category-updated`	Action	分类更新后
`on-category-deleted`	Action	分类删除后
`on-page-created`	Action	页面创建后
`on-page-updated`	Action	页面更新后
`on-page-deleted`	Action	页面删除后
`on-media-uploaded`	Action	文件上传后
`on-media-deleted`	Action	文件删除后

用户与认证

Hook	类型	时机
`on-user-registered`	Action	用户注册后
`on-login`	Action	用户登录后
`on-password-reset-requested`	Action	请求密码重置时
`on-email-verification-requested`	Action	请求邮箱验证时

工具类

Hook	类型	时机
`render-markdown`	Render Override	覆盖 Markdown 渲染
`filter-html`	Render Override	过滤 HTML 输出
`on-cron-tick`	Action	定时任务触发

自定义事件

插件可通过 emitEvent() 发射自定义事件。其他插件通过注册同名 Hook 监听：

[hooks.order-created]
priority = 10

export function order_created(input) {
  const data = JSON.parse(input);
  logInfo("order created: " + data.id);
}

优先级排序

Hook 按优先级升序执行（数字越小越先执行）：

[hooks.on-content-creating]
priority = 10   # 最先执行

[hooks.on-content-creating]
priority = 50   # 第二个执行

[hooks.on-content-creating]
priority = 100  # 最后执行（默认）

未指定时默认优先级为 100。

Filter Hook 中，每个插件接收上一个插件的输出。Action Hook 中，所有插件独立执行。

Content Type 过滤

限制 Hook 仅对特定 Content Type 触发：

[hooks.on-content-creating]
priority = 10
content_types = ["product", "course"]

或使用简写 match：

[hooks.on-content-creating]
priority = 10
match = "product"

content_types 为空（默认）时，Hook 对所有 Content Type 触发。

Filter Hook

Filter Hook 可以在数据保存前修改数据。返回修改后的数据：

export function on_content_creating(input) {
  const data = JSON.parse(input);
  if (!data.slug) {
    data.slug = data.title.toLowerCase().replace(/ /g, '-');
  }
  return JSON.stringify(data);
}

Plugin.on_content_creating = function(input)
  local data = sdk.extractJson(input, "body")
  if not data.slug then
    data.slug = string.lower(data.title):gsub(" ", "-")
  end
  return sdk.ok(data)
end

fn on_content_creating(input) {
  if input.slug == "" {
    input.slug = to_lower(input.title);
    input.slug = replace(input.slug, " ", "-");
  }
  input
}

Action Hook

Action Hook 用于副作用 — 日志、通知、缓存清除。返回值被忽略：

export function on_content_created(input) {
  const data = JSON.parse(input);
  logInfo("created: " + data.id);
  eventEmit("content.created", JSON.stringify({ id: data.id }));
}

Plugin.on_content_created = function(input)
  local data = sdk.extractJson(input, "body")
  sdk.logInfo("created: " .. tostring(data.id))
  sdk.eventEmit("content.created", sdk.jsonEncode({ id = data.id }))
end

fn on_content_created(input) {
  log("info", "created: " + input.id);
  emit_event("content.created", to_json(input));
}

Render Override Hook

Render Override 使用先到先得策略。第一个返回非空值的插件胜出，其余插件跳过：

[hooks.render-markdown]
priority = 10

export function render_markdown(input) {
  const data = JSON.parse(input);
  return customMarkdownRenderer(data.content);
}

错误恢复

连续 5 次 错误后，插件自动禁用
成功执行时错误计数重置为 0
可通过 Admin API 重新启用：POST /api/v1/admin/plugins/{id}/enable
超时或崩溃时，未提交的事务自动回滚

Hook 系统

On this page