简介

fs-form-file 是表单项内容控件，可独立使用或配合 fs-form 使用。支持本地文件、相册、拍照、网盘、录制视频等多种文件来源，提供文件格式校验、队列上传、实时状态管理等功能。

使用方法

局部引入时，在页面的 index.json 中配置：

"usingComponents": {
  "fs-form-file": "/avaui-sub/fs-form/fs-form-file/index"
}

配合 fs-form 使用时：

"usingComponents": {
  "fs-form": "/avaui-sub/fs-form/index",
  "fs-form-item": "/avaui-sub/fs-form/fs-form-item/index",
  "fs-form-file": "/avaui-sub/fs-form/fs-form-file/index"
}

PWC（自定义组件/插件）使用：仅 usingComponents 注册方式使用 avaComponent:// 协议，其他用法一致。

单独使用时：

"usingComponents": {
  "fs-form-file": "avaComponent://avaui-sub/fs-form/fs-form-file/index"
}

代码演示

1. 基础用法

支持文件选择、上传、预览和删除，通过 value 绑定值，通过 change 事件监听值变化。

2. 配合 fs-form 使用

展示在 fs-form 中使用文件上传组件，包含多个文件字段、表单校验、上传中状态管理、提交按钮联动等完整功能。

---

API

fs-form-file 属性

参数	说明	类型	可选值	默认值
value	文件数组，每个文件包含 filename、ext、size、path、create_time	Array	—	[]
file_source	文件来源配置	Array	local / net	['local', 'net']
file_amount_limit	文件数量限制	Number	—	9
support_file_suffix	支持的文件后缀名数组，不区分大小写，始终禁止 .exe	Array	—	[]
placeholder	占位提示文字	String	—	''
disabled	是否禁用	Boolean	—	false
saveToFormal	是否上传后直接保存为正式文件，默认是临时文件(谨慎使用，正式文件没有自动清理机制，避免无用文件存储占用资源)	Boolean	—	false
hooks	钩子函数集合，可含 httpRequest 自定义上传（见下）	Object	—	{}

自定义上传 hooks.httpRequest：直接传入函数，由外部完全控制上传请求的发起。函数签名与 fsapi.uploadFile.upload 一致：(files, onProgressUpdate, complete)。参数说明：

• files：待上传文件数组（每项含 id、filePath、ext、fileId 等）
• onProgressUpdate(file)：单个文件进度/状态更新时调用（可修改 file.status、file.path 后传入）
• complete(results)：全部上传结束时调用，传入结果文件数组

fs-form-file 事件

事件名	说明	回调参数
change	文件变化时触发（用于 fs-form 更新及校验）	{ value: Array }
statuschange	文件上传状态变化时触发	{ hasUploading: Boolean, hasFailed: Boolean }

注意： change 事件开启了 bubbles: true 和 composed: true，可被 fs-form-item 捕获用于表单校验。

fs-form-file 方法

方法名	说明	参数	返回值
hasUploadingFiles	检查是否有文件正在上传	—	Boolean
hasFailedFiles	检查是否有上传失败的文件	—	Boolean
getValue	获取上传成功的文件列表	—	Array

---

设计说明

文件状态管理

组件内部维护文件状态：

• unUpload：待上传
• uploading：上传中
• success：上传成功
• fail：上传失败

文件来源

local（本地文件）：

• H5：相册、拍照、本地文件
• iOS（App >= 915）：相册、拍照、本地视频、本地文件（iCloud）、录制视频（>= 975）
• Android（App >= 915）：相册、拍照、本地文件、录制视频（>= 975）

net（网盘文件）：

• 仅原生环境支持
• 调用 jsapi.chooseFile 的 netdisk 类型

表单校验集成

推荐使用页面状态管理方案，通过 statuschange 事件监听上传状态：

data: {
  fileUploadStatus: { hasUploading: false, hasFailed: false }
},

onFileStatusChange(e) {
  this.setData({ 
    fileUploadStatus: e.detail,
    submitDisabled: e.detail.hasUploading
  });
},

formRules: {
  files: [{
    validator: (rule, value) => {
      if (this.data.fileUploadStatus.hasUploading) {
        return Promise.reject('请等待附件上传完毕');
      }
      if (this.data.fileUploadStatus.hasFailed) {
        return Promise.reject('存在上传失败的附件，请删除后重试');
      }
      return Promise.resolve();
    }
  }]
}

注意事项

1. 文件格式：始终禁止上传 .exe 文件，其他格式根据 support_file_suffix 配置决定
2. 队列上传：文件逐个上传，避免并发过多
3. 临时文件清理：iOS 环境下删除文件时自动清理临时文件
4. 网盘文件：网盘文件通过接口获取 path，无需本地上传
5. 需要在页面引入 dialog-center 组件

---

打开预览