canIUse
该 API 使用方法为 Boolean wx.canIUse(string schema)
功能说明:判断小程序的 API,回调,参数,组件等是否在当前版本可用。
参数及说明:String schema
使用
${API}.${method}.${param}.${options}
或者 ${component}.${attribute}.${option}
方式来调用。参数说明:
参数值 | 说明 |
${API} | 代表 API 名字 |
${method} | 代表调用方式,有效值为 return,success,object,callback |
${param} | 代表参数或者返回值 |
${options} | 代表参数的可选值 |
${component} | 代表组件名字 |
${attribute} | 代表组件属性 |
${option} | 代表组件属性的可选值 |
返回值:Boolean,表达当前版本是否可用。
示例代码:
wx.canIUse('openBluetoothAdapter')wx.canIUse('getSystemInfoSync.return.screenWidth')wx.canIUse('getSystemInfo.success.screenWidth')wx.canIUse('showToast.object.image')wx.canIUse('onCompassChange.callback.direction')wx.canIUse('request.object.method.GET')wx.canIUse('live-player')wx.canIUse('text.selectable')wx.canIUse('button.open-type.contact')
env
该 API 使用方法为 wx.env
功能说明:环境变量。
参数及说明:string USER_DATA_PATH,文件系统中的用户目录路径(本地路径)。
base64ToArrayBuffer
该 API 使用方法为 ArrayBuffer wx.base64ToArrayBuffer(string base64)
功能说明:将 Base64 字符串转成 ArrayBuffer 对象。
参数及说明:string base64,要转化成 ArrayBuffer 对象的 Base64 字符串。
返回值:ArrayBuffer,ArrayBuffer 对象。
示例代码:
const base64 = 'CxYh'const arrayBuffer = wx.base64ToArrayBuffer(base64)
arrayBufferToBase64
该 API 使用方法为 string wx.arrayBufferToBase64(ArrayBuffer arrayBuffer)
功能说明:将 ArrayBuffer 对象转成 Base64 字符串。
参数及说明:ArrayBuffer arrayBuffer,要转换成 Base64 字符串的 ArrayBuffer 对象。
返回值:string,Base64 字符串。
示例代码:
const arrayBuffer = new Uint8Array([11, 22, 33])const base64 = wx.arrayBufferToBase64(arrayBuffer)
系统
getSystemInfo
该 API 使用方法为 wx.getSystemInfo(Object object)
功能说明:获取系统信息。
参数及说明:Object Object。
属性 | 类型 | 默认值 | 必填 | 说明 |
success | Function | - | 否 | 接口调用成功的回调函数 |
fail | Function | - | 否 | 接口调用失败的回调函数 |
complete | Function | - | 否 | 接口调用结束的回调函数(无论成功与否都执行) |
Object.success 的 res 回调结果
属性 | 类型 | 说明 |
brand | String | 设备品牌 |
model | String | 设备型号 |
pixelRatio | Number | 设备像素比 |
screenWidth | Number | 屏幕宽度,单位 px |
screenHeight | Number | 屏幕高度,单位 px |
windowWidth | Number | 可使用窗口宽度,单位 px |
windowHeight | Number | 可使用窗口高度,单位 px |
statusBarHeight | Number | 状态栏的高度,单位 px |
language | String | 语言 |
version | String | 版本号 |
system | String | 操作系统及版本 |
platform | String | 客户端平台,其合法值如下 ios:iOS 客户端(包含 iPhone、iPad) android:Android 客户端 devtools:TCMPP 开发者工具 |
SDKVersion | String | 客户端基础库版本 |
AppPlatform | String | App 平台 |
safeArea | Object | 在竖屏正方向下的安全区域 |
theme | String | 系统当前主题, 取值为 light 或 dark ,全局配置"darkmode":true 时才能获取,否则为 undefined |
res.safeArea 的结构:
属性 | 类型 | 说明 |
left | Number | 安全区域左上角横坐标 |
right | Number | 安全区域右下角横坐标 |
top | Number | 安全区域左上角纵坐标 |
bottom | Number | 安全区域右下角纵坐标 |
width | Number | 安全区域的宽度,单位逻辑像素 |
height | Number | 安全区域的高度,单位逻辑像素 |
示例代码:
wx.getSystemInfo({success(res) {console.log(res.model)console.log(res.pixelRatio)console.log(res.windowWidth)console.log(res.windowHeight)console.log(res.language)console.log(res.version)console.log(res.platform)}})
try {const res = wx.getSystemInfoSync()console.log(res.model)console.log(res.pixelRatio)console.log(res.windowWidth)console.log(res.windowHeight)console.log(res.language)console.log(res.version)console.log(res.platform)} catch (e) {// Do something when catch error}
getSystemInfoSync
该 API 使用方法为 Object wx.getSystemInfoSync()
功能说明:wx.getSystemInfo 的同步版本。
Object.success 的 res 回调结果
属性 | 类型 | 说明 |
brand | String | 设备品牌 |
model | String | 设备型号 |
pixelRatio | Number | 设备像素比 |
screenWidth | Number | 屏幕宽度,单位 px |
screenHeight | Number | 屏幕高度,单位 px |
windowWidth | Number | 可使用窗口宽度,单位 px |
windowHeight | Number | 可使用窗口高度,单位 px |
statusBarHeight | Number | 状态栏的高度,单位 px |
language | String | 语言 |
version | String | 版本号 |
system | String | 操作系统及版本 |
platform | String | 客户端平台,其合法值如下 ios:iOS 客户端(包含 iPhone、iPad) android:Android 客户端 devtools:TCMPP 开发者工具 |
SDKVersion | String | 客户端基础库版本 |
AppPlatform | String | App 平台 |
safeArea | Object | 在竖屏正方向下的安全区域 |
theme | String | 系统当前主题, 取值为 light 或 dark ,全局配置"darkmode":true 时才能获取,否则为 undefined |
res.safeArea 的结构:
属性 | 类型 | 说明 |
left | Number | 安全区域左上角横坐标 |
right | Number | 安全区域右下角横坐标 |
top | Number | 安全区域左上角纵坐标 |
bottom | Number | 安全区域右下上角纵坐标 |
width | Number | 安全区域的宽度,单位逻辑像素 |
height | Number | 安全区域的高度,单位逻辑像素 |
示例代码:
wx.getSystemInfo({success(res) {console.log(res.model)console.log(res.pixelRatio)console.log(res.windowWidth)console.log(res.windowHeight)console.log(res.language)console.log(res.version)console.log(res.platform)}})
try {const res = wx.getSystemInfoSync()console.log(res.model)console.log(res.pixelRatio)console.log(res.windowWidth)console.log(res.windowHeight)console.log(res.language)console.log(res.version)console.log(res.platform)} catch (e) {// Do something when catch error}
getSystemInfoAsync
该 API 使用方法为 wx.getSystemInfoAsync(Object object)
功能说明:异步获取系统信息。需要一定的宿主客户端版本支持,在不支持的客户端上,会使用同步实现来返回。
参数及说明:Object object。
属性 | 类型 | 默认值 | 必填 | 说明 |
success | function | - | 否 | 接口调用成功的回调函数 |
fail | function | - | 否 | 接口调用失败的回调函数 |
complete | function | - | 否 | 接口调用结束的回调函数(调用成功、失败都会执行) |
object.success 回调函数参数:Object res
属性 | 类型 | 说明 |
brand | string | 设备品牌 |
model | string | 设备型号。新机型刚推出一段时间会显示 unknown,我们会尽快进行适配 |
pixelRatio | number | 设备像素比 |
screenWidth | number | 屏幕宽度,单位 px |
screenHeight | number | 屏幕高度,单位 px |
windowWidth | number | 可使用窗口宽度,单位 px |
windowHeight | number | 可使用窗口高度,单位 px |
statusBarHeight | number | 任务状态栏高度,单位 px |
language | string | 应用内设置的语言 |
version | string | 应用版本号 |
system | string | 操作系统及版本 |
platform | string | 客户端平台,其合法值为 iOS:iOS 客户端(包括 iPhone、iPad) Android:Android 客户端 Windows:Windows 客户端 Mac:MacOS 客户端 devtools:IDE 开发者工具 |
fontSizeSetting | number | 用户字体大小,单位 px |
SDKVersion | string | 客户端基础库版本 |
benchmarkLevel | number | 设备性能等级(仅 Android)。取值为: -2 或 0(该设备无法运行小游戏) -1(性能未知) >=1(设备性能值,该值越高,设备性能越好,目前最高不到50) |
albumAuthorized | boolean | 允许客户端使用相册的开关(仅 iOS 有效) |
albumAuthorized | boolean | 允许无需使用摄像头的开关 |
locationAuthorized | boolean | 允许客户端使用定位的开关 |
microphoneAuthorized | boolean | 允许客户端使用麦克风的开关 |
notificationAuthorized | boolean | 允许客户端通知的开关 |
notificationAlertAuthorized | boolean | 允许客户端通知带有提醒的开关(仅 iOS 有效) |
notificationBadgeAuthorized | boolean | 允许客户端通知带有标记的开关(仅 iOS 有效) |
notificationSoundAuthorized | boolean | 允许客户端通知带有声音的开关(仅 iOS 有效) |
phoneCalendarAuthorized | boolean | 允许客户端使用日历的开关 |
bluetoothEnabled | boolean | 蓝牙的系统开关 |
locationEnabled | boolean | 地理位置的系统开关 |
wifiEnabled | boolean | Wi-Fi 的系统开关 |
safeArea | object | 在竖屏正方向下的安全区域。部分机型没有安全区域概念,也不会返回 safeArea 字段,开发者需自行兼容。返回值请参考下表 safeArea 返回值 |
locationReducedAccuracy | boolean | `true` 表示模糊定位,`false` 表示精确定位,仅 iOS 支持 |
theme | string | 系统当前主题,全局配置 darkmode:true 时才能获取,否则为 undefined (不支持小游戏),其合法值为 light:明亮 dark:黑暗 |
host | object | 当前小程序运行的宿主环境。结构为 string类型的 appid,表示客户端 App 对应的 appid |
enableDebug | boolean | 是否已打开调试。可通过右上角菜单或 wx.setEnableDebug 打开调试 |
deviceOrientation | string | 设备方向: portrait:竖屏 landscape:横屏 |
safeArea 返回值
结构属性 | 类型 | 说明 |
left | number | 安全区域左上角横坐标 |
right | number | 安全区域右下角横坐标 |
top | number | 安全区域左上角纵坐标 |
bottom | number | 安全区域右下角纵坐标 |
width | number | 安全区域的宽度,单位逻辑像素 |
height | number | 安全区域的高度,单位逻辑像素 |
示例代码:
wx.getSystemInfoAsync({success (res) {console.log(res.model)console.log(res.pixelRatio)console.log(res.windowWidth)console.log(res.windowHeight)console.log(res.language)console.log(res.version)console.log(res.platform)}})
getWindowInfo
该 API 使用方法为 Object wx.getWindowInfo()
功能说明:获取窗口信息。
参数及说明:Object。
属性 | 类型 | 说明 |
pixelRatio | number | 设备像素比 |
screenWidth | number | 屏幕宽度,单位 px |
screenHeight | number | 屏幕高度,单位 px |
windowWidth | number | 可使用窗口宽度,单位 px |
windowHeight | number | 可使用窗口高度,单位 px |
statusBarHeight | number | 状态栏的高度,单位 px |
safeArea | object | 在竖屏正方向下的安全区域。部分机型没有安全区域概念,也不会返回 safeArea 字段,开发者需自行兼容 |
screenTop | number | 窗口上边缘的 y 值 |
safeArea 返回值
结构属性 | 类型 | 说明 |
left | number | 安全区域左上角横坐标 |
right | number | 安全区域右下角横坐标 |
top | number | 安全区域左上角纵坐标 |
bottom | number | 安全区域右下角纵坐标 |
width | number | 安全区域的宽度,单位逻辑像素 |
height | number | 安全区域的高度,单位逻辑像素 |
示例代码:
const windowInfo = wx.getWindowInfo()console.log(windowInfo.pixelRatio)console.log(windowInfo.screenWidth)console.log(windowInfo.screenHeight)console.log(windowInfo.windowWidth)console.log(windowInfo.windowHeight)console.log(windowInfo.statusBarHeight)console.log(windowInfo.safeArea)console.log(windowInfo.screenTop)
getSystemSetting
该 API 使用方法为 Object wx.getSystemSetting()
功能说明:获取设备设置。
参数及说明:Object。
属性 | 类型 | 说明 |
bluetoothEnabled | boolean | 蓝牙的系统开关 |
locationEnabled | boolean | 地理位置的系统开关 |
wifiEnabled | boolean | Wi-Fi 的系统开关 |
deviceOrientation | string | 设备方向,其合法值为: portrait:竖屏 landscape:横屏 |
示例代码:
const systemSetting = wx.getSystemSetting()console.log(systemSetting.bluetoothEnabled)console.log(systemSetting.deviceOrientation)console.log(systemSetting.locationEnabled)console.log(systemSetting.wifiEnabled)
openSystemBluetoothSetting
该 API 使用方法为 wx.openSystemBluetoothSetting(Object object)
功能说明:跳转系统蓝牙设置页。仅支持 Android 。
参数及说明:Object object。
属性 | 类型 | 默认值 | 必填 | 说明 |
success | function | - | 否 | 接口调用成功的回调函数 |
fail | function | - | 否 | 接口调用失败的回调函数 |
complete | function | - | 否 | 接口调用结束的回调函数(调用成功、失败都会执行) |
示例代码:
wx.openSystemBluetoothSetting({success (res) {console.log(res)}})
openAppAuthorizeSetting
该 API 使用方法为 wx.openAppAuthorizeSetting(Object object)
功能说明:跳转系统宿主客户端授权管理页。
参数及说明:Object object。
属性 | 类型 | 默认值 | 必填 | 说明 |
success | function | - | 否 | 接口调用成功的回调函数 |
fail | function | - | 否 | 接口调用失败的回调函数 |
complete | function | - | 否 | 接口调用结束的回调函数(调用成功、失败都会执行) |
示例代码:
wx.openAppAuthorizeSetting({success (res) {console.log(res)}})
getRendererUserAgent
该 API 使用方法为 Promise wx.getRendererUserAgent(Object object)
功能说明:获取 Webview 小程序的 UserAgent。
参数及说明:Object object。
属性 | 类型 | 默认值 | 必填 | 说明 |
success | function | - | 否 | 接口调用成功的回调函数 |
fail | function | - | 否 | 接口调用失败的回调函数 |
complete | function | - | 否 | 接口调用结束的回调函数(调用成功、失败都会执行) |
object.success 回调函数参数:string userAgent,UserAgent。
返回值:Promise.<string>。
示例代码:
wx.getRendererUserAgent().then(userAgent => console.log(userAgent))wx.getRendererUserAgent({success(res) { console.log(res.userAgent) }})
getDeviceInfo
该 API 使用方法为 Object wx.getDeviceInfo()
功能说明:获取设备基础信息。
返回值:Object。
属性 | 类型 | 说明 |
abi | string | 宿主 App 二进制接口类型(仅 Android 支持) |
deviceAbi | string | 设备二进制接口类型(仅 Android 支持) |
benchmarkLevel | number | 设备性能等级(仅 Android 支持),合法值为: -2 或 0:该设备无法运行小游戏 -1:性能未知 >=1:设备性能值,该值越高,设备性能越好,目前最高不到50 |
brand | string | 设备品牌 |
model | string | 设备型号。新机型刚推出一段时间会显示 unknown,我们会尽快进行适配 |
system | string | 操作系统及版本 |
platform | string | 客户端平台 |
cpuType | string | 设备 CPU 型号(仅 Android 支持)GPU 型号可通过 WebGLRenderingContext.getExtension('WEBGL_debug_renderer_info') 来获取 |
menorySize | string | 设备内存大小,单位为 MB |
示例代码:
const deviceInfo = wx.getDeviceInfo()console.log(deviceInfo.abi)console.log(deviceInfo.benchmarkLevel)console.log(deviceInfo.brand)console.log(deviceInfo.model)console.log(deviceInfo.platform)console.log(deviceInfo.system)
getAppBaseInfo
该 API 使用方法为 Object wx.getAppBaseInfo()
功能说明:获取宿主客户端基础信息。
参数及说明:Object。
属性 | 类型 | 说明 |
SDKVersion | string | 宿主客户端基础库版本 |
enableDebug | boolean | |
host | Object | 当前小程序运行的宿主环境。 结构属性为 string 类型的 appId,用于宿主客户端(第三方 App) 对应的 appId (当小程序运行在第三方 App 环境时才返回) |
language | string | 宿主客户端设置的语言 |
version | string | 宿主客户端版本号 |
theme | string | 系统当前主题,取值为`light:明亮模式` 或 `dark:暗黑模式`,全局配置`"darkmode":true`时才能获取,否则为 undefined (不支持小游戏) |
示例代码:
const appBaseInfo = wx.getAppBaseInfo()console.log(appBaseInfo.SDKVersion)console.log(appBaseInfo.enableDebug)console.log(appBaseInfo.host)console.log(appBaseInfo.language)console.log(appBaseInfo.version)console.log(appBaseInfo.theme)
getAppAuthorizeSetting
该 API 使用方法为 Object wx.getAppAuthorizeSetting()
功能说明:获取宿主客户端授权设置。
参数及说明:Object。
属性 | 类型 | 说明 |
albumAuthorized | 'authorized'/'denied'/'not determined' | 允许宿主客户端使用相册的开关(仅 iOS 有效) |
bluetoothAuthorized | 'authorized'/'denied'/'not determined' | 允许宿主客户端使用蓝牙的开关(仅 iOS 有效) |
cameraAuthorized | 'authorized'/'denied'/'not determined' | 允许宿主客户端使用摄像头的开关 |
locationAuthorized | 'authorized'/'denied'/'not determined' | 允许宿主客户端使用定位的开关 |
locationReducedAccuracy | boolean | 定位准确度。true 表示模糊定位,false 表示精确定位(仅 iOS 有效) |
microphoneAuthorized | 'authorized'/'denied'/'not determined' | 允许宿主客户端使用麦克风的开关 |
notificationAuthorized | 'authorized'/'denied'/'not determined' | 允许宿主客户端通知的开关 |
notificationAlertAuthorized | 'authorized'/'denied'/'not determined' | 允许宿主客户端通知带有提醒的开关(仅 iOS 有效) |
notificationBadgeAuthorized | 'authorized'/'denied'/'not determined' | 允许宿主客户端通知带有标记的开关(仅 iOS 有效) |
notificationSoundAuthorized | 'authorized'/'denied'/'not determined' | 允许宿主客户端通知带有声音的开关(仅 iOS 有效) |
phoneCalendarAuthorized | 'authorized'/'denied'/'not determined' | 允许宿主客户端读写日历的开关 |
示例代码:
const appAuthorizeSetting = wx.getAppAuthorizeSetting()console.log(appAuthorizeSetting.albumAuthorized)console.log(appAuthorizeSetting.bluetoothAuthorized)console.log(appAuthorizeSetting.cameraAuthorized)console.log(appAuthorizeSetting.locationAuthorized)console.log(appAuthorizeSetting.locationReducedAccuracy)console.log(appAuthorizeSetting.microphoneAuthorized)console.log(appAuthorizeSetting.notificationAlertAuthorized)console.log(appAuthorizeSetting.notificationAuthorized)console.log(appAuthorizeSetting.notificationBadgeAuthorized)console.log(appAuthorizeSetting.notificationSoundAuthorized)console.log(appAuthorizeSetting.phoneCalendarAuthorized)
更新
getUpdateManager
该 API 使用方法为 UpdateManager wx.getUpdateManager
功能说明:获取全局唯一的版本更新管理器,用于管理小程序更新,使用方法为 UpdateManager wx.getUpdateManager。
返回值:UpdateManager,更新管理器对象。
UpdateManager
.applyUpdate
该 方法 使用方式为 UpdateManager.applyUpdate()
功能说明:强制小程序重启并使用新版本。在小程序新版本下载完成后(即收到
onUpdateReady
回调)调用。.onCheckForUpdate
该 方法 使用方式为 UpdateManager.onCheckForUpdate(function listener)
功能说明:监听向后台请求检查更新结果事件。在小程序冷启动时自动检查更新,不需由开发者主动触发。
参数及说明:function callback,向后台请求检查更新结果事件的回调函数。
属性 | 类型 | 说明 |
hasUpdate | Boolean | 是否有新版本 |
.onUpdateFailed
该 方法 使用方式为 UpdateManager.onUpdateFailed(function listener)
功能说明:监听小程序有版本更新事件。客户端主动触发下载(无需开发者触发),下载成功后回调。
参数及说明:function callback,小程序更新失败事件的回调函数。
.onUpdateReady
该 方法 使用方式为 UpdateManager.onUpdateReady(function listener)
功能说明:监听小程序更新失败事件。小程序有新版本,客户端主动触发下载(无需开发者触发),下载失败(可能是网络原因等)后回调。
参数及说明:function callback,小程序有新版本更新事件的回调函数。
示例代码:
const updateManager = wx.getUpdateManager()updateManager.onCheckForUpdate(function (res) {// 请求完新版本信息的回调console.log(res.hasUpdate)})updateManager.onUpdateReady(function () {wx.showModal({title: '更新提示',content: '新版本已经准备好,是否重启应用?',success(res) {if (res.confirm) {// 新的版本已经下载好,调用 applyUpdate 应用新版本并重启updateManager.applyUpdate()}}})})updateManager.onUpdateFailed(function () {// 新版本下载失败})
小程序
生命周期
getLaunchOptionsSync
该 API 使用方法为 Object wx.getLaunchOptionsSync()
注意:
部分版本在无
referrerInfo
的时候会返回 undefined
,建议使用options.referrerInfo && options.referrerInfo.appId
进行判断。功能说明:获取小程序启动时的参数 。
返回值:Object,启动参数。
属性 | 类型 | 说明 |
path | String | 启动小程序的路径 |
scene | Number | |
query | Object | 启动小程序的 query 参数 |
referrerInfo | Object | 来源信息,从另一个小程序、公众号或 App 进入小程序时返回。否则返回{} |
forwardMaterials | Array.<Object> | 打开的文件信息数组,只有从聊天素材场景打开(scene 为1173)才会携带该参数 |
referrerInfo 的结构
属性 | 类型 | 说明 |
appId | String | 来源小程序、公众号或 App 的 appId |
extraData | Object | 来源小程序传过来的数据,scene=1037或1038时支持 |
forwardMaterials 的结构
属性 | 类型 | 说明 |
type | string | 文件的 mimetype 类型 |
name | Object | 文件名 |
path | string | 文件路径 |
size | number | 文件大小 |
返回有效
referrerInfo
的场景属性 | 类型 | appId 含义 |
1020 | 公众号 profile 页相关小程序列表 | 来源公众号 |
1035 | 公众号自定义菜单 | 来源公众号 |
1036 | App 分享消息卡片 | 来源 App |
1037 | 小程序打开小程序 | 来源小程序 |
1038 | 从另一个小程序返回 | 来源小程序 |
1043 | 公众号模板消息 | 来源公众号 |
getEnterOptionsSync
该 API 使用方法为 Object wx.getEnterOptionsSync()
注意:
部分版本在无
referrerInfo
的时候会返回 undefined
,建议使用options.referrerInfo && options.referrerInfo.appId
进行判断。功能说明:获取本次小程序启动时的参数。如果当前是冷启动,则返回值与 App.onLaunch 的回调参数一致;如果当前是热启动,则返回值与 App.onShow 一致。
返回值:Object
属性 | 类型 | 说明 |
path | string | 启动小程序的路径(代码包路径) |
scene | number | |
query | Object | 启动小程序的 query 参数 |
shareTicket | string | |
referrInfo | Object | 来源信息。从另一个小程序、公众号或 App 进入小程序时返回。否则返回 {},具体参见表格前文的注意 |
forwardMaterials | Array.<Object> | 打开的文件信息数组,只有从聊天素材场景打开(scene为1173)才会携带该参数 |
chatType | number | 从宿主客户端群聊/单聊打开小程序时,chatType 表示具体宿主客户端里的群聊/单聊类型,合法值为: 1:宿主客户端联系人单聊 2:企业宿主客户端联系人单聊 3:普通宿主客户端群聊 4:企业宿主客户端互通群聊 |
referrerInfo 的结构
属性 | 类型 | 说明 |
appId | String | 来源小程序、公众号或 App 的 appId |
extraData | Object | 来源小程序传过来的数据,scene=1037或1038时支持 |
forwardMaterials 的结构
属性 | 类型 | 说明 |
type | String | 文件的 mimetype 类型 |
name | Object | 文件名 |
path | String | 文件路径(如果是 webview 则是 url) |
size | Number | 文件大小 |
返回有效 referrerInfo 的场景
属性 | 类型 | appId 含义 |
1020 | 公众号 profile 页相关小程序列表 | 来源公众号 |
1035 | 公众号自定义菜单 | 来源公众号 |
1036 | App 分享消息卡片 | 来源 App |
1037 | 小程序打开小程序 | 来源小程序 |
1038 | 从另一个小程序返回 | 来源小程序 |
1043 | 公众号模板消息 | 来源公众号 |
应用级事件
onError
该 API 使用方法为 wx.onError(function callback)
功能说明:监听小程序错误事件。如脚本错误或 API 调用报错等。
参数及说明:function callback,小程序错误事件的回调函数。
返回参数:string error,错误信息,包含堆栈。
offError
该 API 使用方法为 wx.offError(function callback)
功能说明:取消监听小程序错误事件。
参数及说明:function callback,小程序错误事件的回调函数。
onThemeChange
该 API 使用方法为 wx.onThemeChange(function listener)
说明:
只有在全局配置 darkmode:true 时才会触发此事件。
功能说明:监听系统主题改变事件。
参数及说明:function listener,系统主题改变事件的监听函数。
返回参数:Object res
属性 | 合法值及说明 | 类型 | 说明 |
theme | dark:深色主题 light:浅色主题 | String | 系统当前的主题,取值为 light 或 dar |
offThemeChange
该 API 使用方法为 wx.offThemeChange(function listener)
功能说明:移除系统主题改变事件的监听函数 。
参数及说明:function listener,onThemeChange 传入的监听函数。不传此参数则移除所有监听函数。
示例代码:
const listener = function (res) { console.log(res) }wx.onThemeChange(listener)wx.offThemeChange(listener) // 需传入与监听时同一个的函数对象
onPageNotFound
该 API 使用方法为 wx.onPageNotFound(function listener)
注意:
开发者可以在回调中进行页面重定向,但必须在回调中同步处理,异步处理(例如 setTimeout 异步执行)无效。
若开发者没有调用 wx.onPageNotFound 绑定监听,也没有声明 App.onPageNotFound,当跳转页面不存在时,将推入宿主客户端原生的页面不存在提示页面。
如果回调中又重定向到另一个不存在的页面,将推入宿主客户端原生的页面不存在提示页面,并且不再第二次回调。
功能说明:监听小程序要打开的页面不存在事件。该事件与 App.onPageNotFound 的回调时机一致。
参数及说明:Object res 参数,function listener,小程序要打开的页面不存在事件的监听函数。
属性 | 类型 | 说明 |
path | string | 不存在页面的路径 (代码包路径) |
query | Object | 打开不存在页面的 query 参数 |
isEntryPage | boolean | 是否本次启动的首个页面(例如从分享等入口进来,首个页面是开发者配置的分享页面) |
offPageNotFound
该 API 使用方法为 wx.offPageNotFound(function listener)
功能说明:移除小程序要打开的页面不存在事件的监听函数。
参数及说明:function listener,onPageNotFound 传入的监听函数。不传此参数则移除所有监听函数。
示例代码
const listener = function (res) { console.log(res) }wx.onPageNotFound(listener)wx.offPageNotFound(listener) // 需传入与监听时同一个的函数对象
onAppShow
该 API 使用方法为 wx.onAppShow(function listener)
注意:
部分版本在无 referrerInfo 的时候会返回 undefined,建议使用
options.referrerInfo && options.referrerInfo.appId
进行判断。功能说明:监听小程序切前台事件。该事件与 App.onShow 的回调参数一致。
参数及说明:Object res 参数,function listener,小程序切前台事件的监听函数。
属性 | 类型 | 说明 |
path | string | 启动小程序的路径(代码包路径) |
scene | number | |
query | Object | 启动小程序的 query 参数 |
shareTicket | string | shareTicket |
referrerInfo | Object | 来源信息。从另一个小程序、公众号或 App 进入小程序时返回。否则返回{},具体参见表格前文的注意 |
forwardMaterials | Array.<Object> | 打开的文件信息数组,只有从聊天素材场景打开(scene为1173)才会携带该参数 |
chatType | number | 从宿主客户端群聊/单聊打开小程序时,chatType 表示具体宿主客户端内群聊/单聊类型,合法值为: 1:宿主客户端内联系人单聊 2:宿主客户端内企业联系人单聊 3:宿主客户端内普通群聊 4:宿主客户端内企业互通群聊 |
referrerInfo 的结构
属性 | 类型 | 说明 |
appId | string | 来源小程序、公众号或 App 的 appId |
extraData | Object | 来源小程序传过来的数据,scene=1037或1038时支持 |
forwardMaterials 的结构
属性 | 类型 | 说明 |
type | String | 文件的 mimetype 类型 |
name | Object | 文件名 |
path | String | 文件路径(如果是 webview 则是 url) |
size | Number | 文件大小 |
返回有效 referrerInfo 的场景
场景值 | 场景 | appId含义 |
1020 | 公众号 profile 页相关小程序列表 | 来源公众号 |
1035 | 公众号自定义菜单 | 来源公众号 |
1036 | App 分享消息卡片 | 来源 App |
1037 | 小程序打开小程序 | 来源小程序 |
1038 | 从另一个小程序返回 | 来源小程序 |
1043 | 公众号模板消息 | 来源公众号 |
offAppShow
该 API 使用方法为 wx.offAppShow(function listener)
功能说明:移除小程序切前台事件的监听函数。
参数及说明:function listener,onAppShow 传入的监听函数。不传此参数则移除所有监听函数。
示例代码
const listener = function (res) { console.log(res) }wx.onAppShow(listener)wx.offAppShow(listener) // 需传入与监听时同一个的函数对象
onAppHide
该 API 使用方法为 wx.onAppHide(function listener)
功能说明:监听小程序切后台事件。该事件与 App.onHide 的回调时机一致。
参数及说明:function listener,小程序切后台事件的监听函数。
offAppHide
该 API 使用方法为 wx.offAppHide(function listener)
功能说明:移除小程序切前台事件的监听函数。
参数及说明:function listener,onAppHide 传入的监听函数。不传此参数则移除所有监听函数。
const listener = function (res) { console.log(res) }wx.onAppHide(listener)wx.offAppHide(listener) // 需传入与监听时同一个的函数对象
onUnhandledRejection
该 API 使用方法为 wx.onUnhandledRejection(function listener)
注意:
所有的 unhandledRejection 都可以被这一监听捕获,但只有 Error 类型的才会在小程序后台触发报警。
功能说明:监听未处理的 Promise 拒绝事件。
参数及说明:Object res 参数,function listener,未处理的 Promise 拒绝事件的监听函数。
属性 | 类型 | 说明 |
reason | string | 拒绝原因,一般是一个 Error 对象 |
promise | Promise.<any> | 被拒绝的 Promise 对象 |
offUnhandledRejection
该 API 使用方法为 wx.offUnhandledRejection(function listener)
功能说明:移除未处理的 Promise 拒绝事件的监听函数 。
参数及说明:function listener,onUnhandledRejection 传入的监听函数。不传此参数则移除所有监听函数。
示例代码
const listener = function (res) { console.log(res) }wx.onUnhandledRejection(listener)wx.offUnhandledRejection(listener) // 需传入与监听时同一个的函数对象
调试
setEnableDebug
该 API 使用方法为 wx.setEnableDebug(Object object)
功能说明:设置是否打开调试开关。此开关对正式版也能生效。
参数及说明:Object object。
属性 | 类型 | 默认值 | 必填 | 说明 |
enableDebug | boolean | - | 是 | 是否打开调试 |
success | function | - | 否 | 接口调用成功的回调函数 |
fail | function | - | 否 | 接口调用失败的回调函数 |
complete | function | - | 否 | 接口调用结束的回调函数(调用成功、失败都会执行) |
示例代码:
// 打开调试wx.setEnableDebug({enableDebug: true})// 关闭调试wx.setEnableDebug({enableDebug: false})
说明:
在正式版打开调试还可以先在开发版或体验版打开调试,再切到正式版就能看到 vConsol。
getRealtimeLogManager
该 API 使用方法为 RealtimeLogManager wx.getRealtimeLogManager()
功能说明:获取实时日志管理器对象。
返回值:RealtimeLogManager。
示例代码:
// 小程序端const logger = wx.getRealtimeLogManager()logger.info({str: 'hello world'}, 'info log', 100, [1, 2, 3])logger.error({str: 'hello world'}, 'error log', 100, [1, 2, 3])logger.warn({str: 'hello world'}, 'warn log', 100, [1, 2, 3])// 插件端,基础库 2.16.0 版本后支持,只允许采用 key-value 的新格式上报const logManager = wx.getRealtimeLogManager()const logger = logManager.tag('plugin-log1')logger.info('key1', 'value1')logger.error('key2', {str: 'value2'})logger.warn('key3', 'value3')
getLogManager
该 API 使用方法为 LogManager wx.getLogManager(Object object)
功能说明:获取日志管理器对象。
参数及说明:Object object。
属性 | 类型 | 默认值 | 必填 | 说明 |
level | number | 0 | 否 | 取值为0/1,取值为0表示是否会把 App 、Page 的生命周期函数和命名空间下的函数调用写入日志,取值为1则不会。默认值是 0 |
返回值:LogManager。
示例代码:
const logger = wx.getLogManager({level: 1})logger.log({str: 'hello world'}, 'basic log', 100, [1, 2, 3])logger.info({str: 'hello world'}, 'info log', 100, [1, 2, 3])logger.debug({str: 'hello world'}, 'debug log', 100, [1, 2, 3])logger.warn({str: 'hello world'}, 'warn log', 100, [1, 2, 3])
console
console 是一个可以直接访问的全局对象,其具体方法集如下。可以在 IDE 调试面板中打印日志,在客户端中利用 vConsole 输出日志。
debug
该 方法 使用方式为 console.debug()
功能说明:向调试面板中打印 debug 日志。
参数及说明:any ... args,日志内容,可以有任意多个。
error
该 方法 使用方式为 console.error()
功能说明:向调试面板中打印 error 日志。
参数及说明:any ... args,日志内容,可以有任意多个。
group
该 方法 使用方式为 console.group()
说明:
仅在工具中有效,在 vConsole 中为空函数实现。
功能说明:在调试面板中创建一个新的分组。随后输出的内容都会被添加一个缩进,表示该内容属于当前分组。调用 console.groupEnd 之后分组结束。
参数及说明:string label,分组标记,可选。
info
该 方法 使用方式为 console.info
功能说明:向调试面板中打印 info 日志。
参数及说明:any ... args,日志内容,可以有任意多个。
log
该 方法 使用方式为 console.log()
功能说明:向调试面板中打印 log 日志。
参数及说明:any ... args,日志内容,可以有任意多个。
warn
该 方法 使用方式为 console.warn()
功能说明:向调试面板中打印 warn 日志。
参数及说明:any ... args,日志内容,可以有任意多个。
LogManager
debug
该 方法 使用方式为 LogManager.debug()
功能说明:写 debug 日志。
参数及说明:Object|Array.\\ |number|string ... args,日志内容,可以有任意多个。每次调用的参数的总大小不超过100Kb。
info
该 方法 使用方式为 LogManager.info()
功能说明:写 info 日志。
参数及说明:Object|Array.\\ |number|string ...args,日志内容,可以有任意多个。每次调用的参数的总大小不超过100Kb。
log
该 方法 使用方式为 LogManager.log()
功能说明:写 log 日志。
参数及说明:Object|Array.\\ |number|string ...args,日志内容,可以有任意多个。每次调用的参数的总大小不超过100Kb。
warn
该 方法 使用方式为 LogManager.warn()
说明:
最多保存5M的日志内容,超过5M后,旧的日志内容会被删除;
用户可以通过使用
<Button>
组件的open-type="feedback"
来上传打印的日志。开发者可以通过小程序管理后台左侧菜单“反馈管理”页面查看;基础库默认会把
App
、Page
的生命周期函数和命名空间下的函数调用写入日志。功能说明:写 warn 日志。
参数及说明:Object|Array.\\ |number|string ...args,日志内容,可以有任意多个。每次调用的参数的总大小不超过100Kb。
RealtimeLogManager
addFilterMsg
该 方法 使用方式为 RealtimeLogManager.addFilterMsg(string msg)
功能说明:添加过滤关键字,暂不支持在插件使用。
参数及说明:string msg,是setFilterMsg的添加接口。用于设置多个过滤关键字。
error
该 方法 使用方式为 RealtimeLogManager.error()
功能说明:写 error 日志,暂不支持在插件使用。
参数及说明:Object|Array.<any>|number|string ...args,日志内容,可以有任意多个。每次调用的参数的总大小不超过5Kb。
getCurrentState
该 方法 使用方式为 Object RealtimeLogManager.getCurrentState()
注意:
基础库内部在对日志进行上报时会补充一些结构化数据,如果遇到上报溢出的情况也会补充警告日志,所以此方法获取到的当前占用信息会比预期的大一些。
功能说明:实时日志会将一定时间间隔内缓存的日志聚合上报,如果该时间内缓存的内容超出限制,则会被丢弃。此方法可以获取当前缓存剩余空间。
返回值:Object
属性 | 类型 | 说明 |
size | number | 当前缓存中已使用空间,以字节为单位 |
maxSize | number | 当前缓存最大可用空间,以字节为单位 |
logCount | number | 当前缓存中的日志条数 |
maxLogCount | number | 当前缓存中最大可存日志条数 |
in
该 方法 使用方式为 RealtimeLogManager.in(Page pageInstance)
功能说明:设置实时日志page参数所在的页面,暂不支持在插件使用。
参数及说明:Page pageInstance,page 实例。
info
该 方法 使用方式为 RealtimeLogManager.info()
功能说明:写 info 日志,暂不支持在插件使用。
参数及说明:Object|Array.<any>|number|string ...args,日志内容,可以有任意多个。每次调用的参数的总大小不超过5Kb。
setFilterMsg
该 方法 使用方式为 RealtimeLogManagersetFilterMsg(string msg)
功能说明:设置过滤关键字,暂不支持在插件使用。
参数及说明:string msg,过滤关键字,最多不超过1Kb,可以在小程序管理后台根据设置的内容搜索得到对应的日志。
tag
该 方法 使用方式为 RealtimeTagLogManager RealtimeLogManager.tag(string tagName)
功能说明:获取给定标签的日志管理器实例,目前只支持在插件使用。
参数及说明:string tagName,标签名。
warn
该 方法 使用方式为 RealtimeLogManager.warn()
功能说明:写 warn 日志,暂不支持在插件使用。
参数及说明:Object|Array.<any>|number|string ...args,日志内容,可以有任意多个。每次调用的参数的总大小不超过5Kb。
RealtimeTagLogManager
addFilterMsg
该 方法 使用方式为 RealtimeTagLogManager.addFilterMsg(string msg)
功能说明:添加过滤关键字。
参数及说明:string msg,是setFilterMsg的添加接口。用于设置多个过滤关键字。
error
该 方法 使用方式为 RealtimeTagLogManager.error(string key, Object]Array.<any> number string value)
功能说明:写 error 日志。
参数及说明:
string key,日志的 key;
Object|Array.<any>|number|string value,日志的值,每次调用的参数的总大小不超过5Kb。
info
该 方法 使用方式为 RealtimeTagLogManager.info(string key, Object Array.<any> number string value)
功能说明:写 info 日志。
参数及说明:
string key,日志的 key;
Object|Array.<any>|number|string value,日志的值,每次调用的参数的总大小不超过5Kb。
setFilterMsg
该 方法 使用方式为 RealtimeTagLogManager.setFilterMsg(string msg)
功能说明:设置过滤关键字。
参数及说明:string msg,过滤关键字,最多不超过1Kb,可以在小程序管理后台根据设置的内容搜索得到对应的日志。
warn
该 方法 使用方式为 RealtimeTagLogManager.warn(string key, ObjectJArray.< any> number string value)
功能说明:写 warn 日志。
参数及说明:
string key,日志的 key;
Object|Array.<any>|number|string value,日志的值,每次调用的参数的总大小不超过5Kb。