Files
aibridge/docs/control/03-select-controls.md
T
2026-05-18 09:28:15 +08:00

11 KiB
Raw Blame History

选择类控件

目录


下拉选择 (select)

基本信息

属性 值
jnpfKey select / comSelect
AIBridge builder build_field_model(..., jnpf_key="select", options=[...])
源码示例 extend/formDemo/fieldForm2/index.vue
workSystem 示例 几乎所有业务表单

基本规则

关键:options 格式必须为 {fullName, id},不是 {label, value}

  1. 必填配置:

    • field_name: 字段中文名称
    • field_vmodel: 字段 vModel
    • jnpf_key: "select"
    • options: 选项列表
  2. 特有配置:

    • multiple: 是否多选 (默认 False)
    • options: 固定选项列表
    • dictionary_type: 数据字典类型 (平台数据字典)

AIBridge 使用

# 固定选项
field = build_field_model(
    field_name="客户状态",
    field_vmodel="f_customer_status",
    jnpf_key="select",
    required=True,
    options=[
        {"fullName": "潜在客户", "id": "1"},
        {"fullName": "正式客户", "id": "2"},
        {"fullName": "流失客户", "id": "3"},
    ]
)

# 多选模式
multi_field = build_field_model(
    field_name="擅长领域",
    field_vmodel="f_skill_areas",
    jnpf_key="select",
    multiple=True,
    options=[
        {"fullName": "前端开发", "id": "frontend"},
        {"fullName": "后端开发", "id": "backend"},
        {"fullName": "数据库", "id": "db"},
    ]
)

# 使用数据字典
dict_field = build_field_model(
    field_name="所属部门",
    field_vmodel="f_department",
    jnpf_key="select",
    dictionary_type="DepartmentType"  # 平台数据字典编码
)

workSystem 示例

表单名称 表单ID 配置
油耗计算 797460178185224773 计算类型选择
列表标签面板 585825534638818437 标签类型
采购申请 585441013829468933 采购类型
行政区划联动 469139004097359749 行政区划

常见错误

错误现象 原因 解决
下拉选项不显示 options 格式错误 必须使用 {fullName, id},不是 {label, value}
多选保存失败 multiple 未设置 multiple=True
数据字典选项为空 dictionary_type 不存在 检查数据字典编码是否正确

单选组 (radio)

基本信息

属性 值
jnpfKey radio
AIBridge builder build_field_model(..., jnpf_key="radio", options=[...])
源码示例 extend/formDemo/fieldForm2/index.vue
workSystem 示例 离职申请、物资申请、隔离管控 等

基本规则

  1. 必填配置:同 select
  2. 特有配置:无 multiple,其他同 select

AIBridge 使用

field = build_field_model(
    field_name="性别",
    field_vmodel="f_gender",
    jnpf_key="radio",
    required=True,
    options=[
        {"fullName": "男", "id": "1"},
        {"fullName": "女", "id": "2"},
    ]
)

workSystem 示例

表单名称 表单ID 选项内容
离职申请 623163301152424133 离职类型
物资申请 585436888639210245 物资类型
隔离管控 469050754464803205 管控类型
人才管理 469047177461688709 人才类型

多选组 (checkbox)

基本信息

属性 值
jnpfKey checkbox
AIBridge builder build_field_model(..., jnpf_key="checkbox", options=[...])
workSystem 示例 数据接口调用字段示例 (#33)

基本规则

同 select,但允许多选。

AIBridge 使用

field = build_field_model(
    field_name="权限范围",
    field_vmodel="f_permission_scope",
    jnpf_key="checkbox",
    options=[
        {"fullName": "读取", "id": "read"},
        {"fullName": "写入", "id": "write"},
        {"fullName": "删除", "id": "delete"},
        {"fullName": "导出", "id": "export"},
    ]
)

workSystem 示例

表单名称 表单ID 说明
数据接口字段示例 469500336084679173 checkbox 多选

级联选择 (cascader)

基本信息

属性 值
jnpfKey cascader
AIBridge builder build_field_model(..., jnpf_key="cascader", options=[...])
workSystem 示例 数据接口调用字段示例 (#33)

基本规则

  1. options 结构:必须包含 children 字段形成层级
  2. 数据格式:
[
  {
    "fullName": "浙江省",
    "id": "330000",
    "children": [
      {"fullName": "杭州市", "id": "330100", "children": [...]}
    ]
  }
]

AIBridge 使用

field = build_field_model(
    field_name="所在区域",
    field_vmodel="f_region",
    jnpf_key="cascader",
    options=[
        {"fullName": "浙江省", "id": "330000", "children": [
            {"fullName": "杭州市", "id": "330100"},
            {"fullName": "宁波市", "id": "330200"}
        ]},
        {"fullName": "江苏省", "id": "320000", "children": [
            {"fullName": "南京市", "id": "320100"}
        ]}
    ]
)

workSystem 示例

表单名称 表单ID 说明
数据接口调用字段示例 469500336084679173 cascader 级联选择

树形选择 (treeSelect)

基本信息

属性 值
jnpfKey treeSelect
AIBridge builder build_field_model(..., jnpf_key="treeSelect", options=[...])
workSystem 示例 数据接口调用字段示例、列表树形表格 等

基本规则

同 cascader,但显示为树形下拉样式。

AIBridge 使用

field = build_field_model(
    field_name="组织架构",
    field_vmodel="f_organization",
    jnpf_key="treeSelect",
    options=[
        {"fullName": "总公司", "id": "1", "children": [
            {"fullName": "研发部", "id": "1-1"},
            {"fullName": "销售部", "id": "1-2"}
        ]}
    ]
)

workSystem 示例

表单名称 表单ID 说明
数据接口调用字段示例 469500336084679173 treeSelect
列表树形表格 469136286624574597 分类树形选择

组织选择 (organizeSelect)

基本信息

属性 值
jnpfKey organizeSelect
AIBridge builder 无封装,需手动配置
workSystem 示例 几乎所有人员管理表单

基本规则

组织选择控件用于选择部门/组织,AIBridge 无封装,需要手动配置。

workSystem 示例

表单名称 表单ID 说明
员工培训 624164673918337925 培训机构选择
入职申请 624163990351643525 部门选择
离职交接表 623417538411233285 归属部门
列表行内编辑 585824111083652229 组织选择
采购申请 585441013829468933 采购部门
列表左侧树 585806182086608005 组织树
预算管理 469100392253286789 预算部门
大客户信息 468842471892247429 所属组织

手动配置示例

{
  "__config__": {
    "jnpfKey": "organizeSelect",
    "label": "所属部门",
    "tag": "JnpfOrganizeSelect"
  },
  "placeholder": "请选择部门",
  "multiple": false,
  "clearable": true
}

用户选择 (userSelect)

基本信息

属性 值
jnpfKey userSelect
AIBridge builder 无封装,需手动配置
workSystem 示例 几乎所有审批/人员表单

基本规则

用户选择控件用于选择系统用户,AIBridge 无封装。

workSystem 示例

表单名称 表单ID 说明
员工培训 624164673918337925 培训人选择
入职申请 624163990351643525 申请人
离职交接表 623417538411233285 离职人
离职员工表 623183958128984261 员工选择
员工信息 623163913990570181 信息录入
离职申请 623163301152424133 申请人
列表行内编辑 585824111083652229 负责人
采购申请 585441013829468933 申请人
物资申请 585436888639210245 申请人
付款申请 585398402720727621 付款人
订单示例 469133201755925637 创建人
采购管理 469106304141552773 采购人
出差管理 469066996185622917 出差人
设备巡检管理 469062048563652997 巡检人
OKR管理 469059874144184709 负责人
用车管理 469040281883306373 用车人

手动配置示例

{
  "__config__": {
    "jnpfKey": "userSelect",
    "label": "申请人",
    "tag": "JnpfUserSelect"
  },
  "placeholder": "请选择申请人",
  "multiple": false,
  "clearable": true
}

选择类控件对比

控件 多选 层级支持 AIBridge 典型用途
select 支持 否 支持 简单下拉
radio 否 否 支持 二选一/有限选项
checkbox 自动多选 否 支持 多选权限/类别
cascader 否 是 支持 省市县/分类层级
treeSelect 支持 是 支持 组织架构/分类树
organizeSelect 支持 是 无封装 部门选择
userSelect 支持 否 无封装 用户选择


数据存储规律

选择类控件存储规律

控件 jnpfKey 存储类型 存储格式示例
下拉选择(单选) select 字符串 "2"
下拉选择(多选) select (multiple=true) JSON数组字符串 ["1","3","5"]
单选组 radio 字符串 "1"
多选组 checkbox JSON数组字符串 ["1","3"]
级联选择 cascader JSON数组字符串 ["44","4403","440305"]
树形选择 treeSelect 字符串 "1-1" 或 "1-1-2"
组织选择 organizeSelect 字符串 "组织id"
用户选择 userSelect 字符串 "用户id" 或 "admin"

重要:选项格式

AIBridge 必须使用 {fullName, id} 格式,不是 {label, value}

# 正确格式
options = [
    {"fullName": "潜在客户", "id": "1"},
    {"fullName": "正式客户", "id": "2"},
]

# 错误格式(会导致选项不显示)
options = [
    {"label": "潜在客户", "value": "1"},  # 错!
    {"label": "正式客户", "value": "2"},  # 错!
]

存储验证示例

# 通过 AIBridge 查询数据库结果:

# 单选 - 存储的是 id
f_gender: "1"  # 存储选项的 id 值

# 多选 - 存储的是 JSON 数组
f_hobbies: '["1","3"]'  # 存储选项 id 的 JSON 数组

# 级联 - 存储的是完整路径数组
f_region: '["44","4403","440305"]'  # 省-市-区的 id 数组

数据库字段要求

控件 建议字段类型
select/radio varchar(50)
checkbox/cascader varchar(500) 或 text
treeSelect varchar(100)
userSelect/organizeSelect varchar(50)

下一步