Files
aibridge/docs/control/06-popup-controls.md
T
2026-05-18 09:28:15 +08:00

315 lines
7.8 KiB
Markdown
Raw 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.
# 弹窗控件
## 目录
- [弹窗表格 (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)