219 lines
10 KiB
Markdown
219 lines
10 KiB
Markdown
# 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)
|