全局钩子

全局钩子（Global Hooks）是作用于全局文档的钩子。它们允许你在文档生命周期的特定事件中执行自定义逻辑。

要为全局添加钩子，请在全局配置中使用 hooks 属性：

import type { GlobalConfig } from 'payload'

export const GlobalWithHooks: GlobalConfig = {
  // ...
  hooks: {
    // highlight-line
    // ...
  },
}

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

配置选项

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

import type { GlobalConfig } from 'payload';

const GlobalWithHooks: GlobalConfig = {
  // ...
  // highlight-start
  hooks: {
    beforeValidate: [(args) => {...}],
    beforeChange: [(args) => {...}],
    beforeRead: [(args) => {...}],
    afterChange: [(args) => {...}],
    afterRead: [(args) => {...}],
  }
  // highlight-end
}

beforeValidate

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

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

  1. validate 在客户端运行
  2. 如果成功，beforeValidate 在服务器端运行
  3. validate 在服务器端运行
import type { GlobalBeforeValidateHook } from 'payload'

const beforeValidateHook: GlobalBeforeValidateHook = async ({
  data,
  req,
  originalDoc,
}) => {
  return data
}

beforeValidate 钩子提供以下参数：

OptionDescription
global当前钩子运行的 Global 配置。
context在钩子之间传递的自定义上下文。更多详情。
data传入的操作数据。
originalDoc应用更改前的文档。
reqWeb Request 对象。对于 Local API 操作会被模拟。

beforeChange

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

import type { GlobalBeforeChangeHook } from 'payload'

const beforeChangeHook: GlobalBeforeChangeHook = async ({
  data,
  req,
  originalDoc,
}) => {
  return data
}

beforeChange 钩子接收以下参数：

OptionDescription
global当前钩子运行的 Global 对象。
context在钩子之间传递的自定义上下文。详情。
data操作中传入的数据。
originalDoc应用更改前的文档。
reqWeb Request 对象。对于 Local API 操作会被模拟。

afterChange

当一个 global 更新后，afterChange 钩子会执行。你可以使用这个钩子来清除应用缓存、将站点数据同步到 CRM 系统等。

import type { GlobalAfterChangeHook } from 'payload'

const afterChangeHook: GlobalAfterChangeHook = async ({
  doc,
  previousDoc,
  req,
}) => {
  return data
}

afterChange 钩子接收以下参数：

OptionDescription
global当前钩子运行的 Global 对象。
context在钩子间传递的自定义上下文。详情。
doc应用更改后的最终文档。
previousDoc应用更改前的原始文档。
reqWeb Request 对象。对于 Local API 操作会被模拟。

beforeRead

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

import type { GlobalBeforeReadHook } from 'payload'

const beforeReadHook: GlobalBeforeReadHook = async ({
  doc,
  req,
}) => {...}

beforeRead 钩子提供以下参数：

OptionDescription
global此钩子运行所针对的Global配置。
context在钩子之间传递的自定义上下文。更多详情。
doc应用更改后生成的文档。
reqWeb Request对象。对于Local API操作会被模拟。

afterRead

在全局配置返回前作为最后一步执行。它会扁平化多语言字段、隐藏受保护字段，并移除用户无权访问的字段。

import type { GlobalAfterReadHook } from 'payload'

const afterReadHook: GlobalAfterReadHook = async ({
  doc,
  req,
  findMany,
}) => {...}

beforeRead 钩子接收以下参数：

Option描述
global当前钩子运行的全局配置对象。
context在钩子间传递的自定义上下文。详情。
findMany布尔值，表示该钩子是针对单条查询还是批量查询（在版本控制中特别有用）。
doc应用变更后的结果文档。
query请求的查询条件。
reqWeb 请求对象。对于本地 API操作会被模拟。

TypeScript

Payload 为每个 Global hook 导出了对应的类型，可以通过以下方式访问：

import type {
  GlobalBeforeValidateHook,
  GlobalBeforeChangeHook,
  GlobalAfterChangeHook,
  GlobalBeforeReadHook,
  GlobalAfterReadHook,
} from 'payload'