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