工具/交互方法

通用方法

$w.utils.showToast

$w.utils.showToast(options):void

功能描述

显示提示框

入参

options: object

属性	类型	默认值	必填	说明
title	title		是	提示的内容
icon	string	'success'	否	图标
image	string		否	自定义图标的本地路径或 url ，image 的优先级高于 icon
duration	number	1500	否	提示的延迟时间（毫秒）

入参 object.icon 的合法值：

值	说明
success	显示成功图标，此时 title 文本最多显示 7 个汉字长度
error	显示失败图标，此时 title 文本最多显示 7 个汉字长度
loading	显示加载图标，此时 title 文本最多显示 7 个汉字长度
none	不显示图标，此时 title 文本最多可显示两行，1.9.0 及以上版本支持

示例

$w.utils.showToast({
  title: "成功",
  icon: "success",
  duration: 2000, // 2秒
});

$w.utils.showToast({
  title: "失败",
  icon: "error",
  duration: 2000, // 2秒
});

$w.utils.showLoading

功能描述

显示 loading 提示框。需主动调用 $w.utils.hideLoading 才能关闭提示框。

入参

options: object

属性	类型	默认值	必填	说明
title	string		false	提示的内容
mask	boolean		false	移动端是否显示透明蒙层（移动端显示透明蒙层可以防止触摸穿透，PC 端不受此配置影响）

示例

$w.utils.showLoading({
  title: "加载中",
  mask: false,
});

showLoading 弹窗样式

showLoading 弹窗提供了相关的 className，可以用来自定义弹窗的相关样式（不支持微信小程序），具体如下：

className	说明
.wd-toast	可以为根节点设置样式
.wd-toast__mask	可以为透明蒙层设置样式
.wd-toast__body	可以为主体内容设置样式
.wd-toast__icon	可以为 loading 图标设置样式
.wd-toast__title	可以为 loading 标题设置样式

$w.utils.hideLoading

功能描述

隐藏 loading 提示框。

示例

$w.utils.hideLoading();

$w.utils.showModal

$w.utils.showModal(options):void

功能描述

显示模态对话框。

入参

options: object

属性	类型	默认值	必填	说明
title	string		否	提示的标题
content	string		否	提示的内容
showCancel	boolean	true	否	是否显示取消按钮
cancelText	string	'取消'	否	取消按钮的文字，最多 4 个字符
cancelColor	string	#000000	否	取消按钮的文字颜色，必须是 16 进制格式的颜色字符串
confirmText	string	'确定'	否	确认按钮的文字，最多 4 个字符
confirmColor	string	#576B95	否	确认按钮的文字颜色，必须是 16 进制格式的颜色字符串
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行）

入参 object.success 回调函数：

属性	类型	说明
content	string	editable 为 true 时，用户输入的文本
confirm	boolean	为 true 时，表示用户点击了确定按钮
cancel	boolean	为 true 时，表示用户点击了取消

示例

$w.utils.showModal({
  title: "提示",
  content: "这是一个模态弹窗",
  success(res) {
    if (res.confirm) {
      console.log("用户点击确定");
    } else if (res.cancel) {
      console.log("用户点击取消");
    }
  },
});

$w.utils.callPhone

功能描述

拨打电话

入参

options: object

属性	类型	默认值	必填	说明
tel	string		是	电话号码

示例

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

$w.utils.scanCode

功能描述

调起扫码界面进行扫码

入参

options: object

属性	类型	默认值	必填	说明
onlyFromCamera	boolean	false	否	是否只能从相机扫码，不允许从相册选择图片
scanType	string[]	['barCode', 'qrCode']	否	扫码类型
success	function		否	接口调用成功的回调函数
fail	function		否	接口调用失败的回调函数
complete	function		否	接口调用结束的回调函数（调用成功、失败都会执行）

scanType 的值有：

合法值	说明
barCode	条码
qrCode	二维码

出参

入参为 object 类型：

属性	类型	说明
result	string	所扫码的内容
scanType	string[]	所扫码的类型

示例

// 只允许从相机扫码
$w.utils.scanCode({
  onlyFromCamera: true,
  success: (res) => {
    console.log(res);
  },
});

$w.utils.setClipboardData

功能描述

设置系统剪贴板的内容

浏览器安全限制

由于浏览器安全限制，该方法不能完全静默触发，只在点击等交互动事件触发时开启的一个窗口期内有效。例如：页面 load 生命周期内调用无效，在组件点击事件触发后，先异步请求一个接口，之后再设置剪贴板也可能无效（异步请求数据时间较长时，点击触发的激活过期，此时无法再访问剪贴板）。

小程序无特别的限制。

入参

options: object

属性	类型	默认值	必填	说明
data	string	''	是	剪贴板的内容

示例

$w.utils.setClipboardData({
  data: "复制内容到剪贴板",
});

$w.utils.navigateTo

功能描述

保留当前页面，跳转到应用内的某个页面。但是不允许跳转到 tabbar 页面。

入参

options: object

属性	类型	默认值	必填	说明
pageId	string	''	是	页面 id
packageName	string	''	否	子应用包地址，例如 packages/subapp
params	object	{}	否	query object 对象

示例

$w.utils.navigateTo({
  pageId: "index", // 页面 Id
  params: { key: "value" },
});

$w.utils.redirectTo

功能描述

关闭当前页面，跳转到应用内的某个页面。

入参

入参为 object 类型：

属性	类型	默认值	必填	说明
pageId	string	''	是	页面 id
packageName	string	''	否	子应用名称
params	object	{}	否	query object 对象

示例

$w.utils.redirectTo({
  pageId: "home", // 页面 Id
  packageName: "", // 主应用为空或不填，子模块填写 子包目录，查找位置 子包编辑器 --- 页面 --- 子包目录
  params: { key: "value" },
});

$w.utils.reLaunch

功能描述

关闭所有页面，打开到应用内的某个页面（因浏览器限制，web 下能后退页面）

入参

options: object

属性	类型	默认值	必填	说明
pageId	string	''	是	页面 id
packageName	string	''	否	子应用名称
params	object	{}	否	query object 对象

示例

$w.utils.reLaunch({
  pageId: "home", // 页面 Id
  packageName: "", // 主应用为空或不填，子模块填写 子包目录，查找位置 子包编辑器 --- 页面 --- 子包目录
  params: {},
});

$w.utils.relaunchHome

功能描述

返回首页

入参

无

出参

无

示例

$w.utils.relaunchHome();

$w.utils.navigateBack

功能描述

关闭当前页面，返回上一页面或多级页面。

入参

options: object

属性	类型	默认值	必填	说明
delta	number	1	否	返回的页面数，如果 delta 大于现有页面数，则返回到首页。

示例

$w.utils.navigateBack();

$w.utils.getEnumValue

功能描述

获取枚举值，调用方法为 getEnumValue({ enumOptions, optionSetName, key })

入参

params: object

属性	类型	默认值	必填	说明
enumOptions	{ key: any; value: any }[] | { response: { data: { items: any[] } }		是	枚举列表或通用选项集接口返回值
optionSetName	string		否	选项集标识，查询 enumOptions 中对应的选项集列表
key	any		否	要获取的选项值对应的 key 或 key 列表，不传时默认返回选项集中的所有值

出参

result: object

属性	类型	说明
result	any | any[]	获取到的选项集值

示例

/**
 * 自定义枚举列表查询
 */
const enumOptions = [
  { key: "1", value: "aa" },
  { key: "2", value: "bb" },
];
// 不传入optionSetName和key，则返回枚举列表
$w.utils.getEnumValue({ enumOptions }); // result: [{label: 'aa', value: '1'}, {label: 'bb', value: '2'}]
// 不传入optionSetName，传入key，则返回对应key的值
$w.utils.getEnumValue({ enumOptions, key: "1" }); // result: 'aa'

/**
 * 通用选项集接口返回值作为enumOptions入参
 */
const enumOptions = $w.query1.data;
// 不传入optionSetName和key，则返回选项集列表对象
$w.utils.getEnumValue({ enumOptions }); // result: { sex: [{label: '女', value: '1'}, {label: '男', value: '2'}]}
// 传入optionSetName，不传入key，则返回对应选项标识的选项集列表
$w.utils.getEnumValue({ enumOptions, optionSetName: "sex" }); // result: [{label: '女', value: '1'}, {label: '男', value: '2'}]
// 传入optionSetName和key，则返回对应选项标识的选项集列表中对应key的值
$w.utils.getEnumValue({ enumOptions, optionSetName: "sex", key: "1" }); // result: '女'

$w.utils.getStorage

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

功能描述

从本地缓存中异步获取指定 key 的内容。返回 Promise 对象

入参

params: IGetStorageOptions

属性	类型	默认值	必填	说明
key	string		是	本地缓存中指定的 key

出参

result: IGetStorageRes

属性	类型	说明
data	any	key 对应的内容

示例

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

$w.utils.setStorage

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

功能描述

将数据存储在本地缓存中指定的 key 中。会覆盖掉原来该 key 对应的内容。除非用户主动删除或因存储空间原因被系统清理，否则数据都一直可用。单个 key 允许存储的最大数据长度为 1MB，所有数据存储上限为 10MB。

入参

params: ISetStorageOptions

属性	类型	默认值	必填	说明
key	string		是	本地缓存中指定的 key
data	any		是	需要存储的内容。只支持原生类型、Date、及能够通过 JSON.stringify 序列化的对象。

示例

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

$w.utils.removeStorage

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

功能描述

从本地缓存中移除指定 key，调用方法为 removeStorage({ key })

入参

params: IRemoveStorageOptions

属性	类型	默认值	必填	说明
key	string		是	本地缓存中指定的 key

示例

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

WEB 专属方法

$w.utils.exportData

功能描述

导出数据保存为文件

入参

options: object

属性	类型	默认值	必填	说明
data	Object[]	[]	是	需要导出的数据，如：[{name: 'sam', age: 18}]
fileName	String	'download'	否	导出文件名
fileType	String	'csv'	否	导出文件类型，支持 csv 与 xlsx
options	Object	{}	否	其他导出选项

options.options object

属性	类型	默认值	必填	说明
sheetName	string	undefined	否	当导出类型为 xlsx 时，指定导出数据的 sheet 名

示例

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

小程序专属方法

$w.utils.requestSubscribeMessage

功能描述

调起客户端小程序订阅消息界面，返回用户订阅消息的操作结果

入参

options: object

属性	类型	默认值	必填	说明
tmplIds	Array		是	需要订阅的消息模板的 id 的集合，一次调用最多可订阅 3 条消息。

出参

options: object

属性	类型	说明
res	object	订阅结果

订阅结果 res: object

属性	类型	说明
[TEMPLATE_ID: string]	String	[TEMPLATE_ID]是动态的键，即模板 id，值包括'accept'、'reject'、'ban'、'filter'、'acceptWithAudio'。'accept'表示用户同意订阅该条 id 对应的模板消息，'reject'表示用户拒绝订阅该条 id 对应的模板消息，'ban'表示已被后台封禁，'acceptWithAudio' 表示用户接收订阅消息并开启了语音提醒，'filter'表示该模板因为模板标题同名被后台过滤。例如 { errMsg: 'requestSubscribeMessage:ok', zun-LzcQyW-edafCVvzPkK4de2Rllr1fFpw2A_x0oXE: 'accept'} 表示用户同意订阅 zun-LzcQyW-edafCVvzPkK4de2Rllr1fFpw2A_x0oXE 这条消息。
errMsg	String	接口调用成功时 errMsg 值为'requestSubscribeMessage:ok'

示例

$w.utils.requestSubscribeMessage({
  params: {
    tmplIds: ["zun-LzcQyW-edafCVvzPkK4de2Rllr1fFpw2A_x0oXE"],
  },
});
// 只能通过 tap 事件触发
// 执行成功后返回
// {
//   res: {
//     errMsg: 'requestSubscribeMessage:ok',
//     zun-LzcQyW-edafCVvzPkK4de2Rllr1fFpw2A_x0oXE: 'accept'
//   }
// }

$w.utils.openLocation

功能描述

使用微信内置地图查看位置

入参

options: object

属性	类型	默认值	必填	说明
latitude	number		是	纬度，范围为-90~90，负数表示南纬。使用 gcj02 国测局坐标系
longitude	number		是	经度，范围为-180~180，负数表示西经。使用 gcj02 国测局坐标系
scale	number	18	否	缩放比例，范围 5~18
name	number		否	位置名
address	number		否	地址的详细说明

出参

无

示例

$w.utils.openLocation({
  latitude: 39.92,
  longitude: 116.46,
  scale: 18,
  name: "北京",
  address: "北京市",
});

$w.utils.reserveChannelsLive

功能描述

预约视频号直播

入参

options: object

属性	类型	默认值	必填	说明
noticeId	string		是	预告 id，通过 getChannelsLiveNoticeInfo 接口获取

出参

options: object

属性	类型	说明
state	number	用户的预约结果 state = 1，正在直播中，用户点击“取消”拒绝前往直播 state = 2，正在直播中，用户点击“允许”前往直播 state = 3，预告已取消 state = 4，直播已结束 state = 5，用户此前未预约，在弹窗中未预约直播直接收起弹窗 state = 6，用户此前未预约，在弹窗中预约了直播 state = 7，用户此前已预约，在弹窗中取消了预约 state = 8，用户此前已预约，直接收起弹窗 state = 9，弹窗唤起前用户直接取消 state = 10，直播预约已过期

示例

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

$w.utils.openChannelsUserProfile

功能描述

打开视频号主页

入参

options: object

属性	类型	默认值	必填	说明
finderUserName	string		是	视频号 id

出参

无

示例

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

$w.utils.openChannelsLive

功能描述

打开视频号直播

入参

options: object

属性	类型	默认值	必填	说明
finderUserName	string		是	视频号 id
feedId	string		否	直播 feedId，通过 getChannelsLiveInfo 接口获取
nonceId	string		否	直播 nonceId，通过 getChannelsLiveInfo 接口获取

出参

无

示例

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

$w.utils.openChannelsEvent

功能描述

打开视频号活动页

入参

options: object

属性	类型	默认值	必填	说明
finderUserName	string		是	视频号 id
eventId	string		是	活动 id

出参

无

示例

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

$w.utils.openChannelsActivity

功能描述

打开视频号视频

入参

options: object

属性	类型	默认值	必填	说明
finderUserName	string		是	视频号 id
feedId	string		是	视频 feedId

出参

无

示例

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

$w.utils.getChannelsLiveNoticeInfo

功能描述

获取视频号直播预告信息

入参

options: object

属性	类型	默认值	必填	说明
finderUserName	string		是	视频号 id

出参

options: object

属性	类型	说明
noticeId	string	预告 id
status	number	预告状态：0 可用 1 取消 2 已用
startTime	string	开始时间
headUrl	string	直播封面
nickname	string	视频号昵称
reservable	boolean	是否可预约
otherInfos	Array	除最近的一条预告信息外，其他的预告信息列表（注意：每次最多返回按时间戳增序排列的 15 个预告信息，其中时间最近的那个预告信息会在接口其他的返回参数中展示，其余的预告信息会在该字段中展示）。

示例

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

$w.utils.getChannelsLiveInfo

功能描述

获取视频号直播信息

入参

options: object

属性	类型	默认值	必填	说明
finderUserName	string		是	视频号 id
startTime	number		否	起始时间，筛选指定时间段的直播。若上传了 endTime，未上传 startTime，则 startTime 默认为 0
endTime	number		否	结束时间，筛选指定时间段的直播。若上传了 startTime，未上传 endTime，则 endTime 默认取当前时间

出参

options: object

属性	类型	说明
feedId	string	直播 feedId
noticeId	string	直播 id
description	string	直播主题
status	number	直播状态：2 直播中 3 直播结束
headUrl	string	视频号头像
nickname	string	视频号昵称
replayStatus	string	直播回放状态: 0 未生成 1 已生成 3 生成中 6 已过期
otherInfos	Array	除最近的一条直播外，其他的直播列表（注意：每次最多返回按时间戳增序排列的 15 个直播信息，其中时间最近的那个直播会在接口其他的返回参数中展示，其余的直播会在该字段中展示）。	、

示例

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