全局配置

Globals（全局数据）在很多方面与 Collections 类似，但区别在于它们只对应单个文档。你可以根据应用需求定义任意数量的 Globals。每个 Global 文档会根据你定义的 Fields 存储在 Database 中，并自动生成用于管理文档的 Local API、REST API 和 GraphQL API。

Globals 是 Payload 中构建单例结构的主要方式，例如页头导航、全站横幅提醒或应用范围内的本地化字符串。每个 Global 都可以拥有自己独立的 Access Control、Hooks、Admin Options 等配置。

要在 Payload Config 中定义 Global 配置，请使用 globals 属性：

import { buildConfig } from 'payload'

export default buildConfig({
  // ...
  globals: [
    // highlight-line
    // 在此处定义你的 Globals
  ],
})

提示： 如果有多个结构相同的 Globals， 建议改用 Collection。

配置选项

最佳实践通常是将你的 Globals 写在单独的文件中，然后导入到主 Payload 配置 中。

以下是一个简单的 Global Config 示例：

import { GlobalConfig } from 'payload'

export const Nav: GlobalConfig = {
  slug: 'nav',
  fields: [
    {
      name: 'items',
      type: 'array',
      required: true,
      maxRows: 8,
      fields: [
        {
          name: 'page',
          type: 'relationship',
          relationTo: 'pages', // "pages" 是现有 collection 的 slug
          required: true,
        },
      ],
    },
  ],
}

提醒： 更多复杂示例，请查看 Payload 仓库中的 模板 和 示例 目录。

以下是可用的配置选项：

选项描述
access提供访问控制函数，精确定义谁可以对当前 Global 执行哪些操作。更多详情。
admin管理面板的配置选项。更多详情。
custom用于添加自定义数据的扩展点（例如插件使用）
dbName根据数据库适配器自定义此 Global 的表名或集合名。如果未定义，则根据 slug 自动生成。
description显示在 Global 标题下方的文本或 React 组件，为编辑者提供更多信息。
endpoints向 REST API 添加自定义路由。更多详情。
fields *字段类型数组，决定此 Global 内存储数据的结构和功能。更多详情。
graphQL管理与此 global 相关的 GraphQL 属性。更多详情。
hooks钩子的入口点。更多详情。
label管理面板中显示的名称文本，或包含每种语言键的对象。如果未定义，则根据 slug 自动生成。
lockDocuments启用或禁用文档锁定。默认情况下，文档锁定是启用的。设置为对象进行配置，或设置为 false 禁用锁定。更多详情。
slug *唯一、URL 友好的字符串，作为此 Global 的标识符。
typescript包含 interface 属性的对象，用于 schema 生成。如果未定义，则根据 slug 自动生成。
versions设置为 true 启用默认选项，或使用对象属性进行配置。更多详情。
forceSelect指定哪些字段应该始终被选中，忽略 select 查询，这对于确保字段存在于访问控制/钩子中很有用

* 星号表示该属性是必填项。

字段

字段定义了 Global 的数据结构。要了解更多信息，请参阅 字段 文档。

访问控制

Global 访问控制 决定了用户可以对任何给定的 Global 文档执行哪些操作。要了解更多信息，请参阅 访问控制 文档。

钩子

Global 钩子 允许你挂接到文档的生命周期中，从而在特定事件期间执行自定义逻辑。要了解更多信息，请参阅 钩子 文档。

管理选项

Admin Panel 中的 Globals 行为可以完全自定义，以满足你的应用需求。这包括分组或隐藏导航链接、添加自定义组件、设置页面元数据等。

要为 Globals 配置管理选项，可以在 Global Config 中使用 admin 属性：

import { GlobalConfig } from 'payload'

export const MyGlobal: GlobalConfig = {
  // ...
  admin: {
    // highlight-line
    // ...
  },
}

可用选项如下：

选项描述
group用于在管理导航中分组 Collection 和 Global 链接的文本或本地化对象。设置为 false 可从导航中隐藏链接，同时保持其路由可访问。
hidden设置为 true 或一个函数（接收当前用户作为参数），返回 true 时将从导航和管理路由中排除此 Global。
components替换为此 Global 使用的自定义 React 组件。更多详情。
preview生成此 Global 在 Admin Panel 中的预览 URL 的函数，可指向你的应用。更多详情。
livePreview启用实时编辑功能，即时获取前端应用的视觉反馈。更多详情。
hideAPIURL在此集合中编辑文档时隐藏"API URL"元字段。
meta应用于此 Global 在 Admin Panel 中的页面元数据覆盖。更多详情。

自定义组件

Globals 可以设置自己的自定义组件，这些组件仅适用于管理面板中特定于 Global 的 UI。这包括诸如保存按钮之类的元素，或者诸如编辑视图之类的完整布局。

要覆盖 Global 组件，请在 Global Config 中使用 admin.components 属性：

import type { SanitizedGlobalConfig } from 'payload'

export const MyGlobal: SanitizedGlobalConfig = {
  // ...
  admin: {
    components: {
      // highlight-line
      // ...
    },
  },
}

以下是可用的选项：

通用选项

选项描述
elements覆盖或创建编辑视图中的新元素。更多详情。
views覆盖或创建管理面板中的新视图。更多详情。

编辑视图选项

import type { SanitizedGlobalConfig } from 'payload'

export const MyGlobal: SanitizedGlobalConfig = {
  // ...
  admin: {
    components: {
      elements: {
        // highlight-line
        // ...
      },
    },
  },
}

可用选项如下：

OptionDescription
SaveButton用自定义组件替换默认的保存按钮。草稿功能必须禁用。更多详情。
SaveDraftButton用自定义组件替换默认的保存草稿按钮。草稿功能必须启用且自动保存必须禁用。更多详情。
PublishButton用自定义组件替换默认的发布按钮。草稿功能必须启用。更多详情。
PreviewButton用自定义组件替换默认的预览按钮。预览功能必须启用。更多详情。

注意： 关于如何构建自定义组件的详细信息，请参阅构建自定义组件。

GraphQL

你可以通过在全局配置中设置 graphQL: false 来完全禁用该全局的 GraphQL 功能。这将完全禁用所有查询、变更和类型出现在你的 GraphQL 模式中。

你也可以向全局的 graphQL 属性传递一个对象，该对象允许你定义以下属性：

OptionDescription
name覆盖在 GraphQL 模式生成中使用的名称。
disableQueries通过设置为 true 来禁用与该全局相关的所有 GraphQL 查询。
disableMutations通过设置为 true 来禁用与该全局相关的所有 GraphQL 变更。

TypeScript

你可以从 Payload 导入类型，以帮助更轻松且类型安全地编写全局配置。主要有两种类型代表全局配置：GlobalConfig 和 SanitizedGlobalConfig。

GlobalConfig 类型表示原始形式的全局配置，其中只有最基本的属性被标记为必需。SanitizedGlobalConfig 类型表示经过完全清理后的全局配置。通常，这仅在 Payload 内部使用。

import type { GlobalConfig, SanitizedGlobalConfig } from 'payload'