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

446 lines
11 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 选择类控件
## 目录
- [下拉选择 (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)