# 选择类控件 ## 目录 - [下拉选择 (select)](#下拉选择-select) - [单选组 (radio)](#单选组-radio) - [多选组 (checkbox)](#多选组-checkbox) - [级联选择 (cascader)](#级联选择-cascader) - [树形选择 (treeSelect)](#树形选择-treeselect) - [组织选择 (organizeSelect)](#组织选择-organizeselect) - [用户选择 (userSelect)](#用户选择-userselect) --- ## 下拉选择 (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 使用 ```python # 固定选项 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 使用 ```python 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 使用 ```python 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. **数据格式**: ```json [ { "fullName": "浙江省", "id": "330000", "children": [ {"fullName": "杭州市", "id": "330100", "children": [...]} ] } ] ``` ### AIBridge 使用 ```python 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 使用 ```python 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 | 所属组织 | ### 手动配置示例 ```json { "__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 | 用车人 | ### 手动配置示例 ```json { "__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}`** ```python # 正确格式 options = [ {"fullName": "潜在客户", "id": "1"}, {"fullName": "正式客户", "id": "2"}, ] # 错误格式(会导致选项不显示) options = [ {"label": "潜在客户", "value": "1"}, # 错! {"label": "正式客户", "value": "2"}, # 错! ] ``` ### 存储验证示例 ```python # 通过 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)` | --- ## 下一步 - [日期时间控件](04-date-controls.md) - [上传控件](05-upload-controls.md) - [弹窗控件](06-popup-controls.md)