数字字段

数字字段（Number Field）用于存储和验证数字输入，并支持额外的数值验证和格式化功能。

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

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

import type { Field } from 'payload'

export const MyNumberField: Field = {
  // ...
  type: 'number', // highlight-line
}

配置选项

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

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

管理选项

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

import type { Field } from 'payload'

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

数字字段继承了基础 Field Admin Config 的所有默认管理选项，并新增了以下额外选项：

属性描述
step设置数字字段使用浏览器控件增减时的步长值。
placeholder设置该属性可为字段定义占位符文本。
autoComplete设置该属性将用于浏览器自动填充的字符串。

示例

collections/ExampleCollection.ts

import type { CollectionConfig } from 'payload'

export const ExampleCollection: CollectionConfig = {
  slug: 'example-collection',
  fields: [
    {
      name: 'age', // 必填
      type: 'number', // 必填
      required: true,
      admin: {
        step: 1,
      },
    },
  ],
}

自定义组件

字段组件

服务端组件

import type React from 'react'
import { NumberField } from '@payloadcms/ui'
import type { NumberFieldServerComponent } from 'payload'

export const CustomNumberFieldServer: NumberFieldServerComponent = ({
  clientField,
  path,
  schemaPath,
  permissions,
}) => {
  return (
    <NumberField
      field={clientField}
      path={path}
      schemaPath={schemaPath}
      permissions={permissions}
    />
  )
}

客户端组件

'use client'
import React from 'react'
import { NumberField } from '@payloadcms/ui'
import type { NumberFieldClientComponent } from 'payload'

export const CustomNumberFieldClient: NumberFieldClientComponent = (props) => {
  return <NumberField {...props} />
}

标签

服务端组件

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

export const CustomNumberFieldLabelServer: NumberFieldLabelServerComponent = ({
  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 { NumberFieldLabelClientComponent } from 'payload'

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