# 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)