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

266 lines
6.7 KiB
Markdown
Raw Permalink 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.
# 上传控件
## 目录
- [图片上传 (uploadImg)](#图片上传-uploadimg)
- [文件上传 (uploadFile)](#文件上传-uploadfile)
- [移动端特有上传控件](#移动端特有上传控件)
---
## 图片上传 (uploadImg)
### 基本信息
| 属性 | 值 |
|------|-----|
| jnpfKey | `uploadImg` |
| AIBridge builder | `build_field_model(..., jnpf_key="uploadImg")` |
| workSystem 示例 | 纵向卡片表格、横向卡片表格、产品管理、设备巡检 等 |
### 基本规则
1. **必填配置**:
- `field_name`: 字段中文名称
- `field_vmodel`: 字段 vModel
- `jnpf_key`: `"uploadImg"`
2. **特有配置**:
- `multiple`: 是否多选 (默认 False)
- `maxCount`: 最大上传数量 (默认无限制)
- `maxSize`: 单个文件最大大小 (MB)
### AIBridge 使用
```python
# 基础图片上传
field = build_field_model(
field_name="证件照片",
field_vmodel="f_id_card_photo",
jnpf_key="uploadImg",
required=True
)
# 多图片上传
multi_field = build_field_model(
field_name="产品图片",
field_vmodel="f_product_images",
jnpf_key="uploadImg",
multiple=True,
maxCount=9
)
```
### workSystem 示例
| 表单名称 | 表单ID | 配置 |
|----------|--------|------|
| 纵向卡片表格 | 797382749911515717 | uploadImg |
| 横向卡片表格 | 797381799859716677 | uploadImg |
| 产品管理 | 469039386000943493 | 产品图片 |
| 设备巡检管理 | 469062048563652997 | 巡检照片 |
### 返回数据格式
图片上传后,数据库存储的是**文件路径字符串**,格式如:
```
/upload/20260407/test.jpg
```
> ⚠️ **注意**:文档早期描述的 JSON 数组格式 `[{"fileId":"xxx","name":"a.jpg","url":"/files/xxx.jpg"}]` 与实际存储不符,实际存储为纯文件路径字符串。
---
## 文件上传 (uploadFile)
### 基本信息
| 属性 | 值 |
|------|-----|
| jnpfKey | `uploadFile` |
| AIBridge builder | `build_field_model(..., jnpf_key="uploadFile")` |
| workSystem 示例 | 劳动合同续签、离职交接表、采购合同、订单示例 等 |
### 基本规则
同 uploadImg,但上传任意文件类型。
### AIBridge 使用
```python
# 基础文件上传
field = build_field_model(
field_name="合同附件",
field_vmodel="f_contract_attachment",
jnpf_key="uploadFile",
required=True
)
# 多文件上传
multi_field = build_field_model(
field_name="证明材料",
field_vmodel="f_certificates",
jnpf_key="uploadFile",
multiple=True,
maxCount=5
)
```
### workSystem 示例
| 表单名称 | 表单ID | 用途 |
|----------|--------|------|
| 劳动合同续签 | 623425065425305605 | 合同扫描件 |
| 离职交接表 | 623417538411233285 | 交接文档 |
| 代码对比 | 585436444760212229 | 代码文件 |
| 付款申请 | 585398402720727621 | 付款凭证 |
| 套打示例 | 585384793399624261 | 附件 |
| 采购合同 | 585077579715707205 | 合同文件 |
| 订单示例 | 469133201755925637 | 附件 |
| 采购管理 | 469106304141552773 | 采购文件 |
| 事件管理 | 469065268790880645 | 事件附件 |
| 人才管理 | 469047177461688709 | 简历附件 |
| 核酸检测 | 469038006062344581 | 检测报告 |
---
## 移动端特有上传控件
### 上传控件对比
| 控件 | jnpfKey | 平台 | 说明 |
|------|---------|------|------|
| uploadImg | uploadImg | PC+移动 | 图片上传 |
| uploadFile | uploadFile | PC+移动 | 文件上传 |
| UploadFileH | uploadFileH | 移动端 | H5文件上传 (跨平台) |
| UploadFileComment | uploadFileComment | 移动端 | 评论文件上传 |
### 移动端配置
移动端文件上传需要额外配置 `appColumnData`,用于移动端动态表单配置。
```python
# 移动端图片上传配置
field = build_field_model(
field_name="现场照片",
field_vmodel="f_scene_photos",
jnpf_key="uploadImg",
multiple=True
)
# 移动端配置需在 appColumnData 中单独设置
```
---
## 上传控件通用配置
### 重要配置项
| 配置 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| multiple | bool | False | 是否多选 |
| maxCount | int | 无限制 | 最大文件数 |
| maxSize | int | 无限制 | 单文件最大大小(MB) |
| accept | string | 无限制 | 接受的文件类型 |
| showTip | bool | True | 是否显示提示 |
| showView | bool | True | 是否显示预览 |
| showDownload | bool | True | 是否显示下载 |
### 文件类型限制
```python
# 仅允许图片
field = build_field_model(
field_name="证件照",
field_vmodel="f_id_photo",
jnpf_key="uploadImg",
accept="image/*"
)
# 仅允许 PDF 和 Word
field = build_field_model(
field_name="文档",
field_vmodel="f_document",
jnpf_key="uploadFile",
accept=".pdf,.doc,.docx"
)
# 全部允许 (默认)
field = build_field_model(
field_name="附件",
field_vmodel="f_attachments",
jnpf_key="uploadFile"
)
```
---
## 常见问题
| 问题 | 原因 | 解决 |
|------|------|------|
| 上传后不显示 | vModel 字段类型不对 | 数据库字段类型应为 varchar(500+) |
| 多文件只保存一个 | multiple 未设置 | `multiple=True` |
| 移动端上传失败 | appColumnData 未配置 | 需在移动端单独配置 |
| 文件下载404 | 路径问题 | 检查文件服务器配置 |
---
## 数据存储规律
### 上传控件存储规律
| 控件 | jnpfKey | 存储类型 | 存储格式示例 |
|------|---------|---------|------------|
| 图片上传 | `uploadImg` | **文件路径字符串** | `"/upload/20260407/test.jpg"` |
| 文件上传 | `uploadFile` | **文件路径字符串** | `"/upload/20260407/test.pdf"` |
### 返回数据结构
上传成功后,控件返回的 JSON 数组格式:
```json
[
{
"fileId": "文件ID",
"name": "文件名.jpg",
"url": "/files/实际路径/文件名.jpg",
"size": 12345,
"type": "image/jpeg"
}
]
```
### 实际测试结果
```python
# 未上传时,数据库存储空字符串
f_uploadImg: ''
# 上传后,数据库存储文件路径字符串
f_uploadImg: '/upload/20260407/test.jpg'
```
> **交叉验证**:在 `datahub_banner.f_image`、`datahub_app.f_icon`、`comp_test_1775565106.f_uploadImg` 等多个表中均确认存储为文件路径字符串。
### 数据库字段要求
| 控件 | 建议字段类型 |
|------|------------|
| uploadImg | `varchar(2000)` 或 `text` |
| uploadFile | `varchar(2000)` 或 `text` |
### 重要提示
1. **文件存储位置**:文件实际存储在服务器 `/files/` 目录下,数据库只存储路径信息
2. **fileId 作用**:用于文件下载/预览时查找文件
3. **多文件上传**:multiple=true 时,JSON 数组会包含多个文件对象
---
## 下一步
- [弹窗控件](06-popup-controls.md)
- [子表格控件](07-table-controls.md)
- [特殊控件](08-special-controls.md)