Files
aibridge/docs/control/01-quick-ref.md
T
2026-05-18 09:28:15 +08:00

10 KiB
Raw Blame History

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 快速使用

基础文本输入

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 格式)

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"},
    ]
)

日期选择

field = build_field_model(
    field_name="下单日期",
    field_vmodel="f_order_date",
    jnpf_key="datePicker",
    required=True
)

子表格

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

移动端表单配置

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