---
group:
  title: 表单控件 
  order: 3 
title: Field
order: 1
toc: content
---

# Field 基础控件


> 常用于通用筛选表单及通用弹窗内，可指定类型后直接展示antd的基本控件

## 代码演示

###  基础用法
<code  src="../../src/FormComp/FieldComponent/demos/basic.tsx"></code>

###  控件状态
配置 fieldStatus 控制控件展示状态
<code   src="../../src/FormComp/FieldComponent/demos/fieldStatus.tsx" ></code>

<code title="日期类控件" src="../../src/FormComp/FieldComponent/demos/date.tsx" ></code>

<code title="select选择器" src="../../src/FormComp/FieldComponent/demos/select.tsx" ></code>

<code  title="tree-select下拉树" src="../../src/FormComp/FieldComponent/demos/tree-select.tsx"></code>

<code  title="tree-select表单用法" src="../../src/FormComp/FieldComponent/demos/tree-select-form.tsx"></code>

### RefactorTreeSelect 独立公共导出

6.x 可从包根路径直接导入 `RefactorTreeSelect`。它是 `Field type="tree-select"` 内部使用的树选择实现，适合不需要 Field 配置层、但仍需复用完整路径只读展示和 Ant Design 6 搜索适配时使用。

```tsx | pure
import { RefactorTreeSelect } from 'fan-standard-comp';
```

`showSearch` 支持布尔值或 Ant Design 6 的对象配置；对象中的 `treeNodeFilterProp` 优先于组件内部默认值。

<code  title="自定义结构" src="../../src/FormComp/FieldComponent/demos/custom.tsx"></code>

<code  title="扩展控件" src="../../src/FormComp/FieldComponent/demos/extend.tsx"></code>

### 输入控件前后扩展

Ant Design v6 不再推荐在 `Input`、`InputNumber` 上使用 `addonBefore`、`addonAfter`。Field 为 `input`、`inputNumber`、`password`、`textarea` 提供可选的 `Space.Compact` 包装，并使用 `Space.Addon` 渲染前后扩展内容。

前后扩展内容配置在 `protoConfig` 中；未配置 `compactBefore`、`compactAfter` 或 `compactConfig` 时不会增加包装结构。

```typescript
const fields = [
  {
    label: '金额',
    type: 'inputNumber',
    filedName: 'amount',
    protoConfig: {
      prefix: '￥',
      suffix: 'RMB',
      compactBefore: '收入',
      compactAfter: '元',
      compactConfig: {
        size: 'small',
        orientation: 'horizontal',
        block: true,
      },
      viewOnlyHides: ['compactBefore'],
    },
  },
];
```

`compactBefore` 和 `compactAfter` 可以是任意 `ReactNode`。`compactConfig` 会传给 `Space.Compact`，其中 `block` 默认是 `true`。Field 会继续把 `value`、`onChange`、`ref`、`id`、`prefix`、`suffix` 等属性传给真实输入控件。

旧的 `addonBefore`、`addonAfter` 仍可作为兼容配置使用，Field 会将其转换为 `Space.Addon`，不会再传给 antd 输入控件；新旧配置同时存在时，以 `compactBefore`、`compactAfter` 为准。新代码应使用 `compactBefore`、`compactAfter`。

`viewOnlyHides` 支持新旧名称，例如：

```typescript
viewOnlyHides: ['compactBefore', 'compactAfter', 'prefix', 'suffix']
```

`password` 和 `textarea` 也可以使用相同配置，但它们并不存在必须迁移的 antd addon API。这里提供的是统一的 Field 布局能力，使用前应确认多行文本高度、密码框切换按钮及禁用状态下的连接边框符合页面设计。

## API

| 参数      | 说明                                      | 类型         | 默认值 | 参考值 |
|----------|------------------------------------------|-------------|-------|-------|
| type | 表单控件类型（弃用 ~~monthPicker, weekPicker, yearPicker~~） | String | - |[可选值](#type-可选值) |
| filedName | 表单名称，会作为表单字段 id 前缀使用 | String| - |- |
| value | 表单控件值 | String/Array/Object | - |- |
| protoConfig | 表单控件原生属性配置,或antd对应组件的配置项 | Object | - |- |
| selectOptions | 用于`select、checkbox、radio`等多选项数据源 | Array | - |- |
| selectOptionName | 指定`select、checkbox、radio`结构的数据字段 | Object |  { value: 'value', label: 'label', disabled: 'disabled'} |- |
| onChange | 控件触发更新事件 | Function(value, [option]) |   |参数值及类型参考官网对应组件的onChange |
| fieldStatus | 配置化表单展示状态 | String | `default` |  `default` /`viewOnly` 只显示值不显示控件/`disabled`:控件禁用"|
| size | 控件大小(同官网的size) | String | 'middle' |`large`/`middle`/`small`  |
| render | (`custom`条件下使用)自定义渲染结构 | Function(props)=> React.ReactNode | - |- |
| selectOptionRender |  (选项类`select、checkbox、radio`等条件下使用)自定义本配置下拉选项列表内展示内容  | Function(data) | - |- |
| placeholder | 控件描述性文本 | String | '请选择/请输入' |- |
| style | 表单控件样式 | Object | - |- |
| extendComponents(仅适用全局配置） | 扩展控件组 | Array | - |[参考](#extendcomponents-配置项) |
| extendConfig | (扩展控件专用)自定义配置项 | Object | - |- |
| 其他 |  参考对应type的配置项|  ||

### 输入控件 Compact 配置项

以下配置位于 `protoConfig`，适用于 `input`、`inputNumber`、`password`、`textarea`。

| 参数 | 说明 | 类型 | 默认值 |
|------|------|------|--------|
| compactBefore | 输入控件前置扩展内容，使用 `Space.Addon` 渲染 | ReactNode | - |
| compactAfter | 输入控件后置扩展内容，使用 `Space.Addon` 渲染 | ReactNode | - |
| compactConfig | `Space.Compact` 配置 | Object | `{ block: true }` |
| addonBefore | 旧版兼容配置，推荐改用 `compactBefore` | ReactNode | - |
| addonAfter | 旧版兼容配置，推荐改用 `compactAfter` | ReactNode | - |

###  select配置项
| 参数      | 说明                                      | 类型         | 默认值 | 参考值 |
|----------|------------------------------------------|-------------|-------|-------|
| selectOptions | 数据源 | Array | - |同`protoConfig.options` |
| selectOptionName（ | 自定义数据字段名 | Object |  { value: 'value', label: 'label', disabled: 'disabled'} ||
| selectOptionRender | 自定义配置下拉选项列表内展示内容  | Function(data) | - | 同`protoConfig.optionRender` |

###  tree-select配置项
| 参数      | 说明                                      | 类型         | 默认值 | 参考值 |
|----------|------------------------------------------|-------------|-------|-------|
| treeData | 数据源，同`protoConfig.treeData` | `Array` | -| |
| treeOptionName | 自定义数据字段名，同`protoConfig.fieldNames` | Object |  `{ label: 'label', value: 'value', children: 'children' }` | |
| showFullLevel| 输入框内是否显示当前选中节点加上其完整父级节点的名称， `同protoConfig.treeNodeLabelProp = 'treeFullLevelName'`| Boolean | false |(`v4.1.23后不推荐使用`） |
| separator | `showFullLevel`返回值对应的分隔符自定义 | `String` | '/' |- |
| disabledFields | 指定禁用节点  | `Array<{key: string, value: string}>` |(value：多个字段值可用`,`隔开)|
| protoConfig.TreeNode(`v4.1.23弃用`） | TreeNode扩展配置  |`Object` ||
| protoConfig.treeNodeLabelProp(`v4.1.23`） | 官方配置，可指定作为显示的 prop 设置  |`String` ||
| protoConfig.collapsable(`v4.1.27`） | `multiple`或`treeCheckable`下，且未配置`treeNodeLabelProp`，在`只读viewOnly`下显示成可折叠排版|`Boolean` ||
| protoConfig.collapsableTitleRender(`v4.1.27`） | 自定义可折叠排版下节点显示结构|`(key, labelText, nodePaths)=> ReactNode` ||
| protoConfig.collapsableCount(`v4.1.27`） | 可折叠排版下默认展示数量（不得小于1）|`Number` |2|
| protoConfig.collapsableClassName(`v4.1.27`） | 自定义可折叠排版className|`String` ||

###  extendComponents 配置项

| 参数      | 说明                                      | 类型         |  参考值 |
|----------|------------------------------------------|-------------|-------|
| extendType | 控件类型 | `String` |不能使用现有的type值|
| component |自定义组件| `ReactNode` 或 `function(props)` | - |


###  type='dateTimeRangePicker' 配置项

| 参数      | 说明                                      | 类型         | 默认值 | 参考值                                                          |
|----------|------------------------------------------|-------------|-------|--------------------------------------------------------------|
| value | 值 | `Object` || `{type: 'day', dateTime: []}`                                |
| onChange | 值更新事件 | `({type: 'day', dateTime: []})=> void` ||
| options | 指定显示的类型 | `Array` | | `['hour', 'day','week', 'month','year','quarter', 'custom']` |
| optionType | 设置Radio展示的类型 | `String` | `button` | `'radio'` \| `'button'`                                      | 
| timeTypeConfig | 配置指定显示类型特定的格式及配置 | `Object` |  | `{format, disableDate,其他}`                                   |
| radioConfig | 按钮组Radio扩展配置 | `Object` |  | ``                                                           |

### type 可选值

> 输入类：`input、password、textarea、inputNumber、OTP`
>
> 选项类： `select、tree-select、checkbox、radio`
>
> 日期类： `datePicker、dateTimePicker、rangePicker、rangeTimePicker、timePicker、timePickerRange、dateTimeRangePicker`
>
> 上传类： `upload、uploader`
>
> 数据类： `cascader、switch、slider、rate`
>
> 自定义：`custom`
>
> 扩展控件：`类型值由扩展控件组定义`