SDKsuni-app / uni-app x

Upload a file

Upload local files independently with the UniApp SDK and retrieve remote resource URLs.

The file upload capability functions as an independent asset uploader for user avatars, group icons, profile attachments, or general application assets. It operates independently of the messaging pipeline and does not automatically construct or transmit messages.

Parameters

Parameter	Type	Required	Description
`filepath`	`string`	Yes	Local file path readable by the native SDK.
`name`	`string`	Yes	Filename including file extension.
`contentType`	`string`	Yes	The MIME type of the file.
`uuid`	`string`	Yes	A unique task identifier generated by the client for this upload.
`cancelID`	`string \| null`	No	Identifier used to abort the upload; generate and store this before invoking the upload if cancellation is required.
`cause`	`string \| null`	No	Optional business context or reason for the upload.

Temporary file paths obtained from the photo picker, document picker, or audio recorder can be uploaded directly, but the OS may purge temporary directories at any time. When implementing retry logic or requiring local persistence, move the file into uni.env.USER_DATA_PATH via uni.getFileSystemManager() before persisting the path.

Code example

import { uploadFile } from '@/uni_modules/unix-openim-sdk'

const uploadTaskID = `avatar-${Date.now()}`
const cancelID = `cancel-${uploadTaskID}`

const result = await uploadFile({
  filepath: selectedImagePath,
  name: 'avatar.jpg',
  contentType: 'image/jpeg',
  uuid: uploadTaskID,
  cancelID,
})

if (result?.url != null) {
  await updateProfileAvatar(result.url!)
}

Return value

The Promise resolves with an OpenIMUploadFileResult | null object:

Property	Type	Description
`url`	`string \| null`	Public remote URL for the uploaded resource.
`uri`	`string \| null`	Internal storage identifier or path returned by the server.
`uuid`	`string \| null`	Task identifier matching the upload request.
`size`	`number \| null`	File size reported by the storage backend.
`typ`	`number \| null`	Storage resource type integer.
`mediaID`	`string \| null`	Storage media identifier.

Only consume non-null properties required by your application. A resolved Promise confirms that the binary upload succeeded; it does not update a user profile or create a message. Trigger subsequent operations explicitly.

Monitor upload progress

The onUploadFileProgress event provides an OpenIMUploadFileProgressEvent | null object containing only progress without a task identifier. Because the event payload does not include a task ID, avoid concurrent uploads if you need to track individual file percentages accurately. For multi-file flows, serialize uploads or limit concurrency.

import {
  OpenIMUploadFileProgressEvent,
  off,
  onUploadFileProgress,
} from '@/uni_modules/unix-openim-sdk'

const handleUploadProgress = (
  event: OpenIMUploadFileProgressEvent | null,
) => {
  if (event == null) return
  setCurrentUploadProgress(event.progress)
}

const uploadProgressSubscription =
  onUploadFileProgress(handleUploadProgress)

// Clean up when destroying view models or switching sessions:
off(uploadProgressSubscription)

To abort an in-flight upload task, pass the saved cancelID to Cancel a file upload.

Was this page helpful?