JSON 字段

The JSON field type allows you to store any valid JSON data in your database. This is useful when you need to store unstructured data or data that doesn't fit neatly into other field types.

Basic Usage

Here's a basic example of how to use the JSON field in your collection:

import { CollectionConfig } from 'payload/types'

const ExampleCollection: CollectionConfig = {
  slug: 'examples',
  fields: [
    {
      name: 'metadata',
      type: 'json',
    },
  ],
}

This will create a JSON field that can store any valid JSON data.

JSON Schema Validation

You can validate the JSON data against a schema using the jsonSchema property:

import { CollectionConfig } from 'payload/types'

const ExampleCollection: CollectionConfig = {
  slug: 'examples',
  fields: [
    {
      name: 'metadata',
      type: 'json',
      jsonSchema: {
        type: 'object',
        properties: {
          title: { type: 'string' },
          description: { type: 'string' },
          count: { type: 'number' },
          isActive: { type: 'boolean' },
        },
        required: ['title'],
      },
    },
  ],
}

This will ensure that the JSON data matches the specified schema before saving to the database.

Admin UI Configuration

You can customize how the JSON field appears in the admin UI:

{
  name: 'metadata',
  type: 'json',
  admin: {
    description: 'Enter any valid JSON data',
    placeholder: '{"key": "value"}',
    width: '100%',
  }
}

Options

PropertyTypeDescription
namestring字段名称
type'json'必须设置为 'json'
requiredboolean是否必填
jsonSchemaobject用于验证 JSON 数据的 JSON Schema
adminobject管理界面配置选项

Example with All Options

Here's a complete example showing all available options:

import { CollectionConfig } from 'payload/types'

const ExampleCollection: CollectionConfig = {
  slug: 'examples',
  fields: [
    {
      name: 'metadata',
      type: 'json',
      required: true,
      jsonSchema: {
        type: 'object',
        properties: {
          title: { type: 'string' },
          description: { type: 'string' },
        },
        required: ['title'],
      },
      admin: {
        description: 'Enter metadata for this item',
        placeholder: '{"title": "Example"}',
        width: '100%',
      },
    },
  ],
}

注意： JSON 字段不会自动验证数据类型，除非你提供了 jsonSchema。建议始终使用 JSON Schema 来确保数据完整性。

JSON 字段将原始 JSON 数据保存到数据库，并为管理面板提供代码编辑器风格的界面。这与代码字段不同，后者将值作为字符串保存在数据库中。

展示 Payload 管理面板中的 JSON 字段
该字段使用了 `monaco-react` 编辑器的语法高亮功能。

要添加 JSON 字段，请在字段配置中将 type 设置为 json：

import type { Field } from 'payload'

export const MyJSONField: Field = {
  // ...
  type: 'json', // highlight-line
}

配置选项

选项描述
name *作为属性名存储在数据库中并从数据库检索时使用。了解更多
label在管理面板中用作字段标签的文本，或为每种语言提供键值对的对象。
unique强制要求集合中每个条目在此字段上具有唯一值。
index为此字段构建索引以加快查询速度。如果用户会频繁查询此字段的数据，请将此字段设为 true。
validate提供自定义验证函数，该函数将在管理面板和后端执行。了解更多
jsonSchema提供用于验证的 JSON schema。JSON schemas
saveToJWT如果此字段是顶级字段且嵌套在支持身份验证的配置中，则将其数据包含在用户 JWT 中。
hooks提供字段钩子来控制此字段的逻辑。更多详情。
access提供字段访问控制，指定用户可以对此字段数据执行的操作。更多详情。
hidden完全限制此字段在所有 API 中的可见性。仍会保存到数据库，但不会出现在任何 API 或管理面板中。
defaultValue提供用于此字段默认值的数据。了解更多
localized为此字段启用本地化。需要在基础配置中启用本地化。
required要求此字段必须有值。
admin管理面板特定配置。更多详情。
custom用于添加自定义数据的扩展点（例如插件使用）
typescriptSchema通过提供 JSON schema 来覆盖字段类型生成
virtual提供 true 以禁用数据库中的字段，或提供字符串路径来将字段与关系字段链接。参见虚拟字段

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

管理选项

要自定义 JSON 字段在管理面板中的外观和行为，可以使用 admin 选项：

import type { Field } from 'payload'

export const MyJSONField: Field = {
  // ...
  admin: {
    // highlight-line
    // ...
  },
}

JSON 字段继承了基础字段管理配置中的所有默认管理选项，并额外支持以下选项：

选项描述
editorOptions可以传递给 monaco 编辑器的选项，查看完整列表。

示例

collections/ExampleCollection.ts

import type { CollectionConfig } from 'payload'

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

JSON Schema 验证

Payload 的 JSON 字段完全支持 JSON schema 标准。通过在字段配置中提供 schema，编辑器将在管理界面中获得引导，自动获取属性及其格式的类型提示。当文档保存时，默认验证将根据配置中的 schema 阻止保存任何无效数据。

如果仅提供 schema 的 URL，Payload 会在该 schema 公开可用时获取它。如果不可用，建议直接将 schema 添加到配置中或从其他文件导入，以便在项目中保持一致实现。

本地 JSON Schema

collections/ExampleCollection.ts

import type { CollectionConfig } from 'payload'

export const ExampleCollection: CollectionConfig = {
  slug: 'example-collection',
  fields: [
    {
      name: 'customerJSON', // 必填
      type: 'json', // 必填
      jsonSchema: {
        uri: 'a://b/foo.json', // 必填
        fileMatch: ['a://b/foo.json'], // 必填
        schema: {
          type: 'object',
          properties: {
            foo: {
              enum: ['bar', 'foobar'],
            },
          },
        },
      },
    },
  ],
}
// {"foo": "bar"} 或 {"foo": "foobar"} - 有效
// 尝试创建 {"foo": "not-bar"} 将会抛出错误

远程 JSON 模式

collections/ExampleCollection.ts

import type { CollectionConfig } from 'payload'

export const ExampleCollection: CollectionConfig = {
  slug: 'example-collection',
  fields: [
    {
      name: 'customerJSON', // 必填
      type: 'json', // 必填
      jsonSchema: {
        uri: 'https://example.com/customer.schema.json', // 必填
        fileMatch: ['https://example.com/customer.schema.json'], // 必填
      },
    },
  ],
}
// 如果 'https://example.com/customer.schema.json' 包含 JSON 模式
// {"foo": "bar"} 或 {"foo": "foobar"} - 有效
// 尝试创建 {"foo": "not-bar"} 将会抛出错误

自定义组件

字段

服务端组件

import type React from 'react'
import { JSONField } from '@payloadcms/ui'
import type { JSONFieldServerComponent } from 'payload'

export const CustomJSONFieldServer: JSONFieldServerComponent = ({
  clientField,
  path,
  schemaPath,
  permissions,
}) => {
  return (
    <JSONField
      field={clientField}
      path={path}
      schemaPath={schemaPath}
      permissions={permissions}
    />
  )
}

客户端组件

'use client'
import React from 'react'
import { JSONField } from '@payloadcms/ui'
import type { JSONFieldClientComponent } from 'payload'

export const CustomJSONFieldClient: JSONFieldClientComponent = (props) => {
  return <JSONField {...props} />
}

标签

服务端组件

import React from 'react'
import { FieldLabel } from '@payloadcms/ui'
import type { JSONFieldLabelServerComponent } from 'payload'

export const CustomJSONFieldLabelServer: JSONFieldLabelServerComponent = ({
  clientField,
  path,
}) => {
  return (
    <FieldLabel
      label={clientField?.label || clientField?.name}
      path={path}
      required={clientField?.required}
    />
  )
}

客户端组件

'use client'
import React from 'react'
import { FieldLabel } from '@payloadcms/ui'
import type { JSONFieldLabelClientComponent } from 'payload'

export const CustomJSONFieldLabelClient: JSONFieldLabelClientComponent = ({
  field,
  path,
}) => {
  return (
    <FieldLabel
      label={field?.label || field?.name}
      path={path}
      required={field?.required}
    />
  )
}