# 弹窗控件 ## 目录 - [弹窗表格 (popupTable)](#弹窗表格-popuptable) - [弹窗选择 (popupSelect)](#弹窗选择-popupselect) - [弹窗属性 (popupAttr)](#弹窗属性-popupattr) - [关联表单 (relationForm)](#关联表单-relationform) - [关联流程 (relationFlow)](#关联流程-relationflow) --- ## 弹窗表格 (popupTable) ### 基本信息 | 属性 | 值 | |------|-----| | jnpfKey | `popupTable` | | AIBridge builder | 无完整封装,需两阶段创建 | | workSystem 示例 | 数据接口调用字段示例 (#33) | | 复杂度 | 高 - 需要目标表单ID | ### 基本规则 1. **核心概念**:弹窗表格通过弹出另一个表单的列表来选择数据 2. **必需配置**: - `modelId`: 目标表单的 visual_dev ID - `relationField`: 关联字段名 3. **其他配置**: - `popupType`: 弹窗类型 (`"dialog"` / `"drawer"`) - `popupTitle`: 弹窗标题 - `popupWidth`: 弹窗宽度 - `hasPage`: 是否分页 - `pageSize`: 每页条数 ### AIBridge 两阶段创建 **第一阶段**:创建字段(不包含 modelId) ```python # 注意:popupTable 的 modelId 需要等目标表单创建后才能填入 # 先创建占位字段 field = build_field_model( field_name="选择客户", field_vmodel="f_customer_id", jnpf_key="popupTable", # modelId 暂时不填,创建目标表单后再更新 ) ``` **第二阶段**:更新 modelId ```python # 假设目标客户表单 ID 为 123456789 target_form_id = "123456789" # 更新字段配置,填入 modelId field["__config__"]["modelId"] = target_form_id field["relationField"] = "f_customer_id" # 目标表单的关联字段 ``` ### workSystem 示例 | 表单名称 | 表单ID | 说明 | |----------|--------|------| | 数据接口调用字段示例 | 469500336084679173 | popupTableSelect | --- ## 弹窗选择 (popupSelect) ### 基本信息 | 属性 | 值 | |------|-----| | jnpfKey | `popupSelect` | | AIBridge builder | 无封装 | | workSystem 示例 | 数据接口调用字段示例 (#33) | ### 基本规则 同 popupTable,但显示为单选/多选样式。 ### workSystem 示例 | 表单名称 | 表单ID | 配置字段 | |----------|--------|----------| | 数据接口调用字段示例 | 469500336084679173 | popupSelect, popupTableSelect | ### 手动配置示例 ```json { "__config__": { "jnpfKey": "popupSelect", "label": "选择供应商", "tag": "JnpfPopupSelect" }, "modelId": "目标表单ID", "relationField": "f_supplier_id", "popupType": "dialog", "popupTitle": "选择供应商", "popupWidth": "800px", "multiple": false, "hasPage": true, "pageSize": 20 } ``` --- ## 弹窗属性 (popupAttr) ### 基本信息 | 属性 | 值 | |------|-----| | jnpfKey | `popupAttr` | | AIBridge builder | 无封装 | | workSystem 示例 | 数据接口调用字段示例 (#33) | ### 基本规则 弹窗属性用于显示关联数据的详细属性,**不需要选择**。 ### workSystem 示例 | 表单名称 | 表单ID | 配置字段 | |----------|--------|----------| | 数据接口调用字段示例 | 469500336084679173 | popupAttr | ### 手动配置示例 ```json { "__config__": { "jnpfKey": "popupAttr", "label": "供应商信息", "tag": "JnpfPopupAttr" }, "modelId": "目标表单ID", "relationField": "f_supplier_id", "popupType": "dialog", "popupTitle": "供应商详情" } ``` --- ## 关联表单 (relationForm) ### 基本信息 | 属性 | 值 | |------|-----| | jnpfKey | `relationForm` | | AIBridge builder | 无完整封装 | | workSystem 示例 | 跨应用访问 (#4) | ### 基本规则 关联表单用于在当前表单中嵌入另一个表单的视图,**实现跨应用数据访问**。 ### 关键配置 | 属性 | 说明 | |------|------| | `modelId` | 目标表单的 visual_dev ID | | `relationField` | 显示文本字段(如 `f_name`),弹窗列表和选中后显示的文字 | | `propsValue` | 实际主键字段(小写 `f_id`,提交时保存的值) | | `columnOptions` | 弹窗列表的列配置,格式 `[{value, label}]`,从目标表单 `columnData` 中提取 | > **常见错误**: > - 把 `relationField` 设成 ID 字段(如 `f_id`),导致弹窗只显示序号而非名称 > - `propsValue` 误用大写字段名(如 `f_id`),实际主键应为小写 `f_id`(DataChange API 返回的数据主键字段是小写) > - 缺少 `columnOptions`,导致弹窗列表只有序号列 ### workSystem 示例 | 表单名称 | 表单ID | 说明 | |----------|--------|------| | 跨应用访问 | 797436740041179717 | relationForm, 跨应用数据展示 | ### 手动配置示例 ```json { "__config__": { "jnpfKey": "relationForm", "label": "关联客户信息", "tag": "JnpfRelationForm" }, "modelId": "目标表单ID", "relationField": "f_name", "propsValue": "f_id", "columnOptions": [ {"value": "f_name", "label": "名称"}, {"value": "f_code", "label": "编号"} ], "hasPage": true, "pageSize": 20, "popupType": "dialog", "popupTitle": "选择客户", "popupWidth": "800px" } ``` --- ## 关联流程 (relationFlow) ### 基本信息 | 属性 | 值 | |------|-----| | jnpfKey | `relationFlow` | | AIBridge builder | 无封装 | ### 基本规则 关联流程用于在表单中嵌入流程相关信息。 ### 手动配置示例 ```json { "__config__": { "jnpfKey": "relationFlow", "label": "关联流程", "tag": "JnpfRelationFlow" }, "flowId": "流程模板ID" } ``` --- ## 弹窗控件对比 | 控件 | 选择方式 | 编辑支持 | 适用场景 | AIBridge | |------|---------|---------|----------|----------| | popupTable | 弹窗列表选择 | 否 | 简单选择 | 需两阶段 | | popupSelect | 弹窗下拉选择 | 否 | 单选/多选 | 无封装 | | popupAttr | 无选择 | 是 | 仅展示详情 | 无封装 | | relationForm | 嵌入表单 | 是 | 跨应用数据 | 无封装 | | relationFlow | 嵌入流程 | - | 流程关联 | 无封装 | --- ## 常见问题 | 问题 | 原因 | 解决 | |------|------|------| | 弹窗不弹出 | modelId 不正确 | 检查目标表单 ID | | 数据不显示 | relationField 不匹配 | 确保字段名一致 | | 跨应用失败 | 权限问题 | 检查目标表单权限配置 | | 选择后不回填 | popupType 配置 | 确认 popupType 是否正确 | --- ## 数据存储规律 ### 弹窗控件存储规律 | 控件 | jnpfKey | 存储类型 | 存储格式示例 | 说明 | |------|---------|---------|------------|------| | 弹窗表格 | `popupTable` | **字符串** | `"123456789"` | 选中记录的主键ID | | 弹窗选择 | `popupSelect` | **字符串或JSON数组** | `"123"` 或 `["123","456"]` | 单选为ID字符串,多选为ID数组 | | 弹窗属性 | `popupAttr` | **JSON对象字符串** | `{"id":"123","name":"供应商A",...}` | 关联记录的完整属性 | | 关联表单 | `relationForm` | **字符串** | `"123456789"` | 选中记录的主键ID | | 关联流程 | `relationFlow` | **字符串** | `"flow_123"` | 流程实例ID | ### 存储详解 **popupTable / relationForm**: 存储的是选中记录的主键ID(f_id),用于关联查询 ```json // 存储值示例 "f_customer_id": "811298790165190697" ``` **popupSelect 多选**: 存储的是选中记录的ID数组(JSON序列化) ```json // 存储值示例 "f_product_ids": '["811298790165190697","811298790165190698"]' ``` **popupAttr**: 存储的是关联记录的完整JSON对象 ```json // 存储值示例 "f_supplier_info": '{"id":"123","name":"供应商A","code":"SUP001","contact":"张三"}' ``` ### 数据库字段要求 | 控件 | 建议字段类型 | |------|------------| | popupTable/relationForm | `varchar(50)` | | popupSelect (单选) | `varchar(50)` | | popupSelect (多选) | `varchar(500)` 或 `text` | | popupAttr | `text` | | relationFlow | `varchar(50)` | --- ## 下一步 - [子表格控件](07-table-controls.md) - [特殊控件](08-special-controls.md) - [图表控件](09-chart-controls.md)