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

450 lines
11 KiB
Markdown
Raw Permalink 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.
# 特殊控件
## 目录
- [开关 (switch)](#开关-switch)
- [评分 (rate)](#评分-rate)
- [颜色选择 (colorPicker)](#颜色选择-colorpicker)
- [签章 (sign)](#签章-sign)
- [二维码 (qrcode)](#二维码-qrcode)
- [分隔线 (divider)](#分隔线-divider)
- [分组标题 (groupTitle)](#分组标题-grouptitle)
- [页签 (tab)](#页签-tab)
- [轮播 (carousel)](#轮播-carousel)
- [单据规则 (billRule)](#单据规则-billrule)
- [计算 (calculate)](#计算-calculate)
- [自动完成 (autoComplete)](#自动完成-autocomplete)
---
## 开关 (switch)
### 基本信息
| 属性 | 值 |
|------|-----|
| jnpfKey | `switch` |
| AIBridge builder | `build_field_model(..., jnpf_key="switch")` |
### 基本规则
| 配置 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| activeValue | any | true | 开启时的值 |
| inactiveValue | any | false | 关闭时的值 |
### AIBridge 使用
```python
field = build_field_model(
field_name="是否启用",
field_vmodel="f_enabled",
jnpf_key="switch"
)
# 自定义值
field = build_field_model(
field_name="接收通知",
field_vmodel="f_receive_notification",
jnpf_key="switch",
activeValue="1",
inactiveValue="0"
)
```
---
## 评分 (rate)
### 基本信息
| 属性 | 值 |
|------|-----|
| jnpfKey | `rate` |
| AIBridge builder | `build_field_model(..., jnpf_key="rate")` |
### 基本规则
| 配置 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| max | int | 5 | 最大分值 |
| allowHalf | bool | false | 是否允许半星 |
| showText | bool | false | 是否显示文字 |
### AIBridge 使用
```python
field = build_field_model(
field_name="满意度评分",
field_vmodel="f_satisfaction",
jnpf_key="rate",
max=5,
allowHalf=True
)
# 显示文字
field = build_field_model(
field_name="等级评定",
field_vmodel="f_level",
jnpf_key="rate",
max=3,
showText=True
)
```
---
## 颜色选择 (colorPicker)
### 基本信息
| 属性 | 值 |
|------|-----|
| jnpfKey | `colorPicker` |
| AIBridge builder | `build_field_model(..., jnpf_key="colorPicker")` |
### AIBridge 使用
```python
field = build_field_model(
field_name="主题颜色",
field_vmodel="f_theme_color",
jnpf_key="colorPicker"
)
```
---
## 签章 (sign)
### 基本信息
| 属性 | 值 |
|------|-----|
| jnpfKey | `sign` |
| AIBridge builder | 无封装 |
| workSystem 示例 | 套打示例 (#24) |
### 基本规则
签章控件用于电子签章/盖章,**通常需配合流程使用**。
### workSystem 示例
| 表单名称 | 表单ID | 说明 |
|----------|--------|------|
| 套打示例 | 585384793399624261 | billRule + sign, 单据签章 |
---
## 二维码 (qrcode)
### 基本信息
| 属性 | 值 |
|------|-----|
| jnpfKey | `qrcode` |
| AIBridge builder | 无封装 |
| workSystem 示例 | 二维码、条形码多组件值联动展示 (#3) |
### 基本规则
二维码控件用于生成和扫描二维码。
### workSystem 示例
| 表单名称 | 表单ID | 说明 |
|----------|--------|------|
| 二维码、条形码多组件值联动展示 | 797444600007492165 | qrcode + inputNumber 联动 |
### 源码位置
```
jnpf/移动端/jnpf-app-vue3/components/Jnpf/Qrcode/index.vue
jnpf/移动端/jnpf-app-vue3/components/Jnpf/Barcode/index.vue
```
---
## 分隔线 (divider)
### 基本信息
| 属性 | 值 |
|------|-----|
| jnpfKey | `divider` |
| AIBridge builder | 无封装 |
| workSystem 示例 | 入职申请、物资申请、套打示例 等 |
### workSystem 示例
| 表单名称 | 表单ID | 说明 |
|----------|--------|------|
| 入职申请 | 624163990351643525 | 表单分区 |
| 物资申请 | 585436888639210245 | 类型分隔 |
| 套打示例 | 585384793399624261 | 区域分隔 |
### 手动配置示例
```json
{
"__config__": {
"jnpfKey": "divider",
"label": "基本信息"
},
"orientation": "left",
"contentPosition": "left"
}
```
---
## 分组标题 (groupTitle)
### 基本信息
| 属性 | 值 |
|------|-----|
| jnpfKey | `groupTitle` |
| AIBridge builder | 无封装 |
| workSystem 示例 | 离职交接表、预算管理、出差管理、事件管理 等 |
### workSystem 示例
| 表单名称 | 表单ID | 说明 |
|----------|--------|------|
| 离职交接表 | 623417538411233285 | 分组显示 |
| 预算管理 | 469100392253286789 | 预算信息分组 |
| 出差管理 | 469066996185622917 | 出差信息分组 |
| 事件管理 | 469065268790880645 | 事件信息分组 |
| 设备巡检管理 | 469062048563652997 | 巡检信息分组 |
| 产品管理 | 469039386000943493 | 产品信息分组 |
| 核酸检测 | 469038006062344581 | 检测信息分组 |
| 药房管理 | 468849844170057541 | 药房信息分组 |
| 报名管理外链 | 468848215723140933 | 报名信息分组 |
| 用车管理 | 469040281883306373 | 用车信息分组 |
| 人才管理 | 469047177461688709 | 人才信息分组 |
### 手动配置示例
```json
{
"__config__": {
"jnpfKey": "groupTitle",
"label": "基本信息"
},
"showBorder": true
}
```
---
## 页签 (tab)
### 基本信息
| 属性 | 值 |
|------|-----|
| jnpfKey | `tab` |
| AIBridge builder | 无封装 |
| workSystem 示例 | 高级控件和默认查询 (#34)、订单示例 (#43) |
### workSystem 示例
| 表单名称 | 表单ID | 说明 |
|----------|--------|------|
| 高级控件和默认查询 | 469499301635095045 | tab + table |
| 订单示例 | 469133201755925637 | tab 切换明细 |
---
## 轮播 (carousel)
### 基本信息
| 属性 | 值 |
|------|-----|
| jnpfKey | `carousel` |
| AIBridge builder | 无封装 |
| workSystem 示例 | 表单规则 (#7) |
### workSystem 示例
| 表单名称 | 表单ID | 说明 |
|----------|--------|------|
| 表单规则 | 797378890455581253 | carousel + input + inputNumber + select |
---
## 单据规则 (billRule)
### 基本信息
| 属性 | 值 |
|------|-----|
| jnpfKey | `billRule` |
| AIBridge builder | 无封装 |
| workSystem 示例 | 套打示例、采购合同、订单示例、产品管理 等 |
### 基本规则
单据规则用于自动生成单据编号,通常是只读字段。
### workSystem 示例
| 表单名称 | 表单ID | 说明 |
|----------|--------|------|
| 套打示例 | 585384793399624261 | 单据编号 |
| 采购合同 | 585077579715707205 | 合同编号 |
| 订单示例 | 469133201755925637 | 订单编号 |
| 采购管理 | 469106304141552773 | 采购单号 |
| 客户管理 | 469102214628043141 | 客户编号 |
| 产品管理 | 469039386000943493 | 产品编码 |
| 核酸检测 | 469038006062344581 | 检测编号 |
| 药房管理 | 468849844170057541 | 药方编号 |
| 应收费用 | 468826463014018501 | 应收单号 |
| 用车管理 | 469040281883306373 | 用车单号 |
---
## 计算 (calculate)
### 基本信息
| 属性 | 值 |
|------|-----|
| jnpfKey | `calculate` |
| AIBridge builder | 无封装 |
| workSystem 示例 | 水电费用 (#25)、采购合同 (#28) |
### workSystem 示例
| 表单名称 | 表单ID | 说明 |
|----------|--------|------|
| 水电费用 | 585110234985398597 | calculate + table, 自动计算费用 |
| 采购合同 | 585077579715707205 | calculate, 金额汇总计算 |
---
## 自动完成 (autoComplete)
### 基本信息
| 属性 | 值 |
|------|-----|
| jnpfKey | `autoComplete` |
| AIBridge builder | 无封装 |
| workSystem 示例 | 数据接口调用字段示例 (#33) |
### workSystem 示例
| 表单名称 | 表单ID | 说明 |
|----------|--------|------|
| 数据接口调用字段示例 | 469500336084679173 | autoComplete + select + cascader + popupSelect |
---
## 系统自动填充控件
| 控件 | jnpfKey | 说明 | workSystem 示例 |
|------|---------|------|-----------------|
| 创建用户 | createUser | 自动填充当前用户 | #43, #46, #47, #49 |
| 创建时间 | createTime | 自动填充创建时间 | #46, #47, #49, #55 |
| 修改时间 | modifyTime | 自动填充修改时间 | #49, #55 |
| 当前组织 | currOrganize | 自动填充当前组织 | #47, #51 |
| 区域选择 | areaSelect | 省市区选择 | #52, #59 |
---
## 数据存储规律
### 特殊控件存储规律
| 控件 | jnpfKey | 存储类型 | 存储格式示例 | 说明 |
|------|---------|---------|------------|------|
| 开关 | `switch` | **字符串** | `"1"` / `"0"` | activeValue/inactiveValue 转字符串存储,数据库类型 varchar(255) |
| 评分 | `rate` | **decimal(38,1)** | `4.0` | 存储为 decimal(38,1),如 4.0 表示4星 |
| 滑块 | `slider` | **decimal(38,15)** | `50.000000000000000` | 高精度 decimal 存储,非整数 |
| 颜色选择 | `colorPicker` | **字符串** | `"#1890ff"` | 十六进制颜色值 |
| 签章 | `sign` | **字符串** | `"/files/sign/xxx.png"` | 签章图片路径 |
| 二维码 | `qrcode` | **字符串** | `"http://xxx"` | 二维码内容 |
| 条形码 | `barcode` | **字符串** | `"123456789"` | 条形码内容 |
| 单据规则 | `billRule` | **字符串** | `"BJ20260407001"` | 自动生成的编号 |
| 计算 | `calculate` | **数值** | `1234.56` | 计算结果值 |
### 开关控件详解
开关的存储值由 `activeValue` 和 `inactiveValue` 决定:
| 配置 | activeValue | inactiveValue | 开启存储 | 关闭存储 |
|------|------------|---------------|---------|---------|
| 默认 | `true` | `false` | `1` | `0` |
| 数值型 | `"1"` | `"0"` | `"1"` | `"0"` |
| 布尔型 | `"true"` | `"false"` | `"true"` | `"false"` |
### AIBridge 配置示例
```python
# 默认开关(存储 1/0)
field = build_field_model(
field_name="是否启用",
field_vmodel="f_enabled",
jnpf_key="switch"
)
# 自定义值
field = build_field_model(
field_name="接收通知",
field_vmodel="f_receive_notification",
jnpf_key="switch",
activeValue="1",
inactiveValue="0"
)
```
### 地址选择控件
| 控件 | jnpfKey | 存储类型 | 存储格式示例 |
|------|---------|---------|------------|
| 地址选择 | `address` | **纯文本字符串** | `"广东省东莞市万江区家达能大厦74B"` | 实际存储为纯地址文本,非 JSON 对象 |
### 存储验证示例
```python
# 开关(实际存储为字符串)
f_enabled: "1" # 开启,varchar(255) 存储
# 评分(实际存储为 decimal(38,1))
f_rating: Decimal('4.0') # 4星
# 滑块(实际存储为高精度 decimal(38,15))
f_opacity: Decimal('50.000000000000000') # 50%
# 颜色
f_color: "#1890ff"
# 地址(实际存储为纯文本,非 JSON 对象)
f_address: '广东省东莞市万江区家达能大厦74B'
```
### 数据库字段要求
| 控件 | 建议字段类型 |
|------|------------|
| switch | `varchar(255)` |
| rate | `decimal(38,1)` |
| slider | `decimal(38,15)` |
| colorPicker | `varchar(255)` |
| sign/qrcode/barcode | `varchar(500)` 或 `text` |
| billRule | `varchar(50)` |
| calculate | `decimal(18,2)` |
| address | `varchar(255)` |
---
## 下一步
- [图表控件](09-chart-controls.md)
- [表格高级模式](10-table-patterns.md)
- [表单高级模式](11-form-patterns.md)