上传字段

Upload Field（上传字段）允许从支持上传的集合中选择文档，并在管理面板中将所选内容格式化为缩略图显示。

上传字段适用于多种使用场景，例如：

  • 为 Page 页面提供特色图片
  • 允许 Product 产品提供可下载资源（如 PDF 或 MP3）
  • 为布局构建块添加背景图片功能
展示 Payload 管理面板中的上传字段
上传字段在管理面板中的截图

要创建上传字段，需在字段配置中将 type 设置为 upload：

import type { Field } from 'payload'

export const MyUploadField: Field = {
  // ...
  // highlight-start
  type: 'upload',
  relationTo: 'media',
  // highlight-end
}

重要提示： 使用上传字段前，必须配置支持上传的集合。

配置选项

选项描述
name *作为属性名用于数据库存储和检索。了解更多
relationTo *提供一个 collection slug 允许此字段建立关联关系。注意：关联的 collection 必须配置为支持上传功能。
filterOptions用于筛选在 UI 中显示的上传选项并进行验证的查询。了解更多。
hasMany布尔值，设置为 true 时允许此字段建立多个关联关系而非仅一个。
minRows当存在值时，验证允许的最小项目数。与 hasMany 一起使用。
maxRows当存在值时，验证允许的最大项目数。与 hasMany 一起使用。
maxDepth设置查询时关联文档的递归填充深度限制。深度
label在 Admin Panel 中用作字段标签的文本，或包含每种语言键的对象。
unique强制 Collection 中每个条目此字段的值必须唯一。
validate提供自定义验证函数，将在 Admin Panel 和后台执行。了解更多
index为此字段构建索引以加快查询速度。如果用户会频繁查询此字段数据，请将此字段设为 true。
saveToJWT如果此字段是顶级字段且嵌套在支持身份验证的配置中，则将其数据包含在用户 JWT 中。
hooks提供字段钩子来控制此字段的逻辑。更多详情。
access提供字段访问控制以指定用户可以对此字段数据执行的操作。更多详情。
hidden完全限制此字段在所有 API 中的可见性。仍会保存到数据库，但不会出现在任何 API 或 Admin Panel 中。
defaultValue提供用于此字段默认值的数据。了解更多
displayPreview启用上传文件的预览显示。覆盖关联 Collection 的 displayPreview 选项。了解更多。
localized为此字段启用本地化功能。需要在基础配置中启用本地化。
required要求此字段必须有值。
admin管理员特定配置。管理员选项。
custom用于添加自定义数据（例如插件）的扩展点
typescriptSchema通过提供 JSON schema 覆盖字段类型生成
virtual提供 true 以禁用数据库中的字段，或提供字符串路径来将字段与关系链接。参见虚拟字段
graphQL字段的自定义 graphQL 配置。更多详情

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

示例

collections/ExampleCollection.ts

import type { CollectionConfig } from 'payload'

export const ExampleCollection: CollectionConfig = {
  slug: 'example-collection',
  fields: [
    {
      name: 'backgroundImage', // 必填
      type: 'upload', // 必填
      relationTo: 'media', // 必填
      required: true,
    },
  ],
}

过滤上传选项

可以通过提供 query constraint 来动态限制选项，该约束将用于验证输入和过滤 UI 中可用的上传内容。

filterOptions 属性可以是 Where 查询，也可以是一个返回 true（表示不过滤）、false（阻止所有）或 Where 查询的函数。当使用函数时，它将接收一个包含以下属性的参数对象：

属性描述
relationTo要过滤的 collection slug，仅限于该字段的 relationTo 属性
data包含当前正在编辑的完整 collection 或 global 文档的对象
siblingData包含仅限该字段同一父级范围内字段数据的对象
id当前正在编辑文档的 id。在 create 操作期间 id 为 undefined
user包含当前认证用户的对象
reqPayload 请求对象，包含对 payload、user、locale 等的引用。

示例#filter-options-example

const uploadField = {
  name: 'image',
  type: 'upload',
  relationTo: 'media',
  filterOptions: {
    mimeType: { contains: 'image' },
  },
}

你可以在这里了解更多关于编写查询的内容 查询文档。

注意：

当上传字段同时设置了 filterOptions 和自定义的

validate 函数时，API 将不会验证 filterOptions 除非你在 validate 函数中调用从

payload/shared 导入的默认上传字段验证函数。

双向关系

单独的 upload 字段用于引用上传集合中的文档，这可以视为"单向" 关系。如果你希望允许编辑者访问上传文档并查看它被使用的位置，可以在 上传启用的集合中使用 join 字段。了解更多关于双向关系的内容，请参阅 Join 字段文档