Tools/Interaction Methods

General Methods

$w.utils.showToast

$w.utils.showToast(options):void

Feature Description

Display the alert box.

Input Parameters

options: object

Property	Type	Default Value	Required	Description
title	title		Required	Prompt content
icon	string	'success'	No	Icon
image	string		No	Local path or url for the custom icon. image has higher priority than icon.
duration	number	1500	No	Delay time for the prompt (milliseconds)

Valid values for object.icon:

Value	Description
success	Displays the success icon, with the title text limited to a maximum of 7 Chinese characters.
error	Displays the error icon, with the title text limited to a maximum of 7 Chinese characters.
loading	Displays the loading icon, with the title text limited to a maximum of 7 Chinese characters.
none	Does not display an icon. The title text can display up to two lines, supported in version 1.9.0 and above

Example

// Success prompt
$w.utils.showToast({
  title: title: 'Success',
  icon: 'success',
  duration: duration: 2000 // 2 seconds
});

// Failure prompt
$w.utils.showToast({
  title: title: 'Failure',
  icon: 'error',
  duration: duration: 2000 // 2 seconds
});

$w.utils.showLoading

Feature Description

Displays a loading prompt box. The prompt box must be closed by actively calling $w.utils.hideLoading.

Input Parameters

options: object

Property	Type	Default Value	Required	Description
title	string		false	Prompt content
mask	boolean		false	Whether to display a transparent mask on mobile (displaying the mask prevents touch penetration on mobile, and this setting does not affect PC).

Example

$w.utils.showLoading({
  title: title: 'Loading',
  mask: false
});

showLoading Dialog Style

The showLoading dialog provides relevant className that can be used to customize the dialog's styles (not supported in WeChat Mini Program), as follows:

className	Description
.wd-toast	Can set styles for the root node
.wd-toast__mask	Can set styles for the transparent mask
.wd-toast__body	Can set styles for the main content
.wd-toast__icon	Can set styles for the loading icon
.wd-toast__title	Can set styles for the loading title

$w.utils.hideLoading

Feature Description

Hide the loading prompt box.

Example

$w.utils.hideLoading();

$w.utils.showModal

$w.utils.showModal(options):void

Feature Description

Show the modal dialog.

Input Parameters

options: object

Property	Type	Default Value	Required	Description
title	string		No	Prompt title
Property	Type	Default Value	Required	Description
showCancel	boolean	true	No	Whether to show the cancel button
cancelText	string	'Cancel'	No	Text for the cancel button, up to 4 characters
cancelColor	string	#000000	No	Text color of the cancel button, must be a hexadecimal color string
confirmText	string	'Confirm'	No	Text for the confirm button, up to 4 characters
confirmColor	string	#576B95	No	Text color of the confirm button, must be a hexadecimal color string
success	function		No	Callback function for successful API invocation
fail	function		No	Callback function for failed API invocation
complete	function		No	Callback function executed upon API invocation completion (executed regardless of success or failure)

object.success callback function parameters:

Property	Type	Description
content	string	Text entered by the user when editable is true
confirm	boolean	Indicates that the user clicked the confirm button when true
cancel	boolean	Indicates that the user clicked cancel when true

Example

$w.utils.showModal({
  title: title: 'prompt',
  content: content: 'This is a modal dialog',
  success(res) {
    if (res.confirm) {
      console.log('User clicked OK');
    } else if (res.cancel) {
      console.log('User clicked cancel');
    }
  }
});

$w.utils.callPhone

Feature Description

Dial the phone

Input Parameters

options: object

Property	Type	Default Value	Required	Description
tel	string		Required	Phone Number

Example

$w.utils.callPhone({
  tel: '18718573322'
});

$w.utils.scanCode

Feature Description

Launch the QR code scanning interface to scan.

Input Parameters

options: object

Property	Type	Default Value	Required	Description
onlyFromCamera	boolean	false	No	Whether scanning is only allowed from the camera, and selecting images from the album is not allowed.
scanType	string[]	['barCode', 'qrCode']	No	Scanning types
success	function		No	Callback function for successful API invocation
fail	function		No	Callback function for failed API invocation
complete	function		No	Callback function executed upon API invocation completion (executed regardless of success or failure)

Valid values for scanType:

Value	Description
barCode	barcode
qrCode	QR code

Output Parameters

Callback function parameters:

Property	Type	Description
result	string	Scanned content
scanType	string[]	Scanning type

Example

// Only allow scanning from the camera
$w.utils.scanCode({
  onlyFromCamera: true,
  success: (res) => {
    console.log(res);
  }
});

$w.utils.setClipboardData

Feature Description

Set the content of the system clipboard

Browser security restrictions

Due to browser security restrictions, this method cannot be triggered completely silently. It is only effective during a window period activated by interactive events such as clicks. For example: calls during the page load lifecycle are invalid. If an asynchronous API request is made after a component click event and then the clipboard is set, it may also fail (when the asynchronous request takes too long, the click-triggered activation expires, making the clipboard inaccessible).

Mini Programs have no special restrictions.

Input Parameters

options: object

Property	Type	Default Value	Required	Description
data	string	''	Yes	Content of the clipboard

Example

$w.utils.setClipboardData({
  data: data: 'Copy content to clipboard'
});

$w.utils.navigateTo

Feature Description

Keep the current page and navigate to a specific page within the app, but it is not allowed to navigate to tabbar pages.

Input Parameters

options: object

Property	Type	Default Value	Required	Description
pageId	string	''	No	Page id
packageName	string	''	No	Sub-application package address, e.g., packages/subapp
params	object	{}	No	Represents a query object
url	string	''	No	Supports protocol-based redirection. When a url is passed, pageId is parsed as the page path and does not need to be passed separately.
options	object	{}	No	Supports passing extended parameters on the web/mini-program sides.

Example

Basic usage:

$w.utils.navigateTo({
  pageId: pageId: 'index', // Page Id
  params: { key: 'value' }
});

Protocol-based redirection method:

// Redirect to internal page 
$w.utils.navigateTo({
  url: 'weda-page://main/index?tt=2323',
  options: {
    target: target: '_blank' // Supports opening a new window on the web
  }
});

// Redirect to external page. Only supported on the web for external links
$w.utils.navigateTo({
  url: 'https://docs.cloudbase.net/lowcode/components/wedaUI/src/docs/compsdocs/show/WdLink'
});

// Navigate to other Mini Program pages. Only supported on mobile for opening Mini Program pages.
$w.utils.navigateTo({
  url: 'miniprogram://wx1574617e567497e1/pages/register_start/index?foo=bar',
  options: {
    env_version: env_version: 'release' // The version of the Mini Program to open. Production version is 'release', trial version is 'trial', development version is 'develop'. Only effective when opened outside WeChat.
  }
});

// Redirect to Mini Program plugin page. Only supported in the Mini Program environment for opening plugin pages.
$w.utils.navigateTo({
  url: 'plugin://myPlugin/index'
});

$w.utils.redirectTo

Feature Description

Close the current page and navigate to a specific page within the app.

Input Parameters

options: object

Property	Type	Default Value	Required	Description
pageId	string	''	Required	Page id
packageName	string	''	No	Sub-application name
params	object	{}	No	query object

Example

$w.utils.redirectTo({
  pageId: pageId: 'home', // Page Id
  packageName: packageName: '', // For the main application, leave empty or unset; for submodules, enter the subpackage directory
  params: { key: 'value' }
});

$w.utils.reLaunch

Feature Description

Close all pages and open to a specific page within the app. (Due to browser limitations, you can navigate back in web environments.)

Input Parameters

options: object

Property	Type	Default Value	Required	Description
pageId	string	''	Required	Page id
packageName	string	''	No	Sub-application name
params	object	{}	No	query object

Example

$w.utils.reLaunch({
  pageId: pageId: 'home', // Page Id
  packageName: packageName: '', // For the main application, leave empty or unset; for submodules, enter the subpackage directory
  params: {}
});

$w.utils.relaunchHome

Feature Description

Return to Home

Input Parameters

None

Output Parameters

None

Example

$w.utils.relaunchHome();

$w.utils.navigateBack

Feature Description

Close the current page and return to the previous page or multiple levels.

Input Parameters

options: object

Property	Type	Default Value	Required	Description
delta	number	1	No	The number of pages to return. If delta is greater than the existing number of pages, return to the home page.

Example

$w.utils.navigateBack();

$w.utils.getEnumValue

Feature Description

Obtain the enum value by calling the method getEnumValue({ enumOptions, optionSetName, key })

Input Parameters

params: object

Property	Type	Default Value	Required	Description
enumOptions	{ key: any; value: any }[] | { response: { data: { items: any[] } }		Yes	Enumeration list or common option set interface return value
optionSetName	string		No	Option set identifier used to query the corresponding option set list in enumOptions.
key	any		No	The key or list of keys corresponding to the option value to be obtained. If not passed, all values in the option set are returned by default.

Output Parameters

result: object

Property	Type	Description
result	any | any[]	Obtained option set value

Example

// Custom enum list query
const enumOptions = [
  { key: '1', value: 'aa' },
  { key: '2', value: 'bb' }
];

// Returns the enum list if neither optionSetName nor key is passed
$w.utils.getEnumValue({ enumOptions }); 
// Result: [{label: 'aa', value: '1'}, {label: 'bb', value: '2'}]

// If optionSetName is not passed but key is passed, returns the value corresponding to the key
$w.utils.getEnumValue({ enumOptions, key: '1' }); 
// Result: 'aa'

// Common option set interface return value as the input parameter for enumOptions
const enumOptions = $w.query1.data;

// Returns the option set list object if neither optionSetName nor key is passed
$w.utils.getEnumValue({ enumOptions }); 
// Result: { sex: [{label: 'Female', value: '1'}, {label: 'Male', value: '2'}]}

// If optionSetName is passed but key is not passed, returns the option set list corresponding to the passed optionSetName
$w.utils.getEnumValue({ enumOptions, optionSetName: 'sex' }); 
// Result: [{label: 'Female', value: '1'}, {label: 'Male', value: '2'}]

// If optionSetName and key are passed, returns the value corresponding to the key in the option set list corresponding to the option identifier
$w.utils.getEnumValue({ enumOptions, optionSetName: 'sex', key: '1' }); 
// Result: 'Female'

$w.utils.getStorage

async getStorage(options: IGetStorageOptions): Promise<IGetStorageRes>

Feature Description

Asynchronously obtain the content of the specified key from the local cache, returning a Promise object

Input Parameters

options: IGetStorageOptions

Property	Type	Default Value	Required	Description
key	string		Required	The specified key in the local cache

Output Parameters

result: IGetStorageRes

Property	Type	Description
data	any	The content corresponding to the key

Example

$w.utils.getStorage({ key: 'cache_kay' }); 
// Result: { data: xxx }

$w.utils.setStorage

async setStorage(options: ISetStorageOptions): Promise<void>

Feature Description

Stores data in the specified key in the local cache, overwriting the original content corresponding to that key. The data remains available until the user actively deletes it or the system clears it due to storage space limitations. The maximum data length for a single key is 1MB, and the total storage limit is 10MB.

Input Parameters

options: ISetStorageOptions

Property	Type	Default Value	Required	Description
key	string		Required	The specified key in the local cache
data	any		Required	The content to be stored. Only native types, Date, and objects that can be serialized via JSON.stringify are supported.

Example

$w.utils.setStorage({ key: 'cache_kay', data: { test: 10 } });

$w.utils.removeStorage

async removeStorage(options: IRemoveStorageOptions): Promise<void>

Feature Description

Remove the specified key from the local cache

Input Parameters

options: IRemoveStorageOptions

Property	Type	Default Value	Required	Description
key	string		Required	The specified key in the local cache

Example

$w.utils.removeStorage({ key: 'cache_kay' });

WEB Dedicated Methods

$w.utils.exportData

Feature Description

Export data to a file

Input Parameters

options: object

Property	Type	Default Value	Required	Description
data	Object[]	[]	Required	The data to be exported, e.g.: [{name: 'sam', age: 18}]
fileName	String	'download'	No	Export file name
fileType	String	'csv'	No	Export file type, supports csv and xlsx
options	Object	{}	No	Other export options

`options.options parameter:

Property	Type	Default Value	Required	Description
sheetName	string	undefined	No	When the export type is xlsx, specifies the sheet name for the exported data

Example

$w.utils.exportData({
  data: [{ name: 'sam', age: 18 }],
  fileName: 'filename',
  fileType: 'xlsx',
  options: { sheetName: 'sheet1' }
});

Mini Program Dedicated Methods

$w.utils.requestSubscribeMessage

Feature Description

Invoke the client mini program's subscription message interface and return the result of the user's subscription operation.

Input Parameters

options: object

Property	Type	Default Value	Required	Description
tmplIds	Array		Yes	List of message template IDs to subscribe to. A single call can subscribe to up to 3 messages.

Output Parameters

result: object

Property	Type	Description
res	object	Subscription result

Subscription result res object:

Property	Type	Description
[TEMPLATE_ID: string]	String	[TEMPLATE_ID] is a dynamic key, i.e., the template id. The values include: - 'accept': The user agrees to subscribe to this template message - 'reject': The user refuses to subscribe to this template message - 'ban': Indicates that it has been banned by the backend - 'acceptWithAudio': The user accepts the subscription message and has enabled voice reminders - 'filter': This template is filtered by the backend due to duplicate template titles
errMsg	String	When the API call is successful, the value of errMsg is 'requestSubscribeMessage:ok'.

Example

$w.utils.requestSubscribeMessage({
  params: {
    tmplIds: ['zun-LzcQyW-edafCVvzPkK4de2Rllr1fFpw2A_x0oXE']
  }
});

// can only be triggered by the tap event
// After being executed successfully, return
// {
//   res: {
//     errMsg: 'requestSubscribeMessage:ok',
//     zun-LzcQyW-edafCVvzPkK4de2Rllr1fFpw2A_x0oXE: 'accept'
//   }
// }

$w.utils.openLocation

Feature Description

Use the WeChat built-in map to view location

Input Parameters

options: object

Property	Type	Default Value	Required	Description
latitude	number		Yes	Latitude, ranging from -90 to 90. Negative values indicate south latitude. Uses the GCJ-02 coordinate system.
longitude	number		Yes	Longitude, ranging from -180 to 180. Negative values indicate west longitude. Uses the GCJ-02 coordinate system.
scale	number	18	No	Scale, ranging from 5 to 18
name	string		No	Location name
address	string		No	Detailed description of the address

Output Parameters

None

Example

$w.utils.openLocation({
  latitude: 39.92,
  longitude: 116.46,
  scale: 18,
  name: name: 'Beijing',
  address: address: 'Beijing'
});

$w.utils.reserveChannelsLive

Feature Description

Schedule a Channels Live

Input Parameters

options: object

Property	Type	Default Value	Required	Description
noticeId	string		Required	Notice id, obtained via the getChannelsLiveNoticeInfo interface

Output Parameters

result: object

Property	Type	Description
state	number	User's reservation result: - state = 1: Live in progress, user clicked "Cancel" to decline going to the live stream - state = 2: Live in progress, user clicked "Allow" to go to the live stream - state = 3: Notice has been canceled - state = 4: Live has ended - state = 5: User had not reserved previously, closed the pop-up directly without reserving - state = 6: User had not reserved previously, reserved the live stream in the pop-up - state = 7: User had reserved previously, canceled the reservation in the pop-up - state = 8: User had reserved previously, closed the pop-up directly - state = 9: User canceled directly before the pop-up was triggered - state = 10: Live reservation has expired

Example

$w.utils.reserveChannelsLive({
  params: {
    noticeId: 'xxxxxxxxxxxxx'
  }
});

$w.utils.openChannelsUserProfile

Feature Description

Open the Channels Live homepage

Input Parameters

options: object

Property	Type	Default Value	Required	Description
finderUserName	string		Required	Channels id

Output Parameters

None

Example

$w.utils.openChannelsUserProfile({
  finderUserName: 'sphxxxxxxxxxxxxx'
});

$w.utils.openChannelsLive

Feature Description

Open the Channels Live stream

Input Parameters

options: object

Property	Type	Default Value	Required	Description
finderUserName	string		Required	Channels id
feedId	string		No	Live feedId, obtained via the getChannelsLiveInfo interface
nonceId	string		No	Live nonceId, obtained via the getChannelsLiveInfo interface

Output Parameters

None

Example

$w.utils.openChannelsLive({
  finderUserName: 'sphxxxxxxxxxxxxx'
});

$w.utils.openChannelsEvent

Feature Description

Open the Channels Live Activity page

Input Parameters

options: object

Property	Type	Default Value	Required	Description
finderUserName	string		Required	Channels id
eventId	string		Required	Activity id

Output Parameters

None

Example

$w.utils.openChannelsEvent({
  finderUserName: 'sphxxxxxxxxxxxxx',
  eventId: 'event/ULEZgBPE26EcB1M9DtqAzNPgMJqg8sGefrd7RCKj5fFUerYjasdasdasd'
});

$w.utils.openChannelsActivity

Feature Description

Open the Channels video

Input Parameters

options: object

Property	Type	Default Value	Required	Description
finderUserName	string		Required	Channels id
feedId	string		Required	Video feedId

Output Parameters

None

Example

$w.utils.openChannelsActivity({
  finderUserName: 'sphxxxxxxxxxxxxx',
  feedId: 'xxxxxxx'
});

$w.utils.getChannelsLiveNoticeInfo

Feature Description

Retrieve Channels livestream preview information

Input Parameters

options: object

Property	Type	Default Value	Required	Description
finderUserName	string		Required	Channels id

Output Parameters

result: object

Property	Type	Description
noticeId	string	Notice id
status	number	Notice status: 0 Available, 1 Cancelled, 2 Used
startTime	string	Start time
headUrl	string	Cover
nickname	string	Channels nickname
reservable	boolean	Reservable
otherInfos	Array	The list of other notice information except the most recent one. Note: At most 15 notice entries are returned in ascending order by timestamp each time. The most recent notice is displayed in other response parameters of the interface, and the remaining notices are displayed in this field.

Example

$w.utils.getChannelsLiveNoticeInfo({
  params: { finderUserName: 'sphxxxxxxxxxxxxx' }
});

$w.utils.getChannelsLiveInfo

Feature Description

Obtain Channels livestream information

Input Parameters

options: object

Property	Type	Default Value	Required	Description
finderUserName	string		Required	Channels id
startTime	number		No	Start time, which filters livestreams within a specified time range. If endTime is provided but startTime is not, startTime defaults to 0.
endTime	number		No	End time, which filters livestreams within a specified time range. If startTime is provided but endTime is not, endTime defaults to the current time.

Output Parameters

result: object

Property	Type	Description
feedId	string	Livestream feedId
noticeId	string	Livestream id
description	string	Livestream topic

Output Parameters | headUrl | string | Channels avatar | | nickname | string | Channels nickname | | replayStatus | string | Livestream replay status: 0: Not generated, 1: Generated, 3: Generating, 6: Expired | | otherInfos | Array | The list of other livestreams except the most recent one. Note: At most 15 livestream entries are returned in ascending order by timestamp each time. The most recent livestream is displayed in other response parameters of the interface, and the remaining livestreams are displayed in this field. |

Example

$w.utils.getChannelsLiveInfo({
  params: { finderUserName: 'sphxxxxxxxxxxxxx' }
});