可用属性配置项

自定义组件可通过增加配置项来提高组件的复用度，满足用户的多样性选择和定制能力。但过多的配置项会增加用户对自定义组件的使用成本，所以需要适度收缩组件的可配置项，尽可能以最少最容易理解的配置项来提高组件的复用度。

本文列出可在自定义组件模型中可以使用的属性配置项。

支持两类配置项

在自定义组件 属性配置面板（组件模型文件 model.ts 中的 propsSchema）中可使用的配置项类型，分为两类：

自定义表单配置项：平台封装的表单项，用于配置字符串、数字、开关等常规属性。
平台数据源相关配置项：与实体、字段、视图等平台数据源相关的专用配置项。

一、表单类配置项

panelInput - 文本输入配置项

适用属性数值类型：字符串。

交互方式：用于短文本类配置（标题、占位说明、尺寸字符串等）。

说明：能力与 Neo Design Input 一致，详见 Input 输入框。

功能特性：

单行输入：适合标题、高度、提示文案等字符串配置
占位提示：可通过 placeholder 引导填写
数据存储：输入内容写入对应 name 的 value（string）
条件展示：可配合 visibleOn / hiddenOn 与其他配置项联动

使用方法：

在组件模型文件（model.ts）/ 属性配置（propsSchema）中添加使用：

json

{
  "type": "panelInput",
  "name": "height",
  "label": "高度",
  "placeholder": "例如 500px 或 100%",
  "visibleOn": "!autoHeight"
}

组件属性：

name: 字段名称
label: 标签文本
value: 当前值或初始值（string）
placeholder: 占位文案
disabled: 是否禁用
visibleOn / hiddenOn: 与其他字段联动显示（见上文）
onChange: 值变化回调

panelSelect - 下拉选择配置项

适用属性数值类型：单一值（与 options[].value 类型一致）。

交互方式：从固定选项中选择属性值，例如主题（暗黑、蓝色系、橙色系等）。

说明：能力与 Neo Design Select 一致（选项结构、禁用项等），详见 Select 选择器。

功能特性：

下拉单选：从 options 中选择一项
选项结构：options 为 { label, value }[]
数据存储：选中项的 value 写入表单 value
占位与禁用：支持 placeholder、disabled

使用方法：

在组件模型文件（model.ts）/ 属性配置（propsSchema）中添加使用：

json

{
  "type": "panelSelect",
  "name": "columnCount",
  "label": "表单列数",
  "value": 1,
  "placeholder": "请选择表单列数",
  "options": [
    { "label": "单列", "value": 1 },
    { "label": "双列", "value": 2 },
    { "label": "三列", "value": 3 }
  ]
}

组件属性：

name: 字段名称
label: 标签文本
value: 当前选中值（与 options[].value 类型一致）
options: 选项列表，{ label: string; value: unknown }[]
placeholder: 占位文案
disabled: 是否禁用
visibleOn / hiddenOn: 联动显示
onChange: 值变化回调

panelSwitch - 开关配置项

适用属性数值类型：布尔值。

交互方式：控制「是否显示」「是否禁用」等开关类属性。

说明：对应 Neo Design Switch，详见 Switch 开关。

功能特性：

开关展示：支持选中/未选中文案（checkedChildren、unCheckedChildren）
数据存储：布尔值写入 value
设计器集成：通过 ScopedContext 注册，可与设计器表单联动

使用方法：

在组件模型文件（model.ts）/ 属性配置（propsSchema）中添加使用：

json

{
  "type": "panelSwitch",
  "name": "disableSearch",
  "label": "禁用搜索",
  "defaultChecked": false,
  "hiddenOn": "hiddenHeader"
}

组件属性：

name: 字段名称
label: 标签文本
value / defaultChecked: 当前值或默认是否选中（boolean）
checkedChildren: 选中时展示文案，可为字符串或返回 ReactNode 的函数
unCheckedChildren: 未选中时展示文案，可为字符串或返回 ReactNode 的函数
disabled: 是否禁用
size: 尺寸，small | default
visibleOn / hiddenOn: 联动显示
onChange: 值变化回调

panelNumber - 数字输入配置项

适用属性数值类型：number | null。

交互方式：配置条数、精度、步长等数值。

说明：对应 Neo Design InputNumber，详见 InputNumber 数字输入框。

功能特性：

数字输入：支持最小值、最大值、步长、精度
数据存储：number \| null 写入 value
设计器集成：通过 ScopedContext 注册

使用方法：

在组件模型文件（model.ts）/ 属性配置（propsSchema）中添加使用：

json

{
  "type": "panelNumber",
  "name": "paginationPageSize",
  "label": "每页展示条数",
  "value": 20,
  "min": 1,
  "max": 500,
  "visibleOn": "!disablePagination"
}

组件属性：

name: 字段名称
label: 标签文本
value / defaultValue: 当前值或默认值（number | null）
min / max: 最小值、最大值
step: 步长（number 或 string）
precision: 小数位数
disabled: 是否禁用
size: large | middle | small
visibleOn / hiddenOn: 联动显示
onChange: 值变化回调

panelColor - 颜色选择器配置项

适用属性数值类型：颜色字符串（#RRGGBB 或 rgba(r,g,b,a)）。

交互方式：配置字体色、背景色、边框色等（含透明度）。

说明：基于 react-color 的 SketchPicker。

功能特性：

弹层选色：点击色块打开选择器，支持透明度
数据存储：#RRGGBB 或 rgba(r,g,b,a) 字符串写入 value
清除颜色：可清空为 undefined
禁用态：禁用时仅展示色块，不可编辑
设计器集成：ScopedContext 注册

使用方法：

在组件模型文件（model.ts）/ 属性配置（propsSchema）中添加使用：

json

{
  "type": "panelColor",
  "name": "backgroundColor",
  "label": "背景颜色",
  "defaultValue": "rgba(255, 255, 255, 1)"
}

组件属性：

name: 字段名称
label: 标签文本
value / defaultValue: 颜色字符串
disabled: 是否禁用
className: 自定义类名
onChange: 回调参数为 string \| undefined

以下类型与 Neo Design · Data Entry 数据录入 中的同名组件一致。交互细节、受控/非受控用法及完整 API 请以此索引下的子文档为准（若设计器对 type 使用 panel 等前缀，以实际解析为准）。

neoCascader - 级联选择配置项

适用属性数值类型：数组（各级选中 value 组成的路径）。

交互方式：多级关联选项的单选（部分版本支持多选）。

说明：能力与 Neo Design Cascader 一致，详见 Cascader 级联选择。

功能特性：

级联结构：通过 options 的树形结构（含 children）展示多级菜单
选中值：通常为各级选中项 value 组成的数组（选中路径）
搜索与异步：支持过滤展示；可按文档使用动态加载子级（loadData 等，以线上 API 为准）
数据存储：选中结果写入对应 name 的 value
条件展示：可配合 visibleOn / hiddenOn 联动

使用方法：

在组件模型文件（model.ts）/ 属性配置（propsSchema）中添加使用：

json

{
  "type": "neoCascader",
  "name": "region",
  "label": "地区",
  "placeholder": "请选择省 / 市 / 区",
  "options": [
    {
      "label": "浙江省",
      "value": "zj",
      "children": [{ "label": "杭州市", "value": "hz" }]
    }
  ]
}

常用属性（与 Neo Design 文档一致）：

name / label
value / defaultValue：选中路径，一般为 string[] 或 number[]
options：级联数据源
placeholder、disabled、allowClear
multiple（若版本支持多选级联）
visibleOn / hiddenOn、onChange

neoRadio - 单选配置项

适用属性数值类型：单一值（字符串、数字等）。

交互方式：选项较少时的单选配置。

说明：能力与 Neo Design Radio 一致，详见 Radio 单选框。

功能特性：

互斥单选：同一组内只能选中一项
选项展示：常用 Radio.Group 配合 options 或子节点渲染多个 Radio
数据存储：当前选中项的 value 写入表单
布局：支持按钮样式、排列方向等（见文档）

使用方法：

在组件模型文件（model.ts）/ 属性配置（propsSchema）中添加使用：

json

{
  "type": "neoRadio",
  "name": "layoutMode",
  "label": "布局",
  "options": [
    { "label": "横向", "value": "horizontal" },
    { "label": "纵向", "value": "vertical" }
  ]
}

常用属性：

name / label
value / defaultValue
options：{ label, value }[]（若设计器支持）
disabled、optionType（如 button）
visibleOn / hiddenOn、onChange

neoCheckbox - 多选框

适用属性数值类型：数组（多选时为选中值列表）。

交互方式：选项较少时的多选配置。

说明：能力与 Neo Design Checkbox 一致，详见 Checkbox 多选框。

功能特性：

单框布尔：单个 Checkbox 表示是否勾选（boolean）
组多选：Checkbox.Group 从多个选项中勾选若干项，value 为选中值的数组
全选/半选：组场景下可配合 indeterminate 等能力（见文档）
数据存储：布尔或 value[] 写入对应字段

使用方法：

在组件模型文件（model.ts）/ 属性配置（propsSchema）中添加使用：

json

{
  "type": "neoCheckbox",
  "name": "features",
  "label": "展示项",
  "options": [
    { "label": "标题", "value": "title" },
    { "label": "副标题", "value": "subtitle" }
  ]
}

常用属性：

name / label
value / defaultValue：多选时为数组
options：组模式下的选项列表
disabled
visibleOn / hiddenOn、onChange

neoDatePicker - 日期选择框

适用属性数值类型：日期（具体形态以平台绑定为准）。

交互方式：选择单日或日期范围。

说明：能力与 Neo Design DatePicker 一致，详见 DatePicker 日期选择框。

功能特性：

日期 / 周 / 月等：通过 picker 切换选择粒度（以文档为准）
范围选择：可使用 RangePicker 选择起止日期（若平台单独暴露类型则按其 type 配置）
格式化：format、showTime 等控制展示与是否含时间
数据存储：一般为日期对象或格式化字符串（与平台绑定约定一致）

使用方法：

在组件模型文件（model.ts）/ 属性配置（propsSchema）中添加使用：

json

{
  "type": "neoDatePicker",
  "name": "startDate",
  "label": "开始日期",
  "placeholder": "请选择日期",
  "format": "YYYY-MM-DD"
}

常用属性：

name / label
value / defaultValue
format、picker、showTime、allowClear
disabled、disabledDate
visibleOn / hiddenOn、onChange

neoTimePicker - 时间选择框

适用属性数值类型：时间（具体形态以平台绑定为准）。

交互方式：选择时刻（可与日期组合或单独使用，视组件封装而定）。

说明：能力与 Neo Design TimePicker 一致，详见 TimePicker 时间选择框。

功能特性：

时间选择：时、分、秒及步长配置（见文档）
格式化：format 控制展示与回填格式
数据存储：时间类值或字符串，依平台约定

使用方法：

在组件模型文件（model.ts）/ 属性配置（propsSchema）中添加使用：

json

{
  "type": "neoTimePicker",
  "name": "remindTime",
  "label": "提醒时间",
  "format": "HH:mm",
  "placeholder": "请选择时间"
}

常用属性：

name / label
value / defaultValue
format、allowClear、disabled
visibleOn / hiddenOn、onChange

neoRate - 评分

适用属性数值类型：数值。

交互方式：星级或分值评分。

说明：能力与 Neo Design Rate 一致，详见 Rate 评分。

功能特性：

星标展示：默认星级点击评分
半选与总数：allowHalf、count 等扩展行为（见文档）
数据存储：数值型评分写入 value

使用方法：

在组件模型文件（model.ts）/ 属性配置（propsSchema）中添加使用：

json

{
  "type": "neoRate",
  "name": "satisfaction",
  "label": "满意度",
  "count": 5,
  "allowHalf": true
}

常用属性：

name / label
value / defaultValue
count、allowHalf、disabled
visibleOn / hiddenOn、onChange

neoSlider - 滑动输入条

适用属性数值类型：number；开启区间模式（range）时为 [number, number]。

交互方式：在区间内拖动取值。

说明：能力与 Neo Design Slider 一致，详见 Slider 滑动输入条。

功能特性：

区间与步长：min、max、step
范围滑块：开启 range 时用双滑块选择区间，值为 [number, number]；关闭时为单个 number。
刻度与提示：marks、tooltip 等（见 Neo Design 文档）。
数据存储：非区间时为 number，区间时为 [number, number]。

使用方法：

在组件模型文件（model.ts）/ 属性配置（propsSchema）中添加使用：

json

{
  "type": "neoSlider",
  "name": "opacity",
  "label": "透明度",
  "min": 0,
  "max": 100,
  "step": 1
}

常用属性：

name / label
value / defaultValue
min、max、step、marks、disabled
visibleOn / hiddenOn、onChange

neoTransfer - 穿梭框

适用属性数值类型：数组（已选项的 key 列表，与 dataSource 配合）。

交互方式：左右两栏之间移动选项。

说明：能力与 Neo Design Transfer 一致，详见 Transfer 穿梭框。

功能特性：

双栏列表：左侧源列表、右侧已选列表
搜索与禁用：支持过滤、单项或整侧禁用
数据存储：已选 key 列表 targetKeys 与完整 dataSource 配合
大数据：可按文档使用懒加载、分页等模式

使用方法：

在组件模型文件（model.ts）/ 属性配置（propsSchema）中添加使用：

json

{
  "type": "neoTransfer",
  "name": "selectedKeys",
  "label": "字段分配",
  "dataSource": [
    { "key": "a", "title": "选项 A" },
    { "key": "b", "title": "选项 B" }
  ]
}

常用属性：

name / label
dataSource：含 key、title（及 disabled 等）
targetKeys / selectedKeys（命名以文档为准）
titles、showSearch、disabled
visibleOn / hiddenOn、onChange

neoTreeSelect - 树选择

适用属性数值类型：单选时为节点 value；多选时为 value[]。

交互方式：在树形数据中单选或多选节点。

说明：能力与 Neo Design TreeSelect 一致，详见 TreeSelect 树选择。

功能特性：

树形数据：treeData 描述父子节点
单选 / 多选：multiple、treeCheckable 等（见文档）
搜索与异步：可搜索节点；支持异步加载子节点时按文档配置
数据存储：选中节点的 value 或 value[]

使用方法：

在组件模型文件（model.ts）/ 属性配置（propsSchema）中添加使用：

json

{
  "type": "neoTreeSelect",
  "name": "categoryId",
  "label": "类目",
  "placeholder": "请选择类目",
  "treeData": [
    {
      "title": "一级",
      "value": "1",
      "children": [{ "title": "二级", "value": "1-1" }]
    }
  ]
}

常用属性：

name / label
treeData / treeDataSimpleMode（若使用）
value / defaultValue
multiple、treeCheckable、showSearch、allowClear
visibleOn / hiddenOn、onChange

neoUpload - 上传

适用属性数值类型：文件列表（平台约定的 URL、id 或文件对象结构，以绑定为准）。

交互方式：选择并上传文件（点击或拖拽）。

说明：能力与 Neo Design Upload 一致，详见 Upload 上传。

功能特性：

点击 / 拖拽：支持多种触发方式（见文档）
列表与预览：fileList、预览、移除
限制：accept、maxCount、大小校验、beforeUpload
上传地址与请求：action、headers、data 等与后端对接
数据存储：文件列表或平台约定的 URL / id 结构写入 value

使用方法：

在组件模型文件（model.ts）/ 属性配置（propsSchema）中添加使用：

json

{
  "type": "neoUpload",
  "name": "attachments",
  "label": "附件",
  "maxCount": 5,
  "accept": ".pdf,.png"
}

常用属性：

name / label
action、headers、data、name（字段名）
fileList / defaultFileList
multiple、accept、maxCount、beforeUpload、disabled
visibleOn / hiddenOn、onChange

二、平台数据源相关配置项

xObjectEntityList - 实体列表数据源

以下拉列表方式选择平台实体对象，在自定义组件中可通过选择的实体对象 key 获取实体业务类型列表、业务对象描述等数据。

功能特性：

实体列表展示：以下拉列表形式展示当前可选择的实体对象
搜索功能：支持实体名称搜索
数据存储：选择的实体 ID 存储到 value 中
实体类型控制：通过 custom 属性控制使用标准实体还是自定义实体

使用方法：

在组件模型文件（model.ts）/ 属性配置（propsSchema）中添加使用：

json

{
  "type": "xObjectEntityList",
  "name": "xObjectApiKey",
  "label": "对象实体列表",
  "custom": false
}

属性说明：

name: 字段名称
label: 标签文本
disabled: 是否禁用
custom: 是否使用自定义实体，设置为 false 则表示展示标准实体列表，不传则展示标准实体和自定义实体
value: 当前已选择的实体对象 ID（xObjectApiKey）
onChange: 值变化回调

xObjectDataApi - 实体业务数据列表数据源

用于配置列表类数据源：实体、fields、分页等，供组件拉取业务数据列表。

功能特性：

输入框展示：以输入框形式展示当前配置的实体和选择的字段信息
设置按钮：右侧设置图标，点击打开配置弹窗
实体类型选择：弹窗中支持选择标准实体或自定义实体
实体选择：弹窗中支持下拉选择实体
字段选择：使用 antd Transfer 组件选择字段，默认选中所有实体字段
分页配置：配置页码（默认展示第几页）和每页条数（每页展示多少条数据）
数据存储：选择的实体 ID 存储到 xObjectApiKey，选中的字段列表存储到 fields，字段信息列表存储到 fieldDescList，页码存储到 page，每页条数存储到 pageSize

使用方法：

在组件模型文件（model.ts）/ 属性配置（propsSchema）中添加使用：：

json

{
  "type": "xObjectDataApi",
  "name": "dataSource",
  "label": "数据源配置"
}

属性说明：

name: 字段名称
label: 标签文本
disabled: 是否禁用
value: 当前值，格式为 { xObjectApiKey: string, fields: string[], fieldDescList: object[], page: number, pageSize: number }
- xObjectApiKey: 选择的实体 API Key
- fields: 选中的字段列表
- fieldDescList: 字段信息列表
- page: 页码，默认为 1（默认展示第几页）
- pageSize: 每页条数，默认为 20（每页展示多少条数据）
onChange: 值变化回调

xObjectDetailApi - 实体详情数据源

用于配置单条详情数据源：实体、objectId、字段等，供组件拉取一条业务数据详情。

功能特性：

输入框展示：以输入框形式展示当前配置的实体、业务数据 ID 和字段信息
设置按钮：右侧设置图标，点击打开配置弹窗
实体选择：弹窗中支持下拉选择实体（标准实体/自定义实体）
业务数据 ID 选择：根据选择的实体，使用 xObject.query 获取业务数据列表，支持选择具体的业务数据 ID
字段选择：使用 antd Transfer 组件选择字段，默认全部选中
数据存储：选择的实体 ID 存储到 xObjectApiKey，业务数据 ID 存储到 objectId，字段列表存储到 fieldDescList

使用方法：

在组件模型文件（model.ts）/ 属性配置（propsSchema）中添加使用：：

json

{
  "type": "xObjectDetailApi",
  "name": "dataSource",
  "label": "业务详情数据源配置"
}

属性说明：

name: 字段名称
label: 标签文本
disabled: 是否禁用
value: 当前值，一般为
{ xObjectApiKey: string; objectId: string; fields?: string[]; fieldDescList?: object[] }
- xObjectApiKey：实体 API Key
- objectId：业务数据主键，支持上下文变量（如 ${recordId}）
- fields / fieldDescList：在面板中勾选字段后由配置项写入，供组件展示列或拉数
onChange: 值变化回调

特性

支持标准实体与自定义实体切换。
选择实体后可联动加载业务数据列表与字段列表。
各选择器支持搜索过滤。

selectFieldsApi - 字段 apiKey 多选（穿梭框）

在已配置实体（xObjectApiKey）的前提下，用穿梭框多选字段 apiKey。须与同表单内提供实体的配置项一起使用（例如 xObjectDataApi、xObjectDetailApi）。

功能特性：

输入框展示：以只读输入框展示「已选择 N 个字段」
设置按钮：右侧设置图标，点击打开「字段选择」弹窗
穿梭框选择：弹窗内使用 Transfer 在「可选字段」与「已选字段」间勾选，支持搜索
数据存储：选中的字段 apiKey 列表存储到 value（string[]）
联动数据源：通过 xObjectApiKey 指定从 props.data 中读取实体 key 的路径，实体变化时会重新拉取字段列表

使用方法：

在组件模型文件（model.ts）/ 属性配置（propsSchema）中添加使用，需与提供 xObjectApiKey 的配置项（如 xObjectDataApi、xObjectDetailApi）关联使用：

json

{
  "type": "selectFieldsApi",
  "name": "fields",
  "label": "选择字段",
  "xObjectApiKey": "dataSource.xObjectApiKey"
}

属性说明：

name: 字段名称
label: 标签文本
disabled: 是否禁用
xObjectApiKey: 从 props.data 中获取实体 API Key 的 key 名，不传则默认为 'xObjectApiKey'。若实体在嵌套对象中可传路径，如 'dataSource.xObjectApiKey'
value: 当前值，格式为 string[]（字段 apiKey 列表）
onChange: 值变化回调

selectFieldDescApi - 字段描述选择（下拉单选/多选）

在已配置实体的前提下，通过下拉选择字段，支持单选或多选；选中结果以「字段描述」对象数组存储（含 label、value/apiKey）。须与同表单内的实体配置联动。

功能特性：

下拉选择：以 Select 形式展示，支持搜索、清空
单选/多选：通过 mode 控制，可选 'multiple' 或 'tags'
数据存储：选中的值存储为 Array<{ label: string; value: string }>，其中 value 为字段 apiKey
联动数据源：通过 xObjectApiKey 指定从 props.data 中读取实体 key 的路径，实体变化时会重新加载字段列表

使用方法：

在组件模型文件（model.ts）/ 属性配置（propsSchema）中添加使用，需与提供 xObjectApiKey 的配置项关联使用：

json

{
  "type": "selectFieldDescApi",
  "name": "selectFieldDesc",
  "label": "绑定字段",
  "xObjectApiKey": "entityApiKey.xObjectApiKey",
  "mode": "tags",
  "placeholder": "请至少选择一个要显示的字段"
}

属性说明：

name: 字段名称
label: 标签文本
disabled: 是否禁用
placeholder: 占位文案
xObjectApiKey: 从 props.data 中获取实体 API Key 的 key 名或路径，不传则默认为 'xObjectApiKey'，如 'entityApiKey.xObjectApiKey'
mode: 可选 'multiple'（多选）或 'tags'（多选标签形式），不传为单选
value: 当前值，格式为 Array<{ label: string; value: string }>
onChange: 值变化回调

dataViewIdSelect - 实体视图选择

在组件模型文件（model.ts）/ 属性配置（propsSchema）中添加使用，用于选择指定实体下的列表视图（viewId），需与提供 xObjectApiKey 的配置项关联使用。

功能特性：

单选视图：下拉展示当前实体可用视图
接口加载：根据 xObjectApiKey 请求视图列表（如 /rest/data/v2.0/layouts/listLayout）
搜索与清空：支持搜索视图名、清空选择
数据存储：value 为视图 ID 字符串（viewId）
无实体提示：未配置实体时禁用并提示先配置数据源

使用方法：

jsonc

{
  "type": "dataViewIdSelect",
  "name": "defaultViewId",
  "label": "列表视图",
  "xObjectApiKey": "objectApiKey", // 用于关联当前属性配置中的实体数据来源（关联哪个实体对象）
  "placeholder": "请选择列表视图"
}

其中 xObjectApiKey 为从 props.data 读取实体 API Key 的字段名或路径，用于确定查询哪个实体的视图列表。

属性说明：

name: 字段名称
label: 标签文本
disabled: 是否禁用
placeholder: 占位文案，默认可为「请选择视图」
xObjectApiKey: 从 props.data 取实体 API Key 的字段名或路径，默认 xObjectApiKey
value: 字符串，所选 viewId
onChange: 值变化回调

customApi - Neo 平台自定义 API 绑定配置项

返回的数值类型：对象数值格式，各字段说明如下：

字段	类型	说明
`apiUrl`	`string`	所选自定义 API 的地址（与平台列表项中的 `URL` 一致）
`methodType`	`string`	请求方式，小写：`get` \| `post` \| `put` \| `patch` \| `delete`
`headers`	`Record<string, string>`	可选。请求头键值对
`data`	`Record<string, any>`	可选。请求参数；值可为解析后的 JSON 或原始字符串（见下文保存规则）

空对象 {} 或未配置时，组件侧可按「未选择 API」处理。

交互方式：在配置面板中默认展示 只读摘要 + 设置按钮；点击设置 icon 后在弹窗中可选择平台已注册的自定义 OpenAPI，并可配置 请求头 与 请求参数（Data）。

说明：列表数据来自 neo-open-api 的 customApi.getList({ pageNo: 1, pageSize: 10000 })。

功能特性：

API 下拉：选项展示为 methodName + methodType，选中后写入 apiUrl 与 methodType（请求方式随所选接口自动回填，不支持手动编辑）
请求头：多组 Key / Value；确定时合并为 headers 对象；Key 必填
请求参数 (Data)：多组 Key / Value；Value 若为合法 JSON 字符串则 JSON.parse 后存入，否则存原始字符串
空对象裁剪：headers / data 若最终无键值，会从保存结果中删除该字段

使用方法：

在组件模型文件（model.ts）/ 属性配置（propsSchema）中添加使用，用于添加一个可获取平台自定义 API 数据的配置项：

json

{
  "type": "customApi",
  "name": "fetchConfig",
  "label": "自定义接口",
  "description": "请选择已注册的 OpenAPI；Data 中 Value 可填 JSON。"
}

属性说明：

name：字段名，必填；对应模型中的属性名
label：标签文案；同时作为弹窗标题的默认值
description：可选；显示在「请求参数 (Data)」区域下方的说明文字
placeholder：预留（主输入框为只读展示，具体以产品为准）
value：当前值，结构见上文「适用属性数值类型」
onChange：弹窗确定时回传完整对象
visibleOn / hiddenOn：与其他字段联动显示

在属性配置面板中获取的数值格式如下：

json

{
    "apiUrl": "/rest/data/v2.0/scripts/api/proxy/forward",
    "methodType": "post",
    "data": {
        "url": "'https://jsonplaceholder.typicode.com/posts",
        "method": "GET",
        "data": "{ test: 123}"
    }
}

以上数据可在自定义组件 this.props.fetchConfig 获取，可通过 customApi.run 获取对应的外部接口数据。使用方式如下：

// @ts-ignore
import { customApi } from 'neo-open-api';

const { fetchConfig } = this.props;
const result = await customApi.run(fetchConfig); // 获取平台自定义 API 返回的数据

三、如何开发一个自定义配置项？

如当前 表单类、数据源类 配置项无法满足自定义组件的特殊属性配置交互（例如：特殊的数值格式、特殊的取值交互方式等），支持在自定义组件工程中 开发自定义配置项，并通过 amis 的 FormItem 注册为新的配置项类型 type，再在组件模型文件（model.ts）的属性配置（propsSchema）中添加使用。

整体流程：开发自定义配置项组件 → 使用 @FormItem 注册并导出 → 在组件模型文件中 import 此自定义配置项组件，并在 propsSchema 中添加这个新增的配置项类型。

步骤一：开发自定义配置项组件

在 自定义组件项目（非 src/components 直接子目录，避免识别成自定义组件）中开发自定义配置项组件：

展示只读摘要或占位输入，以及打开弹窗、抽屉等复杂编辑区；
在确认保存时，将结构化结果通过 onChange 写回表单；
需要读取页面/表单上下文时，可通过 RendererProps（如 data、disabled）获取。

完整可参考示例工程中的实现（弹窗 + JSON Schema 编辑器）：

targetNumber__c/customStyleConfig/index.tsx（GitHub）

示例中 propsSchema 里传入的 viewStyle、wideScreen 等字段，会作为普通 props 进入该组件，可按需扩展。

步骤二：使用 FormItem 注册为 amis 表单项并导出

使用 amis 提供的 FormItem 装饰器（或等价 API）将组件注册为表单项，type 字段必须与后续 propsSchema 中的 type 完全一致。

tsx

// @ts-ignore
import { FormItem, RendererProps } from 'amis';
import React from 'react';
import { Input, Button, Modal, message } from 'antd';
import { SettingOutlined } from '@ant-design/icons';
// @ts-ignore
import JSONEditor from '@wibetter/json-editor';
import '@wibetter/json-editor/lib/index.css';

import { configSchema } from './configSchema';
import './index.scss';

interface ICustomStyleConfigProps {
  onChange?: (value: unknown) => void;
  value?: unknown;
  name: string;
  /** 可由 propsSchema 传入的扩展配置 */
  viewStyle?: string;
  wideScreen?: boolean;
}

interface ICustomStyleConfigState {
  isModalVisible: boolean;
  editorValue: unknown;
}

@FormItem({
  type: 'customStyleConfig',
  /** 当列出的 props 变化时需要重渲染时在此声明，例如依赖表单 data */
  detectProps: ['data'],
})
export default class CustomStyleConfigRenderer extends React.Component<
  RendererProps & ICustomStyleConfigProps,
  ICustomStyleConfigState
> {
  constructor(props: RendererProps & ICustomStyleConfigProps) {
    super(props);
    this.state = {
      isModalVisible: false,
      editorValue: props.value ?? {},
    };
    this.showModal = this.showModal.bind(this);
    this.handleModalOk = this.handleModalOk.bind(this);
    this.handleModalCancel = this.handleModalCancel.bind(this);
    this.handleEditorChange = this.handleEditorChange.bind(this);
    this.getDisplayValue = this.getDisplayValue.bind(this);
  }

  handleEditorChange(value: unknown) {
    this.setState({ editorValue: value });
  }

  handleModalOk() {
    const { editorValue } = this.state;
    const { onChange } = this.props;
    try {
      onChange?.(editorValue);
      this.setState({ isModalVisible: false });
    } catch {
      message.error('保存配置失败');
    }
  }

  handleModalCancel() {
    const value = this.props.value ?? {};
    this.setState({ isModalVisible: false, editorValue: value });
  }

  showModal() {
    const value = this.props.value ?? {};
    this.setState({ isModalVisible: true, editorValue: value });
  }

  getDisplayValue() {
    const { value } = this.props;
    if (!value || typeof value !== 'object' || Object.keys(value as object).length === 0) {
      return '';
    }
    return '已配置自定义样式';
  }

  render() {
    const { disabled, viewStyle, wideScreen, value } = this.props;
    const { isModalVisible } = this.state;

    return (
      <div className="properties-panel-custom-style-config">
        <div className="custom-style-config-input-container">
          <Input
            value={this.getDisplayValue()}
            placeholder="请配置自定义样式"
            disabled={disabled}
            readOnly
            className="custom-style-config-input"
          />
          <Button
            type="text"
            icon={<SettingOutlined />}
            onClick={this.showModal}
            disabled={disabled}
            className="custom-style-config-setting-btn"
          />
        </div>
        <Modal
          title="自定义样式配置"
          visible={isModalVisible}
          onOk={this.handleModalOk}
          onCancel={this.handleModalCancel}
          width={800}
          centered
          okText="确定"
          cancelText="取消"
          destroyOnClose={false}
        >
          <div className="custom-style-config-modal-content">
            {isModalVisible && (
              <JSONEditor
                schemaData={configSchema}
                jsonData={value}
                onChange={this.handleEditorChange}
                viewStyle={viewStyle || 'tabs'}
                tabPosition="left"
                wideScreen={wideScreen ?? false}
              />
            )}
          </div>
        </Modal>
      </div>
    );
  }
}

与属性面板的约定

约定	说明
当前值	通过 `this.props.value` 读取（与 `defaultComProps` 中同名字段的初始值对应）。
写回表单	用户确认配置后调用 `this.props.onChange(newValue)`，否则设计器无法持久化。
`detectProps`	若渲染依赖 `data` 等上下文字段变化，需在 `@FormItem` 中声明，否则可能不会更新。
标签与布局	`label`、`description`、校验提示、表单项布局等由 amis 表单统一处理，无需在自定义组件内重复实现。

更多扩展方式见 amis 官方文档：自定义 React — 表单项扩展。

步骤三：在组件模型文件 / 属性配置（propsSchema）中添加使用

引入注册侧产物：确保包含 @FormItem 注册的模块被执行一次（通常通过 import '.../customStyleConfig' 或包导出的 side-effect 入口），样式文件按需单独引入。
propsSchema 中声明：type 与 @FormItem 的 type 相同，name 与 defaultComProps 中的属性键一致，保证画布默认值与面板编辑的是同一字段。

// 侧效 import：注册 amis 表单项（路径以实际构建产物为准）
import 'neo-bi-cmps/lib/customStyleConfig';
import 'neo-bi-cmps/lib/customStyleConfig.css';

export class TargetNumberModel {
  isAmisCmp: boolean = true;
  label: string = '数值指标';
  description: string =
    '用于展示关键数值指标，支持从 XObject 实体对象获取动态数据，支持绑定多个字段进行展示';
  tags: string[] = ['业务组件'];
  iconUrl: string = 'https://custom-widgets.bj.bcebos.com/TargetNumber.svg';
  targetPage: string[] = ['all'];
  targetDevice: string = 'all';

  defaultComProps = {
    entityApiKey: '',
    targetNumberStyle: {
      baseStyle: {
        backgroundColor: '#ffffff',
        paddingMargin: { margin: '0', padding: '0' },
      },
      layoutStyle: { alignClass: 'flex-col' },
      titleStyle: {
        show: false,
        text: '',
        fontSize: 24,
        fontWeight: 400,
        color: '#000',
      },
      numberStyle: {
        fontSize: 32,
        fontWeight: 600,
        color: '#262626',
      },
      numberTitleStyle: {
        fontSize: 14,
        fontWeight: 400,
        color: '#8c8c8c',
      },
    },
  };

  functions = [
    {
      apiKey: 'loadData',
      label: '刷新数据',
      helpTextKey: '重新加载数值指标数据',
    },
  ];

  propsSchema = [
    {
      type: 'xObjectDetailApi',
      name: 'entityApiKey',
      label: '绑定实体业务数据',
      placeholder: '绑定实体业务数据源',
      disabledFieldSelect: true,
      disabledAutoFetchData: true,
    },
    {
      type: 'selectFieldDescApi',
      name: 'selectFieldDesc',
      xObjectApiKey: 'entityApiKey.xObjectApiKey',
      mode: 'tags',
      label: '绑定字段',
      placeholder: '请至少选择一个要显示的字段',
    },
    {
      type: 'customStyleConfig',
      name: 'targetNumberStyle',
      label: '自定义样式配置',
      viewStyle: 'tabs',
      wideScreen: false,
    },
  ];
}

export default TargetNumberModel;

说明

import 的入口路径需与项目打包配置一致（示例为 neo-bi-cmps 发布包路径；单体仓库可为相对路径指向注册文件）。
自定义 type 名称在全局需唯一，避免与平台或其他组件重复。
若业务使用 antd 5+，Modal 等组件 API 可能与 antd 4（如 visible 与 open）不同，需按实际版本调整。

可用属性配置项 ​

支持两类配置项 ​

一、表单类配置项 ​

panelInput - 文本输入配置项 ​

panelSelect - 下拉选择配置项 ​

panelSwitch - 开关配置项 ​

panelNumber - 数字输入配置项 ​

panelColor - 颜色选择器配置项 ​

neoCascader - 级联选择配置项 ​

neoRadio - 单选配置项 ​

neoCheckbox - 多选框 ​

neoDatePicker - 日期选择框 ​

neoTimePicker - 时间选择框 ​

neoRate - 评分 ​

neoSlider - 滑动输入条 ​

neoTransfer - 穿梭框 ​

neoTreeSelect - 树选择 ​

neoUpload - 上传 ​

二、平台数据源相关配置项 ​

xObjectEntityList - 实体列表数据源 ​

xObjectDataApi - 实体业务数据列表数据源 ​

xObjectDetailApi - 实体详情数据源 ​

selectFieldsApi - 字段 apiKey 多选（穿梭框） ​

selectFieldDescApi - 字段描述选择（下拉单选/多选） ​

dataViewIdSelect - 实体视图选择 ​

customApi - Neo 平台自定义 API 绑定配置项 ​

三、如何开发一个自定义配置项？ ​

步骤一：开发自定义配置项组件 ​

步骤二：使用 FormItem 注册为 amis 表单项并导出 ​

步骤三：在组件模型文件 / 属性配置（propsSchema）中添加使用 ​

可用属性配置项

支持两类配置项

一、表单类配置项

panelInput - 文本输入配置项

panelSelect - 下拉选择配置项

panelSwitch - 开关配置项

panelNumber - 数字输入配置项

panelColor - 颜色选择器配置项

neoCascader - 级联选择配置项

neoRadio - 单选配置项

neoCheckbox - 多选框

neoDatePicker - 日期选择框

neoTimePicker - 时间选择框

neoRate - 评分

neoSlider - 滑动输入条

neoTransfer - 穿梭框

neoTreeSelect - 树选择

neoUpload - 上传

二、平台数据源相关配置项

xObjectEntityList - 实体列表数据源

xObjectDataApi - 实体业务数据列表数据源

xObjectDetailApi - 实体详情数据源

selectFieldsApi - 字段 apiKey 多选（穿梭框）

selectFieldDescApi - 字段描述选择（下拉单选/多选）

dataViewIdSelect - 实体视图选择

customApi - Neo 平台自定义 API 绑定配置项

三、如何开发一个自定义配置项？

步骤一：开发自定义配置项组件

步骤二：使用 FormItem 注册为 amis 表单项并导出

步骤三：在组件模型文件 / 属性配置（propsSchema）中添加使用