CodeSnippet

Appearance

钩子概述 ​

钩子允许您在文档生命周期的特定事件中执行自己的副作用。它们使您能够在应用程序中的精确时刻做各种事情，比如变更数据、执行业务逻辑、与第三方集成或其他任何操作。

通过钩子，您可以将 Payload 从传统的内容管理系统（CMS）转变为一个功能完整的应用程序框架。钩子的应用场景非常广泛，包括但不限于：

  • 在数据被读取或更新之前修改数据
  • 对敏感数据进行加密和解密
  • 与第三方 CRM 系统（如 HubSpot 或 Salesforce）集成
  • 将上传的文件复制到 Amazon S3 或类似存储
  • 通过像 Stripe 这样的支付提供商处理订单
  • 在提交联系表单时发送电子邮件
  • 跟踪数据的所有权或随时间变化

在 Payload 中，钩子有四种主要类型：

  • 根钩子（Root Hooks）
  • 集合钩子（Collection Hooks）
  • 全局钩子（Global Hooks）
  • 字段钩子（Field Hooks）

NOTE

Payload 还提供了一组 React 钩子，您可以在前端应用程序中使用。尽管它们有相同的名称，但这些钩子与文档生命周期中的钩子是非常不同的，不能混淆使用。更多详情请参阅相关文档。

根钩子 ​

根钩子与任何特定的集合、全局或字段无关。它们用于处理全局性副作用，例如当发生应用级别的错误时。

要添加根钩子，请在您的 Payload 配置中使用 hooks 属性：

javascript
import { buildConfig } from 'payload'

export default buildConfig({
  // ...
  hooks: {
    afterError:[() => {...}]
  },
})

以下是可用的选项：

选项描述
afterError在 Payload 应用程序发生错误后执行。

afterError ​

afterError 钩子在 Payload 应用程序发生错误时触发。它可以用于将错误记录到第三方服务、向开发团队发送电子邮件、将错误日志发送到 Sentry 或 DataDog 等。输出可以用来转换结果对象或状态码。

javascript
import { buildConfig } from 'payload'

export default buildConfig({
  // ...
  hooks: {
    afterError: [
      async ({ error }) => {
        // Do something
      },
    ],
  },
})

以下是传递给 afterError 钩子的参数：

参数描述
error发生的错误。
context在钩子之间传递的自定义上下文。更多详情
graphqlResultGraphQL 结果对象，如果钩子在 GraphQL 上下文中执行，则可用。
req扩展自 Web 请求的 PayloadRequest 对象。包含当前认证的用户和本地 API 实例的 payload。
collection当前钩子正在操作的集合。如果钩子在非集合端点或 GraphQL 中执行，则为 undefined。
result格式化的错误结果对象，如果钩子在 REST 上下文中执行，则可用。

异步 vs 同步 ​

所有钩子都可以写成同步或异步函数。选择合适的类型取决于您的使用场景，但在两者之间切换只需添加或删除 async 关键字。

异步 ​

如果钩子需要在文档更新或创建之前修改数据，并且依赖于异步操作（例如从第三方获取数据），那么将钩子定义为异步函数是合理的。这样，您可以确保钩子在操作生命周期继续之前完成。异步钩子是按顺序执行的——如果定义了两个异步钩子，第二个钩子将在第一个钩子完成后才开始执行。

同步 ​

如果钩子只是执行一个副作用，例如更新 CRM，那么将其定义为同步钩子可能是合适的，这样 Payload 操作就不必等待钩子完成。

仅服务器执行 ​

钩子仅在服务器上触发，并会自动从客户端包中排除。这意味着您可以放心地在钩子中使用敏感的业务逻辑，而无需担心将其暴露给客户端。