266 lines
6.7 KiB
Markdown
266 lines
6.7 KiB
Markdown
# 上传控件
|
||
|
||
## 目录
|
||
|
||
- [图片上传 (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)
|