插件 Hook 清单

当前宿主把扩展点分成 5 类：

• slot：插入 UI 块
• surface：覆盖宿主默认 UI 区块
• action hook：在生命周期点执行副作用逻辑
• waterfall：同步串行改写数据
• asyncWaterfall：异步串行改写数据

通用规则

• 所有扩展点都按 order 升序执行
• 同 order 下按 addonId:key 稳定排序
• slot 返回 AddonRenderResult | null
• surface 返回 AddonRenderResult | null
• action hook 返回 void
• waterfall / asyncWaterfall 返回下一个值；返回 undefined 时保留上一个值
• hook 执行失败时，宿主默认记录 lifecycle log 并继续后续插件
• before action hook 在宿主显式传入 throwOnError: true 时可中断主流程
• surface 只会选择一个插件生效；命中失败时自动回退宿主默认 UI
• 宿主通过 <AddonSlotRenderer slot="..." props={{ ... }} /> 或 <AddonSurfaceRenderer surface="..." props={{ ... }} /> 调用时，当前点位上下文会进入 context.props

Action Hook

Waterfall

AsyncWaterfall

Surface

命名规则：

• 如果宿主同时开放了 xxx.before 和 xxx.after 两个 slot，中间那块默认 UI 通常会同步开放一个 xxx surface
• 例如 search.hero.before / search.hero.after 对应 search.hero
• 例如 topup.payment.before / topup.payment.after 对应 topup.payment
• 例如 messages.thread.before / messages.thread.after 对应 messages.thread
• 例如 post.create.tools.before / post.create.tools.after 对应 post.create.tools
• 例如 post.author.name.before / post.author.name.after 对应 post.author.name
• 例如 post.author.badges.before / post.author.badges.after 对应 post.author.badges

当前已接入的一批常用 surface 包括：

• 页面主体类：about.page、announcements.page、auth.complete.page、auth.forgot-password.page、auth.passkey.page、badge.page、board.page、collections.page、funs.page、help.page、history.page、notifications.page、prison.page、search.page、settings.page、tag.page、tags.page、terms.page、topup.page、topup.result.page、vip.page、write.page
• 头部 / Hero 类：about.hero、announcement.hero、announcements.hero、auth.complete.panel、auth.forgot-password.panel、auth.passkey.panel、badge.hero、board.hero、collections.hero、friend-links.hero、search.hero、terms.hero、vip.hero、write.header
• 帖子作者类：post.header、post.author.row、post.author.meta、post.author.verification、post.author.name、post.author.badges
• 评论作者类：comment.author.row、comment.author.meta、comment.author.verification、comment.author.name、comment.author.badges
• 内容 / 列表类：about.highlights、about.principles、announcement.content、announcements.content、board.content、faq.content、friend-links.content、notifications.list、post.create.form、post.create.tools、post.create.editor、post.create.enhancements、post.create.submit、prison.content、search.results、settings.content、settings.profile、settings.invite、settings.post-management、settings.board-applications、settings.level、settings.badges、settings.verifications、settings.points、settings.follows、tag.content、terms.content、topup.payment、topup.redeem、topup.result.panel、vip.actions、vip.levels
• 侧栏 / 辅助区块类：about.sidebar、badge.sidebar、board.sidebar、collections.sidebar、funs.sidebar、help.sidebar、prison.sidebar、tag.sidebar、tags.sidebar、terms.sidebar
• 交互区块类：layout.footer、messages.page、messages.header、messages.sidebar、messages.thread、collection.hero、collection.pending、collection.content、history.panel

说明：

• 服务端静态区块一般通过 render(context) 接管
• messages.page、settings.page 属于 hybrid surface：先尝试服务端 render(context)，未命中再回退到 clientModule
• messages.header、messages.sidebar、messages.thread、collection.hero、collection.pending、collection.content、history.panel、settings.content、post.create.form、post.create.tools、post.create.editor、post.create.enhancements、post.create.submit、comment.author.row、comment.author.meta、comment.author.verification、comment.author.name、comment.author.badges 属于 client-only surface：只支持 clientModule
• 如果某个只有单边 slot、纯插入位、或宿主没有默认内容的点位，通常不会对应 surface

Slot

认证

全局布局

首页 / 节点 / 帖子

用户设置

积分 / VIP

帮助 / 关于

发帖页 / 功能区

FAQ / 通知 / 私信 / 搜索

标签 / 用户主页

内容流 / 节点 / 合集

公告 / 足迹 / 友情链接 / 节点目录 / 勋章详情

协议 / 小黑屋 / 认证流程 / 充值结果

js
api.registerActionHook({
  key: "after-login-sync",
  hook: "auth.login.after",
  async handle(context) {
    // ...
  },
})

示例

js
api.registerWaterfallHook({
  key: "slug-prefix",
  hook: "post.slug.value",
  transform(context) {
    return `topic-${context.value}`
  },
})

api.registerAsyncWaterfallHook({
  key: "prepend-navigation",
  hook: "navigation.primary.items",
  async transform(context) {
    return [
      { label: "活动", href: "/events", activePrefix: "/events" },
      ...context.value,
    ]
  },
})