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