集合钩子

Collection Hooks（集合钩子）是在特定 Collection 内文档上运行的 Hooks。它们允许你在文档生命周期的特定事件中执行自定义逻辑。

要为集合添加 Hooks，请在 Collection Config 中使用 hooks 属性：

import type { CollectionConfig } from 'payload'

export const CollectionWithHooks: CollectionConfig = {
  // ...
  hooks: {
    // highlight-line
    // ...
  },
}

提示： 你也可以在字段级别设置 hooks，将钩子逻辑隔离到特定字段。更多详情。

配置选项

所有 Collection Hooks 都接受一个同步或异步函数数组。每个 Collection Hook 根据其类型接收特定参数，并能够修改特定输出。

import type { CollectionConfig } from 'payload';

export const CollectionWithHooks: CollectionConfig = {
  // ...
  // highlight-start
  hooks: {
    beforeOperation: [(args) => {...}],
    beforeValidate: [(args) => {...}],
    beforeDelete: [(args) => {...}],
    beforeChange: [(args) => {...}],
    beforeRead: [(args) => {...}],
    afterChange: [(args) => {...}],
    afterRead: [(args) => {...}],
    afterDelete: [(args) => {...}],
    afterOperation: [(args) => {...}],
    afterError: [(args) => {....}],

    // 启用认证的 Hooks
    beforeLogin: [(args) => {...}],
    afterLogin: [(args) => {...}],
    afterLogout: [(args) => {...}],
    afterRefresh: [(args) => {...}],
    afterMe: [(args) => {...}],
    afterForgotPassword: [(args) => {...}],
    refresh: [(args) => {...}],
    me: [(args) => {...}],
  },
  // highlight-end
}

beforeOperation

beforeOperation 钩子可用于修改操作接受的参数，或在操作开始前执行副作用。

可用的 Collection 操作包括 create、read、update、delete、login、refresh 和 forgotPassword。

import type { CollectionBeforeOperationHook } from 'payload'

const beforeOperationHook: CollectionBeforeOperationHook = async ({
  args,
  operation,
  req,
}) => {
  return args // 根据需要返回修改后的操作参数
}

beforeOperation 钩子接收以下参数：

Option	Description
`collection`	当前钩子运行的 Collection 对象。
`context`	在钩子间传递的自定义上下文。详情。
`operation`	当前钩子所在操作的名称。
`req`	Web Request 对象。对于 Local API 操作会被模拟。

beforeValidate

在 create 和 update 操作期间运行。该钩子允许你在传入数据通过服务端验证之前添加或格式化数据。

请注意，这不会在客户端验证之前运行。如果你在前端渲染自定义字段组件并为其提供 validate 函数，验证的执行顺序将是：

validate 在客户端运行
如果成功，beforeValidate 在服务端运行
validate 在服务端运行

import type { CollectionBeforeValidateHook } from 'payload'

const beforeValidateHook: CollectionBeforeValidateHook = async ({ data }) => {
  return data
}

beforeValidate 钩子提供以下参数：

Option	Description
`collection`	该钩子正在运行的 Collection 配置。
`context`	在钩子之间传递的自定义上下文。更多详情。
`data`	传入操作的数据。
`operation`	运行该钩子的操作名称。
`originalDoc`	应用更改前的文档。
`req`	Web Request 对象。对于 Local API 操作会被模拟。

beforeChange

在验证完成后，beforeChange 钩子会在 create 和 update 操作中立即执行。在这个阶段，你可以确信即将保存到文档中的数据已经通过了字段验证。你可以选择性地修改要保存的数据结构。

import type { CollectionBeforeChangeHook } from 'payload'

const beforeChangeHook: CollectionBeforeChangeHook = async ({ data }) => {
  return data
}

beforeChange 钩子接收以下参数：

Option	Description
`collection`	当前钩子运行的 Collection 对象。
`context`	在钩子之间传递的自定义上下文。查看更多详情。
`data`	通过操作传入的数据。
`operation`	当前钩子所在操作的名称。
`originalDoc`	应用更改前的原始文档。
`req`	Web Request 对象。对于 Local API 操作会被模拟。

afterChange

当文档创建或更新后，afterChange 钩子会运行。这个钩子对于重新计算统计数据（如全局范围内的总销售额）、将用户资料变更同步到 CRM 系统等场景非常有用。

import type { CollectionAfterChangeHook } from 'payload'

const afterChangeHook: CollectionAfterChangeHook = async ({ doc }) => {
  return doc
}

afterChange 钩子接收以下参数：

Option	Description
`collection`	当前钩子运行的 Collection 对象。
`context`	在钩子之间传递的自定义上下文。详情。
`doc`	变更应用后的结果文档。
`operation`	运行此钩子的操作名称。
`previousDoc`	变更前的文档。
`req`	Web Request 对象。对于 Local API 操作会被模拟。

beforeRead

在 find 和 findByID 操作被 afterRead 转换输出之前执行。此钩子在隐藏字段被移除之前触发，也在本地化字段被扁平化为请求的语言环境之前触发。使用此钩子将通过 doc 参数提供所有语言环境和所有隐藏字段。

import type { CollectionBeforeReadHook } from 'payload'

const beforeReadHook: CollectionBeforeReadHook = async ({ doc }) => {
  return doc
}

beforeRead 钩子提供以下参数：

Option	Description
`collection`	此钩子运行所针对的 Collection。
`context`	在钩子之间传递的自定义上下文。更多详情。
`doc`	应用更改后的结果文档。
`query`	请求的 Query。
`req`	Web Request 对象。对于 Local API 操作会被模拟。

afterRead

在文档返回前的最后一步执行。该钩子会执行以下操作：扁平化本地化字段、隐藏受保护字段，并移除用户无权访问的字段。

import type { CollectionAfterReadHook } from 'payload'

const afterReadHook: CollectionAfterReadHook = async ({ doc }) => {
  return doc
}

afterRead 钩子接收以下参数：

Option	Description
`collection`	当前钩子运行的 Collection 配置。
`context`	在钩子间传递的自定义上下文。了解更多。
`doc`	应用变更后的最终文档。
`query`	请求的 Query 对象。
`req`	Web Request 对象。对于 Local API 操作，该对象会被模拟。

beforeDelete

在 delete 操作之前执行。返回值会被丢弃。

import type { CollectionBeforeDeleteHook } from 'payload';

const beforeDeleteHook: CollectionBeforeDeleteHook = async ({
  req,
  id,
}) => {...}

beforeDelete 钩子提供以下参数：

Option	Description
`collection`	当前钩子运行的 Collection 对象。
`context`	在钩子之间传递的自定义上下文。详情。
`id`	正在被删除文档的 ID。
`req`	Web Request 对象。对于 Local API 操作会被模拟。

afterDelete

在 delete 操作从数据库中删除记录后立即执行。返回值会被忽略。

import type { CollectionAfterDeleteHook } from 'payload';

const afterDeleteHook: CollectionAfterDeleteHook = async ({
  req,
  id,
  doc,
}) => {...}

afterDelete 钩子接收以下参数：

Option	Description
`collection`	当前钩子运行的 Collection 对象。
`context`	在钩子间传递的自定义上下文。详情。
`doc`	应用更改后的结果文档。
`id`	被删除文档的 ID。
`req`	Web Request 对象。对于 Local API 操作会被模拟。

afterOperation

afterOperation 钩子可用于修改操作结果或在操作完成后执行副作用。

可用的 Collection 操作包括 create、find、findByID、update、updateByID、delete、deleteByID、login、refresh 和 forgotPassword。

import type { CollectionAfterOperationHook } from 'payload'

const afterOperationHook: CollectionAfterOperationHook = async ({ result }) => {
  return result
}

afterOperation 钩子接收以下参数：

Option	Description
`args`	传入操作的参数。
`collection`	当前钩子运行的 Collection 对象。
`req`	Web Request 对象。对于 Local API 操作会被模拟。
`operation`	当前钩子所在操作的名称。
`result`	操作的结果（修改前）。

afterError

afterError Hook 在 Payload 应用发生错误时触发。这个 Hook 可用于将错误记录到第三方服务、向开发团队发送电子邮件、将错误记录到 Sentry 或 DataDog 等场景。其输出可用于转换结果对象/状态码。

import type { CollectionAfterErrorHook } from 'payload';

const afterErrorHook: CollectionAfterErrorHook = async ({
  req,
  id,
  doc,
}) => {...}

afterError Hook 提供以下参数：

Argument	Description
`error`	发生的错误。
`context`	在 Hooks 之间传递的自定义上下文。更多详情。
`graphqlResult`	GraphQL 结果对象，如果 Hook 在 GraphQL 上下文中执行则可用。
`req`	扩展自 Web Request 的 `PayloadRequest` 对象。包含当前认证的 `user` 和 Local API 实例 `payload`。
`collection`	当前 Hook 运行的 Collection。
`result`	格式化的错误结果对象，如果 Hook 从 REST 上下文执行则可用。

beforeLogin

对于启用了身份验证的集合，此钩子会在 login 操作期间运行，当存在提供凭据的用户时，但在生成令牌并将其添加到响应之前触发。你可以选择性地修改返回的用户，或者抛出错误以拒绝登录操作。

import type { CollectionBeforeLoginHook } from 'payload'

const beforeLoginHook: CollectionBeforeLoginHook = async ({ user }) => {
  return user
}

beforeLogin 钩子接收以下参数：

Option	Description
`collection`	当前钩子运行的集合。
`context`	在钩子之间传递的自定义上下文。详情。
`req`	Web请求对象。对于本地API操作会被模拟。
`user`	正在登录的用户。

afterLogin

对于启用了身份验证的 Collections，此钩子会在成功执行 login 操作后运行。你可以选择性地修改返回的用户对象。

import type { CollectionAfterLoginHook } from 'payload';

const afterLoginHook: CollectionAfterLoginHook = async ({
  user,
  token,
}) => {...}

afterLogin 钩子接收以下参数：

Option	Description
`collection`	当前钩子运行的Collection对象。
`context`	在钩子之间传递的自定义上下文。查看更多详情。
`req`	Web Request 对象。对于Local API操作会被模拟。
`token`	为用户生成的令牌。
`user`	正在登录的用户对象。

afterLogout

对于启用了身份验证的集合，此钩子会在 logout 操作后执行。

import type { CollectionAfterLogoutHook } from 'payload';

const afterLogoutHook: CollectionAfterLogoutHook = async ({
  req,
}) => {...}

afterLogout 钩子接收以下参数：

Option	描述
`collection`	当前钩子运行的集合。
`context`	在钩子之间传递的自定义上下文。查看更多详情。
`req`	Web 请求对象。对于本地 API操作，该对象会被模拟。

afterMe

对于启用了身份验证的集合，此钩子在 me 操作之后运行。

import type { CollectionAfterMeHook } from 'payload';

const afterMeHook: CollectionAfterMeHook = async ({
  req,
  response,
}) => {...}

afterMe 钩子接收以下参数：

Option	描述
`collection`	当前钩子运行的集合对象。
`context`	在钩子之间传递的自定义上下文。查看更多详情。
`req`	Web请求对象。对于本地API操作，该对象会被模拟。
`response`	要返回的响应对象。

afterRefresh

对于启用了身份验证的 Collections，此钩子会在 refresh 操作后运行。

import type { CollectionAfterRefreshHook } from 'payload';

const afterRefreshHook: CollectionAfterRefreshHook = async ({
  token,
}) => {...}

afterRefresh 钩子接收以下参数：

Option	Description
`collection`	当前钩子运行的Collection对象。
`context`	在钩子之间传递的自定义上下文。详情。
`exp`	令牌的过期时间。
`req`	Web Request对象。对于Local API操作会被模拟。
`token`	新刷新的用户令牌。

afterForgotPassword

对于启用了身份验证的 Collections，此钩子会在成功的 forgotPassword 操作后运行。返回值将被丢弃。

import type { CollectionAfterForgotPasswordHook } from 'payload'

const afterForgotPasswordHook: CollectionAfterForgotPasswordHook = async ({
  args,
  context,
  collection,
}) => {...}

afterForgotPassword 钩子接收以下参数：

选项	描述
`args`	传入该操作的参数。
`collection`	运行此钩子的Collection。
`context`	在钩子之间传递的自定义上下文。更多详情。

refresh

对于启用了身份验证的 Collections，此钩子允许你选择性地用自定义行为替换默认的 refresh 操作。如果你从钩子中返回一个值，操作将不会执行其默认逻辑并继续执行。

import type { CollectionRefreshHook } from 'payload'

const myRefreshHook: CollectionRefreshHook = async ({
  args,
  user,
}) => {...}

afterRefresh 钩子接收以下参数：

选项	描述
`args`	传入该操作的参数。
`user`	当前登录的用户对象。

me（当前用户）

对于启用了身份验证的 Collections，这个钩子允许你用自定义逻辑替换默认的 me 操作行为。如果你从钩子中返回一个值，操作将不会执行其默认逻辑并继续执行。

import type { CollectionMeHook } from 'payload'

const meHook: CollectionMeHook = async ({
  args,
  user,
}) => {...}

me 钩子接收以下参数：

选项	描述
`args`	传入操作的参数
`user`	当前登录的用户

TypeScript 支持

Payload 为每个 Collection 钩子导出了对应的类型，可以通过以下方式引入：

import type {
  CollectionBeforeOperationHook,
  CollectionBeforeValidateHook,
  CollectionBeforeChangeHook,
  CollectionAfterChangeHook,
  CollectionAfterReadHook,
  CollectionBeforeReadHook,
  CollectionBeforeDeleteHook,
  CollectionAfterDeleteHook,
  CollectionBeforeLoginHook,
  CollectionAfterLoginHook,
  CollectionAfterLogoutHook,
  CollectionAfterRefreshHook,
  CollectionAfterMeHook,
  CollectionAfterForgotPasswordHook,
  CollectionRefreshHook,
  CollectionMeHook,
} from 'payload'

钩子概览

全局钩子

快速开始

配置

数据库

字段

访问控制

钩子

本地 API

REST API

Graphql

查询

管理员

自定义组件

认证

富文本

实时预览

版本

上传

文件夹

电子邮件

作业队列

查询预设

TypeScript

插件

示例

集成

云

生产