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

6.7 KiB
Raw Blame History

上传控件

目录


图片上传 (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 使用

# 基础图片上传
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 使用

# 基础文件上传
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,用于移动端动态表单配置。

# 移动端图片上传配置
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 是否显示下载

文件类型限制

# 仅允许图片
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 数组格式:

[
  {
    "fileId": "文件ID",
    "name": "文件名.jpg",
    "url": "/files/实际路径/文件名.jpg",
    "size": 12345,
    "type": "image/jpeg"
  }
]

实际测试结果

# 未上传时,数据库存储空字符串
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 数组会包含多个文件对象

下一步