446 lines
11 KiB
Markdown
446 lines
11 KiB
Markdown
# 选择类控件
|
||
|
||
## 目录
|
||
|
||
- [下拉选择 (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)
|