单选组字段

Radio Field（单选字段）允许从预定义的一组可能值中选择一个值，并在 Admin Panel 中呈现一组单选按钮样式的输入。

展示 Payload 管理面板中的单选字段
管理面板中单选字段的截图

要添加 Radio Field，请在 Field Config 中将 type 设置为 radio：

import type { Field } from 'payload'

export const MyRadioField: Field = {
  // ...
  // highlight-start
  type: 'radio',
  options: [
    // ...
  ],
  // highlight-end
}

配置选项

选项描述
name *作为存储在数据库中及从数据库检索时的属性名使用。了解更多
options *允许该字段存储的选项数组。可以是字符串数组，也可以是包含 label 字符串和 value 字符串的对象数组。
label在 Admin Panel 中用作字段标签的文本，或为每种语言提供键值的对象。
validate提供自定义验证函数，该函数将在 Admin Panel 和后台执行。了解更多
index为此字段构建索引以加快查询速度。如果用户会频繁查询此字段的数据，请将此字段设置为 true。
saveToJWT如果此字段是顶级字段且嵌套在支持身份验证的配置中，则将其数据包含在用户 JWT 中。
hooks提供字段钩子来控制此字段的逻辑。更多详情。
access提供字段访问控制，以指定用户可以对此字段数据执行的操作。更多详情。
hidden完全限制此字段在所有 API 中的可见性。仍会保存到数据库，但不会出现在任何 API 或 Admin Panel 中。
defaultValue提供用于此字段默认值的数据。默认值必须存在于 options 提供的值中。了解更多
localized为此字段启用本地化。需要在基础配置中启用本地化。
required要求此字段必须有值。
admin特定于 Admin 的配置。更多详情。
custom用于添加自定义数据的扩展点（例如插件使用）
enumName使用 SQL 数据库适配器(Postgres)时此字段的自定义枚举名称。如果未定义，则根据名称自动生成。
interfaceName创建顶层的可重用 Typescript 接口 和 GraphQL 类型。
typescriptSchema通过提供 JSON schema 来覆盖字段类型生成
virtual提供 true 以在数据库中禁用该字段，或提供字符串路径以将字段与关系链接。参见虚拟字段

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

重要提示：

由于 GraphQL 枚举命名限制，选项值应为不包含连字符或特殊字符的字符串。允许使用下划线。如果您确定需要选项值为非字符串或包含特殊字符，它们将在用作 GraphQL 枚举之前进行相应格式化。

管理选项

要自定义 Admin Panel 中 Radio Field 的外观和行为，可以使用 admin 选项：

import type { Field } from 'payload'

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

Radio Field 继承了基础 Field Admin Config 的所有默认管理选项，并额外支持以下选项：

属性描述
layout允许将单选按钮组样式设置为水平或垂直分布的列表。默认值为 horizontal（水平）。

示例

collections/ExampleCollection.ts

import type { CollectionConfig } from 'payload'

export const ExampleCollection: CollectionConfig = {
  slug: 'example-collection',
  fields: [
    {
      name: 'color', // 必填
      type: 'radio', // 必填
      options: [
        // 必填
        {
          label: '薄荷色',
          value: 'mint',
        },
        {
          label: '深灰色',
          value: 'dark_gray',
        },
      ],
      defaultValue: 'mint', // 默认为 options 中的第一个值
      admin: {
        layout: 'horizontal',
      },
    },
  ],
}

自定义组件

字段组件

服务端组件

import type React from 'react'
import { RadioGroupField } from '@payloadcms/ui'
import type { RadioFieldServerComponent } from 'payload'

export const CustomRadioFieldServer: RadioFieldServerComponent = ({
  clientField,
  path,
  schemaPath,
  permissions,
}) => {
  return (
    <RadioGroupField
      field={clientField}
      path={path}
      schemaPath={schemaPath}
      permissions={permissions}
    />
  )
}

客户端组件

'use client'
import React from 'react'
import { RadioGroupField } from '@payloadcms/ui'
import type { RadioFieldClientComponent } from 'payload'

export const CustomRadioFieldClient: RadioFieldClientComponent = (props) => {
  return <RadioGroupField {...props} />
}

标签

服务端组件

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

export const CustomRadioFieldLabelServer: RadioFieldLabelServerComponent = ({
  clientField,
  path,
  required,
}) => {
  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 { RadioFieldLabelClientComponent } from 'payload'

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