Query Presets

查询预设(Query Presets)功能允许你保存和分享针对Collections的筛选条件、列显示和排序设置。这对于复用常见或复杂的筛选模式，以及在团队间共享这些设置非常有用。

每个查询预设都会作为新记录保存在数据库的payload-query-presets集合中。这样可以实现无限数量的预设配置，由应用程序用户自行定义对他们最有用的预设，而不是将这些预设硬编码到Payload配置中。

在Admin Panel中，查询预设会应用到列表视图(List View)。启用该功能后，界面会显示新的控件供用户管理预设。保存后，这些预设可以随时加载，并选择性地与他人共享。

要在Collection中启用查询预设功能，请在Collection Config中使用enableQueryPresets属性：

import type { CollectionConfig } from 'payload'

export const MyCollection: CollectionConfig = {
  // ...
  // highlight-start
  enableQueryPresets: true,
  // highlight-end
}

配置选项

虽然非必需，但你可能需要自定义 Query Presets 的行为以满足需求，例如添加自定义标签或访问控制规则。

Query Presets 的设置通过 Payload Config 根目录下的 queryPresets 属性进行管理：

import { buildConfig } from 'payload'

const config = buildConfig({
  // ...
  // highlight-start
  queryPresets: {
    // ...
  },
  // highlight-end
})

Query Presets 提供以下配置选项：

Option描述
access用于定义应用于所有预设的自定义集合级别访问控制。更多详情。
filterConstraints用于定义管理预设时可用的约束条件。更多详情。
constraints用于定义应用于单个预设的自定义文档级别访问控制。更多详情。
labels为 Query Presets 集合使用的自定义标签。

访问控制

Query Presets 遵循与 Payload 其他部分相同的访问控制规则。这意味着你可以使用熟悉的模式来控制谁可以读取、更新和删除预设。

Query Presets 的访问控制可通过两种方式自定义：

  1. 集合访问控制：适用于所有预设。这些规则由用户控制，是在配置中静态定义的。
  2. 文档访问控制：适用于每个单独的预设。这些规则可由用户控制，是在数据库中的每条记录上动态定义的。

集合访问控制

集合级别的访问控制适用于 Query Presets 集合中的所有预设。用户无法控制这些规则，它们是在你的配置中静态编写的。

要为集合添加访问控制，请在 Payload 配置 中使用 queryPresets.access 属性：

import { buildConfig } from 'payload'

const config = buildConfig({
  // ...
  queryPresets: {
    // ...
    // highlight-start
    access: {
      read: ({ req: { user } }) =>
        user ? user?.roles?.some((role) => role === 'admin') : false,
      update: ({ req: { user } }) =>
        user ? user?.roles?.some((role) => role === 'admin') : false,
    },
    // highlight-end
  },
})

此示例将限制只有具有 admin 角色的用户才能访问所有 Query Presets。

注意： 自定义访问控制会覆盖此集合的默认设置， 包括要求用户进行身份验证的限制。除非你打算公开这些预设， 否则请确保在自定义规则中包含必要的检查。

文档访问控制

你还可以为每个特定预设定义访问控制规则。用户在管理预设时能够动态定义和修改这些规则。这些规则会实时保存到数据库的每条记录中。

当用户管理预设时，Admin Panel 中会为每个操作提供文档级别的访问控制选项。

默认情况下，Payload 为所有 Query Presets 提供了一组合理的默认设置，但你可以根据需要自定义这些规则：

  • 仅我：只有创建预设的用户可以读取、更新和删除它。
  • 所有人：所有用户都可以读取、更新和删除预设。
  • 特定用户：只有选定的用户可以读取、更新和删除预设。

自定义访问控制

你可以通过自定义规则来增强默认的访问控制功能。这对于创建更复杂的访问控制模式非常有用，例如基于角色的访问控制(RBAC)，这些是默认规则无法提供的。

添加自定义访问控制规则需要：

  1. 一个显示在下拉菜单中的标签
  2. 当该选项被选中时需要条件性渲染的一组字段
  3. 一个返回该选项访问控制规则的函数

要实现这一点，可以在你的 Payload 配置 中使用 queryPresets.constraints 属性。

import { buildConfig } from 'payload'

const config = buildConfig({
  // ...
  queryPresets: {
    // ...
    // highlight-start
    constraints: {
      read: [
        {
          label: '特定角色',
          value: 'specificRoles',
          fields: [
            {
              name: 'roles',
              type: 'select',
              hasMany: true,
              options: [
                { label: '管理员', value: 'admin' },
                { label: '用户', value: 'user' },
              ],
            },
          ],
          access: ({ req: { user } }) => ({
            'access.read.roles': {
              in: [user?.roles],
            },
          }),
        },
      ],
    },
    // highlight-end
  },
})

在这个例子中，我们添加了一个名为"特定角色"的新选项，允许用户从角色列表中进行选择。当选择此选项时，用户将被提示从选项列表中选择一个或多个角色。该选项的访问控制规则是：操作预设的用户必须拥有所选角色之一。

注意： Payload 会将你的自定义字段放入 access[operation] 字段组中，因此你的规则需要反映这一点。

每个约束可用的选项如下：

选项描述
label该约束在下拉菜单中显示的标签
value当选择此约束时存储在数据库中的值
fields当选择此约束时需要渲染的字段数组
access一个确定该约束访问控制规则的函数

约束条件访问控制

用于根据当前用户、文档数据或其他标准动态筛选可用的约束条件。

一些典型应用场景包括：

  • 确保只有"管理员"才能将预设设为"所有人"可用
  • 根据假设的"disablePrivatePresets"复选框来阻止选择"仅限我"选项

当用户没有权限设置某个约束条件时，该选项要么会被隐藏，要么如果已经保存到该预设中则会被禁用。

要实现这一点，你可以在 Payload 配置 中使用 filterConstraints 属性：

import { buildConfig } from 'payload'

const config = buildConfig({
  // ...
  queryPresets: {
    // ...
    // highlight-start
    filterConstraints: ({ req, options }) =>
      !req.user?.roles?.includes('admin')
        ? options.filter(
            (option) =>
              (typeof option === 'string' ? option : option.value) !==
              'everyone',
          )
        : options,
    // highlight-end
  },
})

filterConstraints 函数接收与 Select 字段 中的 filterOptions 相同的参数。