Files
2026-05-18 09:28:15 +08:00

219 lines
10 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.
# JNPF 控件快速使用速查
## 目录结构
本文档集包含以下内容:
| 文档 | 说明 |
|------|------|
| 01-quick-ref.md | 本文档,控件快速使用速查 |
| 02-input-controls.md | 输入类控件 |
| 03-select-controls.md | 选择类控件 |
| 04-date-controls.md | 日期时间控件 |
| 05-upload-controls.md | 上传控件 |
| 06-popup-controls.md | 弹窗控件 |
| 07-table-controls.md | 子表格控件 |
| 08-special-controls.md | 特殊控件 |
| 09-chart-controls.md | 图表控件 |
| 10-table-patterns.md | 表格高级模式 |
| 11-form-patterns.md | 表单高级模式 |
| 13-mobile-controls.md | 移动端控件 |
| 12-examples/workSystem-examples.md | workSystem 示例索引 |
| 12-examples/extend-examples.md | extend 代码示例索引 |
---
## 控件速查表
### 输入类控件
| 控件 | jnpfKey | 关键配置 | 数据存储规律 | AIBridge builder |
|------|---------|----------|-------------|------------------|
| 单行文本 | `input` | placeholder, showPassword | **字符串直接存储** | `build_field_model(..., jnpf_key="input")` |
| 多行文本 | `textarea` | rows, maxlength | **字符串直接存储**(含换行) | `build_field_model(..., jnpf_key="textarea")` |
| 数字输入 | `inputNumber` | step, controls, min, max | **数值或字符串存储**(取决于 precision 配置) | `build_field_model(..., jnpf_key="inputNumber")` |
### 选择类控件
| 控件 | jnpfKey | 关键配置 | 数据存储规律 | AIBridge builder |
|------|---------|----------|-------------|------------------|
| 下拉选择 | `select` | multiple, options (格式: {fullName, id}) | **选项id字符串存储**(单选如"2",多选格式为JSON数组) | `build_field_model(..., jnpf_key="select", options=[...])` |
| 单选组 | `radio` | options | **选项id字符串存储**(如"1") | `build_field_model(..., jnpf_key="radio", options=[...])` |
| 多选组 | `checkbox` | options | **选项id数组JSON序列化存储**(如`["1","3"]`) | `build_field_model(..., jnpf_key="checkbox", options=[...])` |
| 级联选择 | `cascader` | options | **节点id数组JSON序列化存储**(如`["44","4403","440305"]`) | `build_field_model(..., jnpf_key="cascader", options=[...])` |
| 树形选择 | `treeSelect` | options | **节点id字符串存储**(如"1-1") | `build_field_model(..., jnpf_key="treeSelect", options=[...])` |
| 组织选择 | `organizeSelect` | - | **组织id字符串存储** | AIBridge 无封装,需手动配置 |
| 用户选择 | `userSelect` | - | **用户名字符串存储**(如"admin"),非用户ID | AIBridge 无封装,需手动配置 |
### 日期时间控件
| 控件 | jnpfKey | 关键配置 | 数据存储规律 | AIBridge builder |
|------|---------|----------|-------------|------------------|
| 日期选择 | `datePicker` | format: "yyyy-MM-dd" | **日期字符串存储**(如"2026-04-07")或时间戳 | `build_field_model(..., jnpf_key="datePicker")` |
| 时间选择 | `timePicker` | format: "HH:mm:ss" | **时间字符串存储**(如"14:30:00") | `build_field_model(..., jnpf_key="timePicker")` |
### 上传控件
| 控件 | jnpfKey | 关键配置 | 数据存储规律 | AIBridge builder |
|------|---------|----------|-------------|------------------|
| 图片上传 | `uploadImg` | multiple, maxCount | **文件路径字符串存储**:`"/upload/20260407/test.jpg"` | `build_field_model(..., jnpf_key="uploadImg")` |
| 文件上传 | `uploadFile` | multiple, maxCount | **文件路径字符串存储**:`"/upload/20260407/test.pdf"` | `build_field_model(..., jnpf_key="uploadFile")` |
### 弹窗控件
| 控件 | jnpfKey | 关键配置 | 数据存储规律 | AIBridge builder |
|------|---------|----------|-------------|------------------|
| 弹窗表格 | `popupTable` | modelId, relationField | **关联记录id字符串存储** | 需两阶段创建 |
| 弹窗选择 | `popupSelect` | - | **选中记录id** | workSystem #33 |
| 弹窗属性 | `popupAttr` | - | **JSON对象存储** | workSystem #33 |
| 关联表单 | `relationForm` | modelId, relationField | **关联记录id字符串存储** | 需两阶段创建 |
| 关联流程 | `relationFlow` | - | **流程实例id** | - |
### 特殊控件
| 控件 | jnpfKey | 关键配置 | 数据存储规律 | AIBridge builder |
|------|---------|----------|-------------|------------------|
| 开关 | `switch` | activeValue, inactiveValue | **字符串存储**(activeValue/inactiveValue 转字符串存储,如"1"/"0",数据库 varchar(255)) | `build_field_model(..., jnpf_key="switch")` |
| 评分 | `rate` | max, allowHalf | **decimal(38,1) 存储**(如 4.0 表示4星) | `build_field_model(..., jnpf_key="rate")` |
| 滑块 | `slider` | min, max, step | **decimal(38,15) 高精度存储** | `build_field_model(..., jnpf_key="slider")` |
| 颜色选择 | `colorPicker` | - | **颜色值字符串存储**(如"#1890ff") | `build_field_model(..., jnpf_key="colorPicker")` |
| 签章 | `sign` | - | **签章图片路径** | - |
### 布局控件
| 控件 | jnpfKey | 关键配置 | 数据存储规律 |
|------|---------|----------|-------------|
| 分隔线 | `divider` | - | 不存储数据 |
| 分组标题 | `groupTitle` | - | 不存储数据 |
| 轮播 | `carousel` | - | 不存储数据 |
| 页签 | `tab` | - | 不存储数据 |
| 二维码 | `qrcode` | - | **字符串存储**(二维码内容) |
| 条形码 | `barcode` | - | **字符串存储**(条形码内容) |
| 单据规则 | `billRule` | - | **字符串存储**(自动生成的编号) |
| 计算 | `calculate` | - | **数值存储**(计算结果) |
| 地址选择 | `address` | - | **纯文本字符串存储**(如"广东省东莞市万江区家达能大厦74B"),非 JSON 对象 |
### 系统控件
| 控件 | jnpfKey | 说明 | 数据存储规律 |
|------|---------|------|-------------|
| 创建用户 | `createUser` | 自动填充当前用户 | **用户id字符串** |
| 创建时间 | `createTime` | 自动填充创建时间 | **时间戳或日期字符串** |
| 修改时间 | `modifyTime` | 自动填充修改时间 | **时间戳或日期字符串** |
| 当前组织 | `currOrganize` | 自动填充当前组织 | **组织id字符串** |
| 区域选择 | `areaSelect` | 省市区选择 | **省市区JSON数组** |
---
## AIBridge 快速使用
### 基础文本输入
```python
from aibridge.builders.field_model import build_field_model
field = build_field_model(
field_name="客户名称",
field_vmodel="f_customer_name",
jnpf_key="input",
required=True
)
```
### 下拉选择 (注意 options 格式)
```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"},
]
)
```
### 日期选择
```python
field = build_field_model(
field_name="下单日期",
field_vmodel="f_order_date",
jnpf_key="datePicker",
required=True
)
```
### 子表格
```python
from aibridge.builders.field_model import build_table_field_model
table = build_table_field_model(
label="订单明细",
vmodel="f_order_detail_list",
child_table_name="ord_order_detail",
children=[
build_field_model("商品名称", "f_product_name", "input"),
build_field_model("数量", "f_quantity", "inputNumber"),
build_field_model("单价", "f_unit_price", "inputNumber"),
],
render_key=0,
show_summary=True,
summary_field="f_amount"
)
```
### 移动端表单配置
```python
from aibridge.builders.mobile_field_model import build_mobile_field, build_mobile_column_data
import json
# 构建单个移动端字段
mobile_field = build_mobile_field(
field_name="客户名称",
field_vmodel="f_customer_name",
jnpf_key="input",
required=True
)
# 批量构建移动端 columnData(可赋值给 f_app_column_data)
fields = [
{"fieldName": "客户名称", "field": "f_customer_name", "jnpfKey": "input", "required": True},
{"fieldName": "状态", "field": "f_status", "jnpfKey": "select", "options": [{"fullName": "启用", "id": "1"}]},
]
column_data = build_mobile_column_data(fields)
# 输出 JSON 字符串供 f_app_column_data 使用
print(json.dumps(column_data))
```
---
## 常见错误
| 错误 | 原因 | 解决 |
|------|------|------|
| 下拉选择不显示选项 | options 格式错误 | 必须使用 `{fullName, id}` 格式,不是 `{label, value}` |
| 日期选择无值 | valueFormat 与 format 不匹配 | valueFormat 应等于 format(如 `"yyyy-MM-dd"`),非 `"timestamp"` |
| 开关状态不生效 | activeValue/inactiveValue 类型错误 | 应为数值 `1/0`,非布尔 `True/False` |
| relationForm 无法弹出 | modelId 未设置 | 需要两阶段创建,先创建表单获取 ID,再填充 modelId |
| 子表格提交失败 | isSubTable 属性缺失 | 子表格字段必须设置 `is_sub_table=True` |
---
## workSystem 示例索引
| 表单名称 | 表单ID | 包含的控件 |
|----------|--------|----------|
| 信贷信息 | 797473600809468485 | input, inputNumber |
| 油耗计算 | 797460178185224773 | input, inputNumber, select |
| 二维码条形码联动 | 797444600007492165 | input, inputNumber, qrcode |
| 跨应用访问 | 797436740041179717 | relationForm |
| 员工培训 | 624164673918337925 | datePicker, input, organizeSelect, select, textarea, userSelect |
| 入职申请 | 624163990351643525 | datePicker, divider, input, organizeSelect, textarea, userSelect |
| 数据接口字段示例 | 469500336084679173 | autoComplete, cascader, checkbox, popupAttr, popupSelect, popupTableSelect, radio, select, treeSelect |
| 复杂表头主子表 | 469496902811974149 | table, tableGrid |
| 订单示例 | 469133201755925637 | billRule, createUser, datePicker, input, inputNumber, select, tab, textarea, uploadFile, userSelect |
| 产品管理 | 469039386000943493 | billRule, createTime, createUser, groupTitle, input, inputNumber, modifyTime, select, textarea, uploadImg |
详细示例见: [workSystem-examples.md](12-examples/workSystem-examples.md)