Field
描述
作为 @silver-formily/core 中 createField 的 React 实现，它是专门用于将 ViewModel 与输入控件做绑定的桥接组件，Field 组件属性参考 IFieldFactoryProps
name 属性必填。
Field 与 ArrayField、ObjectField、VoidField 使用相同的挂载生命周期处理。StrictMode 同步重放 effect 时，不会额外触发字段的 onFieldMount / onFieldUnmount；字段实例变化或真正卸载时仍正常清理。真正卸载的清理延迟到微任务执行，因此不要在移除组件后立即同步读取 unmounted 来判断清理是否完成。
用例
import type { ReactNode } from 'react'
import { createForm } from '@silver-formily/core'
import { Field, FormProvider } from '@silver-formily/react'
import { Input } from 'antd'
import { StrictMode, useState } from 'react'
function Decorator({ content, children }: { content?: ReactNode, children?: ReactNode }) {
return (
<label>
{children}
<small>{content}</small>
</label>
)
}
export default function Demo() {
const [form] = useState(() => createForm({
initialValues: { input: '初始值' },
}))
return (
<StrictMode>
<FormProvider form={form}>
<Field
name="input"
component={[Input, { placeholder: '请输入' }]}
decorator={[Decorator]}
decoratorContent={['提示：', <span key="help">请输入内容</span>]}
/>
<Field name="zero" content={0} />
</FormProvider>
</StrictMode>
)
}import type { ReactNode } from 'react'
import { createForm } from '@silver-formily/core'
import { Field, FormProvider } from '@silver-formily/react'
import { Input } from 'antd'
import { StrictMode, useState } from 'react'
function Decorator({ content, children }: { content?: ReactNode, children?: ReactNode }) {
return (
<label>
{children}
<small>{content}</small>
</label>
)
}
export default function Demo() {
const [form] = useState(() => createForm({
initialValues: { input: '初始值' },
}))
return (
<StrictMode>
<FormProvider form={form}>
<Field
name="input"
component={[Input, { placeholder: '请输入' }]}
decorator={[Decorator]}
decoratorContent={['提示：', <span key="help">请输入内容</span>]}
/>
<Field name="zero" content={0} />
</FormProvider>
</StrictMode>
)
}API
Field 属性
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| name | 字段在 Form 中的路径，必须唯一 | FormPathPattern | — |
| basePath | 推导 name 的基准路径，常用于局部表单或数组项 | FormPathPattern | 父字段 address，否则为表单根路径 |
| title | 字段展示标题，通常映射到装饰器组件的 label | any | — |
| description | 字段辅助描述信息 | any | — |
| value | 字段当前值（受控模式） | any | — |
| initialValue | 字段初始值，初始化规则由 Core 决定 | any | — |
| required | 是否必填，会驱动校验与 UI 状态 | boolean | false |
| display | 展示状态：visible、hidden、none | enum | visible |
| pattern | 交互模式：editable、readOnly、disabled、readPretty | enum | editable |
| hidden | 隐藏渲染但保留字段值（display: hidden） | boolean | false |
| visible | false 设置 display: none；true 设置 display: visible | boolean | true |
| editable | 是否允许编辑 | boolean | true |
| disabled | 是否禁用（组件不可交互） | boolean | false |
| readOnly | 是否只读（仍可聚焦但不可修改） | boolean | false |
| readPretty | 是否进入只读展示态（常配合 mapReadPretty 使用） | boolean | false |
| loading | 字段加载态 | boolean | false |
| dataSource | 组件可选项数据源，为可扩展属性的对象数组 | FieldDataSource（来自 @silver-formily/core） | - |
| validateFirst | 校验失败时是否立即停止后续规则 | boolean | 省略时使用表单设置 |
| validatePattern | 仅在指定 pattern 下触发的校验 | FieldPatternTypes[] | 表单设置，否则 ['editable'] |
| validateDisplay | 仅在指定 display 下触发的校验 | FieldDisplayTypes[] | 表单设置，否则 ['visible'] |
| validator | 自定义校验器，签名与 Formily validator 一致 | FieldValidator | — |
| decorator | 装饰器组件及其 props，形如 [Decorator, props] | [] | [D] | [D, Partial<React.ComponentProps<D>>] | — |
| decoratorContent beta | 装饰器内容：纯内容（字符串/ReactNode）作为约定 prop content 传给装饰器，对象映射展开为装饰器的多个 props，与 decorator props 同名时优先 | string | React.ReactNode | Record<string, React.ReactNode> | — |
| component | 输入组件及其 props，形如 [Component, props] | [] | [C] | [C, Partial<React.ComponentProps<C>>] | — |
| reactions | 响应式副作用，支持函数或函数数组 | FieldReaction[] | FieldReaction | — |
| mountedReactions 1.0.0 | 表单首批字段全部挂载后启动、字段卸载时自动停止的响应式副作用 | FieldReaction[] | FieldReaction | — |
| content | 传给输入组件的子节点 | any | — |
| data | 透传的扩展数据，可在副作用或组件中读取 | any | — |
| children | 渲染函数或子节点，渲染函数接收 (field, form) | Function | React.ReactNode | — |
提示
只有 component / decorator 元组中的 props 会传给对应组件，任意顶层 Field 属性不会自动展开到 UI 组件。数据字段注入 value、onChange、onFocus、onBlur，事件先更新模型，再调用最新的同名组件回调。组件显式传入的 disabled / readOnly 优先于字段 pattern 推导值；checkbox 等使用不同值属性的组件可通过 connect / mapProps 适配。
hidden 与 none 都不渲染内容；Core 对 hidden 保留值，对 none 移除值并在恢复显示时恢复缓存值。字段模型是否挂载与内部 UI 是否可见是不同概念。
children（含渲染函数结果）与 field.content ?? field.componentProps.children 合并渲染，数值 0 是有效内容。未配置 component 时仍渲染内容。组件和装饰器可以是原生标签名或 React 组件；Schema 注册名称通过 SchemaComponentsContext 解析。
Core 将 title、description、content 声明为 any，放入 React 渲染树的内容仍须是合法 ReactNode。表中 display/pattern 默认值以没有父字段或表单状态覆盖为前提。