fs-form-file

About 783 wordsAbout 3 min

Introduction

fs-form-file is a form item content control that can be used independently or together with fs-form. It supports multiple file sources such as local files, photo album, camera, network disk, and recorded video, and provides file format validation, queued upload, and real-time status management.

Usage

When importing locally, configure in the page's index.json:

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

When using together with 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 (custom component/plugin) usage: only the usingComponents registration uses the avaComponent:// protocol; everything else is the same.

When using standalone:

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

Code demos

1. Basic usage

Supports file selection, upload, preview, and deletion. Bind the value via value and listen for value changes via the change event.

2. Using with fs-form

Demonstrates using the file upload component inside fs-form, including multiple file fields, form validation, in-upload status management, and submit button linkage.

API

fs-form-file properties

Parameter	Description	Type	Possible values	Default
value	File array. Each file contains filename, ext, size, path, create_time	Array	—	[]
file_source	File source configuration	Array	local / net	['local', 'net']
file_amount_limit	File count limit	Number	—	9
support_file_suffix	Array of supported file suffixes, case-insensitive. .exe is always forbidden	Array	—	[]
placeholder	Placeholder hint text	String	—	''
disabled	Whether disabled	Boolean	—	false
saveToFormal	Whether to save uploaded files as formal files directly. Defaults to temporary files (use with caution: formal files have no auto-cleanup mechanism and may occupy storage with unused files)	Boolean	—	false
hooks	Hook function collection, may include httpRequest custom upload (see below)	Object	—	{}

Custom upload hooks.httpRequest: Pass a function directly; the external side fully controls the upload request. The function signature is identical to fsapi.uploadFile.upload: (files, onProgressUpdate, complete). Parameter description:

files: Array of files to upload (each item contains id, filePath, ext, fileId, etc.)
onProgressUpdate(file): Called when a single file's progress/status updates (you may modify file.status, file.path, then pass them in)
complete(results): Called when all uploads finish, receiving the result file array

fs-form-file events

Event	Description	Callback params
change	Triggered when files change (used by fs-form for update and validation)	`{ value: Array }`
statuschange	Triggered when file upload status changes	`{ hasUploading: Boolean, hasFailed: Boolean }`

Note: The change event has bubbles: true and composed: true enabled, so it can be captured by fs-form-item for form validation.

fs-form-file methods

Method name	Description	Parameters	Return value
hasUploadingFiles	Check whether any files are uploading	—	Boolean
hasFailedFiles	Check whether any files failed to upload	—	Boolean
getValue	Get the list of successfully uploaded files	—	Array

Design notes

File status management

The component maintains file status internally:

unUpload: Pending upload
uploading: Uploading
success: Upload succeeded
fail: Upload failed

File sources

local (local files):

H5: photo album, camera, local files
iOS (App >= 915): photo album, camera, local video, local files (iCloud), recorded video (>= 975)
Android (App >= 915): photo album, camera, local files, recorded video (>= 975)

net (network disk files):

Only supported in native environments
Calls the netdisk type of jsapi.chooseFile

Form validation integration

The recommended approach uses page state management, listening to upload status via the statuschange event:

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('Please wait for attachments to finish uploading');
      }
      if (this.data.fileUploadStatus.hasFailed) {
        return Promise.reject('Some attachments failed to upload. Please remove them and retry');
      }
      return Promise.resolve();
    }
  }]
}

Notes

File format: .exe upload is always forbidden; other formats are controlled by the support_file_suffix config
Queued upload: Files are uploaded one by one to avoid excessive concurrency
Temporary file cleanup: On iOS, temporary files are automatically cleaned up when files are deleted
Network disk files: Network disk files obtain their path via API, with no local upload needed
The page must include the dialog-center component

打开预览