File Upload

WdUploadFile

Applicable Scenarios

Used for uploading local file resources, such as video, audio, PDF, Excel, Word, etc.

Basic Capabilities

Bind File and Array Field

1. Single file upload: After the form container is bound to the data model, the "File" field in the model will be automatically rendered as a file upload component, providing support for uploading a single file.
2. Multiple file upload: After the form container is bound to the data model, the "Array" field of image elements in the model will be automatically rendered as a file upload component, providing support for uploading multiple files.

Extended Scenarios

Obtain File ID After User Uploads File

After a file is uploaded via the file upload component, an "Upload Success" event will be triggered. The cloudID of the uploaded file can be obtained from the output parameter event.detail.value of this event. This ID can be viewed by printing logs, as shown in the following example:

1. Create a custom method and write the log printing code console.log(event.detail.value). The specific content format is shown in the figure below:

   

2. Drag and drop the "File Upload" component into the page, and configure the "Upload Success" event to trigger this log printing method.

   

3. Preview the configuration effect: After a file upload is successful, you will find that the cloudID of the uploaded file is printed in the console.

   

4. In daily usage, you can store this ID in a variable through the component's upload success event, or utilize it in other ways.

   

Practices for Other Scenarios

Refer to the Form Scenario Practice Guide to explore various supported scenarios and implementation solutions for forms.

Notes

caution

After a file is uploaded, it is by default downloadable by the logged-in user. For security reasons, the generated temporary download URL has an expiration time limit and is not recommended to be stored in the database. To restrict file/image resources so that only the uploader can download them, adjust the bucket access permission to "Only creator and administrator have read/write access" in the Weida environment's CloudBase-Cloud Storage module.

Example

Interactive Preview

Component Input Status

Style API Example

#wd-page-root .wd-form-item.wd-pc-upload-file-root .wd-upload-file__label {
  color: #05c3c3;
  display: flex;
  justify-content: center;
  align-items: center;
}
#wd-page-root
  .wd-form-item.wd-pc-upload-file-root
  .weda-upload-file-pc__btn--weak {
  background: transparent;
}

Properties

External properties received by the component

Property Name	Property Identifier	Type	Description

Display Headlines	labelVisible	boolean	Default value: true
Title alignment	labelAlign	string	In the scenario, the form by default follows the title alignment configuration of the form container.
Line break in heading	labelWrap	boolean	If the title content is too long when closed, show one line with overflow omitted; when enabled, show with line breaks. In form scenarios, it follows the form container's title line break configuration by default.
Title position	layout	string	Set title display position in form component. In the scenario, it follows the title position configuration of the form container by default.
Title width	labelWidth	string	You can enter a value with units such as px or %, for example: 200px. In the scenario, the form follows the title width configuration of the form container by default.
Heading Note	labelTips	string	Take effect on PC/H5 Configure tooltip content for the heading
Maximum limit for a single file	maxSize	number	Default value: 10
File type limit	acceptTypes	string	Empty indicates no limit. Multiple data types should be separated by commas, for example doc,pdf,png. This property is not currently supported in mini programs. Supported file type formats
Upper limit of the number of files	maxUploadCount	number	Maximum number of uploads allowed Default value: 9
Status.	status	string	Example: "edit"
Required	required	boolean
Required identifier	requiredFlag	boolean	Enabled, the component will display a required asterisk tag if mandatory. Default value: true
Required validation note	requiredMsg	string	Example: "该项为必填项"
Upload button text	uploadButtonText	string	Upload button text Default value: "点击上传"
batch upload description	uploadTipText	string	Support batch uploading text description Default value: "支持批量上传"
Prompt.	extra	string	The prompt content is displayed below the input box after configuration.
Download supported after uploading	downloadVisible	boolean	Default value: true
Deletion supported after uploading	deleteVisible	boolean	Default value: true
Display underscore on mobile terminal	borderedH5	boolean	After closing, the mobile terminal does not show the bottom underline Default value: true
	callbacks	object	configuration-related functions
Bound field	name	string	After file upload, the file HTTPS URL can only be accessed in application by default, with a valid period of 2 hr. You can adjust access permission in Cloud Storage Settings. The Key value of a form field is used to match the field identifier of the data model when submitting data. It must be unique within the form.
Title content.	label	string	Example: "文件上传"
Value storage method	storageType	string	Select the cloudID method, and the file will be stored directly in the data model in the form of a cloud storage fileID. Select the HTTPS method, you need to first enable public read and write permissions for cloud storage, and the file will be stored in the data model in the form of an HTTPS link. Specify the image storage method Default value: "cloudID"
File value	value	array	Supports writing https addresses or cloudIDs to file in array format; supports string type for one upload and array type for multiple uploads.
Upload a single file	single	boolean	To upload multiple files, you can disable this property, but you need to bind an array-file field to ensure the form is properly committed. Learn more Enable the WeChat Mini Program to get the WeChat avatar, then only upload 1 image.

Pre-upload Handler Function Property

You can preprocess uploaded files using the pre-upload handler function.

Function Parameter Types:

type BeforeUploadParams0 = {
  // base64 uri
  base64Uri: string[];
  // Mini Program only, temporary file path
  tempFilePaths?: string[];
  // web end only, File object
  files: File[];
};

Function Return Value Types:

boolean | File[] | string[]

• Return true to continue the default upload logic.
• Return false to disable the default upload logic.
• The Web end returns an array of File. The Web end accepts the file[] returned by the function as the upload object to complete the upload logic.
• The Mini Program returns a string[] array of temporary file paths. The Mini Program receives the array of temporary file paths returned by the function as the upload object to complete the upload logic.

Applications can determine the runtime environment using the Platform API to optimize multi-end custom upload logic.

Example: Custom Upload

For example, to customize the upload to other destinations such as COS Below is an example using CloudBase Cloud Storage in the WeDa environment:

async (result) => {
  console.log('beforeUpload', result);
  // Files can be processed before upload, such as compression
  // result.files[0] = FAKE_COMPRESS(result.files[0])

  const tcb = await $w.cloud.getCloudInstance();
  const res = await tcb.uploadFile({
    cloudPath: 'ttt/abc.jpg',
    filePath: result.files[0]
  });

  console.log(res.download_url); // Image HTTP address
  $w.uploadImage1.setValue({ value: [res.download_url] }); // Set the obtained http address to the image upload component
  return false; // Abort the upload
};

Events

Events exposed by the component. You can listen to component events to trigger external actions

Event Name	Event Code	Event Output Parameters event.detail	Applicable Scenarios	Description

value change	change	object value: 值 isDelete: boolean是否删除动作	Compatible with all platforms	Trigger when a user modifies a component value
upload succeeded	success	object value: 上传文件的fileId file: 上传文件file对象	Compatible with all platforms	-
upload failed	error		Compatible with all platforms	-

Properties API

Through the Property API, you can access the internal state and property values of components. You can access internal values using$w.componentId.propertyName, such as $w.input1.value. For details, please refer to Property API

Read-only Property Name	Property Identifier	Type	Description

Bound field	name	string	The Key value of a form field is used to match the field identifier of the data model when submitting data. It must be unique within the form.
Title content.	label	string
File value	value	array	Supports writing https addresses or cloudIDs to file in array format; supports string type for one upload and array type for multiple uploads.
Required	required	boolean
Indicates whether to display	visible	boolean	Whether to display the component
Whether to disable	disabled	boolean	Component Disabled
Specify whether it is read-only or not.	readOnly	boolean	Whether the component is read-only

Method API

Through the Method API, you can programmatically trigger internal methods of components, such as submitting forms, displaying popups, etc. You can call component methods using $w.componentId.methodName, such as $w.form1.submit()

Method Name	Method Identifier	Parameters	Method Description

set value	setValue	object value: 值 isDelete: boolean是否删除动作	通过 $w.id1.setValue("weda") 设置组件值
Show/Hide Settings	setVisible	boolean显示	Set the component to hidden via $w.id1.setVisible(false)
Set Disabled	setDisabled	boolean禁用	Set the component to disabled with $w.id1.setDisabled(true)
Clear value	clearValue		Clear the component value with $w.id1.clearValue()
Set as read-only	setReadOnly	boolean只读	Set the component to read-only via $w.id1.setReadOnly(true)
Trigger validation	handleValidate		Validate the component value via $w.id1.handleValidate()
Clear verification	clearValidate		Clear component validation via $w.id1.clearValidate()

Style API

Through the Style API, you can override the styles of internal elements in components to achieve customization. For example, in the low-code editor, you can write styles for all button components using #wd-page-root .wd-btn, and control individual component styles with :scope. For detailed instructions, please refer toStyle API

Name	Class Name	Description and Examples

root element	.wd-upload-file-root	Outermost component element /* :scope refers to the current component element */ /* For details, refer to the Style API documentation */ :scope.wd-upload-file-root { /* Write CSS styles here */ }
H5 root element	.wd-h5-upload-file-root	Settable root element style for the H5 side /* :scope refers to the current component element */ /* For details, refer to the Style API documentation */ :scope.wd-h5-upload-file-root { /* Write CSS styles here */ }
PC-side root element	.wd-pc-upload-file-root	Settable root element style for the PC side /* :scope refers to the current component element */ /* For details, refer to the Style API documentation */ :scope.wd-pc-upload-file-root { /* Write CSS styles here */ }
Mini program root element	.wd-mp-upload-file-root	Settable root element style for mini program /* :scope refers to the current component element */ /* For details, refer to the Style API documentation */ :scope.wd-mp-upload-file-root { /* Write CSS styles here */ }
Component title style	.wd-upload-file-root .wd-form-item-wrap__label	Component title element :scope .wd-form-item-wrap__label { font-size: 20px; color: gray; padding: 0; display: flex; align-items: center; }
form control root node style	.wd-upload-file-root .wd-form-item-wrap__control	Set form control root element style :scope .wd-form-item-wrap__control { font-size: 20px; color: gray; padding: 0; display: flex; align-items: center; }
Editing status - Verification information	.wd-upload-file-root .wd-g-text-error	Set component verification information style :scope .wd-g-text-error { font-size: 20px; color: gray; }
prompt text	.wd-upload-file-root .wd-form-item__help-text	Set the text style of the component prompt :scope .wd-form-item__help-text { font-size: 20px; color: gray; }

Learn about Style API

Version Changes

• Property Changes
• Style Changes
• widget api Changes

Frequently Asked Questions

Is there a size limit for uploaded files?

The size limit for uploaded files primarily depends on the underlying cloud storage restrictions. Currently, the PUT Object interface of the underlying cloud storage supports a maximum file size of 5GB for uploads. While there is no strict limit, excessively large files may easily cause upload failures since the resumable upload feature is not yet supported. In practical applications, choose an appropriate file size for upload based on actual requirements and network conditions.

Supported File Formats for Mini Program File Downloads

On the Mini Program side, file preview and download are implemented using the wx.openDocument interface, which only supports downloading files in specific formats.