工具/交互方法

通用方法

$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	提示的内容

示例

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

$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: '女'

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' },
});