tencent cloud

基础
最后更新时间:2025-11-13 15:29:57
基础
最后更新时间: 2025-11-13 15:29:57

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 小程序支持,小游戏不支持。
功能说明:该 API 使用方法为 ArrayBuffer wx.base64ToArrayBuffer(string base64), 将 Base64 字符串转成 ArrayBuffer 对象。
参数及说明:string base64,要转化成 ArrayBuffer 对象的 Base64 字符串。
返回值:ArrayBuffer,ArrayBuffer 对象。
示例代码:
const base64 = 'CxYh'
const arrayBuffer = wx.base64ToArrayBuffer(base64)

arrayBufferToBase64

说明:
该 API 小程序支持,小游戏不支持。
功能说明:该 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:开发者工具
fontSizeSetting
number
用户字体大小,单位 px
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:开发者工具
fontSizeSetting
number
用户字体大小,单位 px
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 小程序支持,小游戏暂不支持。
功能说明:该 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 客户端
devtools:IDE 开发者工具
fontSizeSetting
number
用户字体大小,单位 px
SDKVersion
string
客户端基础库版本
safeArea
object
在竖屏正方向下的安全区域。部分机型没有安全区域概念,也不会返回 safeArea 字段,开发者需自行兼容。返回值请参考下表 safeArea 返回值
theme
string
系统当前主题,全局配置 darkmode:true 时才能获取,否则为 undefined (不支持小游戏),其合法值为
light:明亮
dark:黑暗
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 小程序支持,小游戏暂不支持。
功能说明:该 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 小程序支持,小游戏暂不支持。
功能说明:该 API 使用方法为 wx.openSystemBluetoothSetting(Object object) 跳转系统蓝牙设置页。仅支持 Android 。
参数及说明:Object object。
属性
类型
默认值
必填
说明
success
function
-
接口调用成功的回调函数
fail
function
-
接口调用失败的回调函数
complete
function
-
接口调用结束的回调函数(调用成功、失败都会执行)
示例代码:
wx.openSystemBluetoothSetting({
success (res) {
console.log(res)
}
})

openAppAuthorizeSetting

说明:
该 API 小程序支持,小游戏暂不支持。
功能说明:该 API 使用方法为 wx.openAppAuthorizeSetting(Object object) 跳转系统宿主客户端授权管理页。
参数及说明:Object object。
属性
类型
默认值
必填
说明
success
function
-
接口调用成功的回调函数
fail
function
-
接口调用失败的回调函数
complete
function
-
接口调用结束的回调函数(调用成功、失败都会执行)
示例代码:
wx.openAppAuthorizeSetting({
success (res) {
console.log(res)
}
})

getRendererUserAgent

说明:
该 API 小程序支持,小游戏不支持。
功能说明:该 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') 来获取
memorySize
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
是否已打开调试。可通过右上角菜单或 wx.setEnableDebug 打开调试
host
Object
当前小程序运行的宿主环境。
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)

getAccountInfoSync

功能说明:该 API 使用方法为 Object wx.getAccountInfoSync() 获取当前小程序账号信息。线上小程序版本号仅支持在正式版小程序中获取,开发版和体验版中无法获取。
返回值:Object,账号信息。
属性
类型
说明
miniProgram
Object
小程序账号信息
miniProgram 结构属性
结构属性
类型
说明
appId
string
小程序 appId
envVersion
string
小程序版本,合法值为:
develop:开发版
trial:体验版
release:正式版
version
string
线上小程序版本号

更新

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

注意:
部分版本在无referrerInfo的时候会返回 undefined,建议使用options.referrerInfo && options.referrerInfo.appId进行判断。
功能说明:该API使用方法为 Object wx.getLaunchOptionsSync() 获取小程序启动时的参数 。
返回值:Object,启动参数。
属性
类型
说明
path
String
启动小程序的路径 (仅小程序支持)
scene
Number
启动小程序的场景值,默认为1001
query
Object
启动小程序的 query 参数
referrerInfo
Object
来源信息,从另一个小程序或 App 进入小程序时返回。否则返回 {}
forwardMaterials
Array.<Object>
打开的文件信息数组
extendData
String
SDK打开小程序时传递的参数
referrerInfo 的结构
属性
类型
说明
appId
String
来源小程序 或 App 的 appId
extraData
Object
来源小程序传过来的数据
注意:
这里的 extraData 字段是由调用原生启动小程序传入的扩展参数。
iOS:传入的 paramsStr
[[TMFMiniAppSDKManager sharedInstance] startUpMiniAppWithAppID:@"mpbz0uqwzddj5zbt" scene:TMAEntrySceneNone firstPage:nil paramsStr:@"a=1&b=2" parentVC:self completion:^(NSError * _Nullable err) {

}];
Android:MiniStartLinkOptions 对象的 params 字段

MiniStartLinkOptions miniStartOptions = new MiniStartLinkOptions(); miniStartOptions.params = (String) options.get("params");
public static void startMiniApp(Activity activity, String appId, MiniStartOptions options) { startMiniApp(activity, appId, 1001, 0, options);
}

forwardMaterials 的结构
属性
类型
说明
type
string
文件的 mimetype 类型
name
Object
文件名
path
string
文件路径
size
number
文件大小
返回有效referrerInfo的场景
属性
类型
appId 含义
1037
小程序打开小程序
来源小程序
1038
从另一个小程序返回
来源小程序

getEnterOptionsSync

注意:
部分版本在无referrerInfo的时候会返回 undefined,建议使用options.referrerInfo && options.referrerInfo.appId进行判断。
功能说明:该API使用方法为 Object wx.getEnterOptionsSync() 获取本次小程序启动时的参数。如果当前是冷启动,则返回值与 App.onLaunch 的回调参数一致;如果当前是热启动,则返回值与 App.onShow 一致。
返回值:Object
属性
类型
说明
path
string
启动小程序的路径(代码包路径) (仅小程序支持)
scene
number
启动小程序的场景值
query
Object
启动小程序的 query 参数
shareTicket
string
shareTicket
referrerInfo
Object
来源信息。从另一个小程序 或 App 进入小程序时返回。否则返回 {},具体参见表格前文的注意
forwardMaterials
Array.<Object>
打开的文件信息数组
extendData
String
SDK打开小程序时传递的参数
referrerInfo 的结构
属性
类型
说明
appId
String
来源小程序 或 App 的 appId
extraData
Object
来源小程序传过来的数据
forwardMaterials 的结构
属性
类型
说明
type
String
文件的 mimetype 类型
name
Object
文件名
path
String
文件路径(如果是 webview 则是 url)
size
Number
文件大小
返回有效 referrerInfo 的场景
属性
类型
appId 含义
1037
小程序打开小程序
来源小程序
1038
从另一个小程序返回
来源小程序

应用级事件

onError

说明:
该 API 小程序支持,小游戏暂不支持。
功能说明:该 API 使用方法为 wx.onError(function callback) 监听小程序错误事件。如脚本错误或 API 调用报错等。
参数及说明:function callback,小程序错误事件的回调函数。
返回参数:string error,错误信息,包含堆栈。

offError

说明:
该 API 小程序支持,小游戏暂不支持。
功能说明:该 API 使用方法为 wx.offError(function callback) 取消监听小程序错误事件。
参数及说明:function callback,小程序错误事件的回调函数。

onThemeChange

说明:
只有在全局配置 darkmode:true 时才会触发此事件。
该 API 小程序支持,小游戏不支持。
功能说明:该 API 使用方法为 wx.onThemeChange(function listener) 监听系统主题改变事件。
参数及说明:function listener,系统主题改变事件的监听函数。
返回参数:Object res
属性
合法值及说明
类型
说明
theme
dark:深色主题
light:浅色主题
String
系统当前的主题,取值为 light 或 dark

offThemeChange

说明:
该 API 小程序支持,小游戏不支持。
功能说明:该 API 使用方法为 wx.offThemeChange(function listener) 移除系统主题改变事件的监听函数 。
参数及说明:function listener,onThemeChange 传入的监听函数。不传此参数则移除所有监听函数。
示例代码:
const listener = function (res) { console.log(res) }

wx.onThemeChange(listener)
wx.offThemeChange(listener) // 需传入与监听时同一个的函数对象

onPageNotFound

说明:
该 API 小程序支持,小游戏不支持。
注意:
开发者可以在回调中进行页面重定向,但必须在回调中同步处理,异步处理(例如 setTimeout 异步执行)无效。
若开发者没有调用 wx.onPageNotFound 绑定监听,也没有声明 App.onPageNotFound,当跳转页面不存在时,将推入宿主客户端原生的页面不存在提示页面。
如果回调中又重定向到另一个不存在的页面,将推入宿主客户端原生的页面不存在提示页面,并且不再第二次回调。
功能说明:该 API 使用方法为 wx.onPageNotFound(function listener) 监听小程序要打开的页面不存在事件。该事件与 App.onPageNotFound 的回调时机一致。
参数及说明:Object res 参数,function listener,小程序要打开的页面不存在事件的监听函数。
属性
类型
说明
path
string
不存在页面的路径 (代码包路径)
query
Object
打开不存在页面的 query 参数
isEntryPage
boolean
是否本次启动的首个页面(例如从分享等入口进来,首个页面是开发者配置的分享页面)

offPageNotFound

说明:
该 API 小程序支持,小游戏不支持。
功能说明:该 API 使用方法为 wx.offPageNotFound(function listener) 移除小程序要打开的页面不存在事件的监听函数。
参数及说明:function listener,onPageNotFound 传入的监听函数。不传此参数则移除所有监听函数。
示例代码:
const listener = function (res) { console.log(res) }

wx.onPageNotFound(listener)
wx.offPageNotFound(listener) // 需传入与监听时同一个的函数对象

onAppShow

说明:
该 API 小程序支持,小游戏不支持。
注意:
部分版本在无 referrerInfo 的时候会返回 undefined,建议使用options.referrerInfo && options.referrerInfo.appId进行判断。
功能说明:该 API 使用方法为 wx.onAppShow(function listener) 监听小程序切前台事件。该事件与 App.onShow 的回调参数一致。
参数及说明:Object res 参数,function listener,小程序切前台事件的监听函数。
属性
类型
说明
path
string
启动小程序的路径(代码包路径)
scene
number
启动小程序的场景值
query
Object
启动小程序的 query 参数
shareTicket
string
shareTicket
referrerInfo
Object
来源信息。从另一个小程序 或 App 进入小程序时返回。否则返回{},具体参见表格前文的注意
forwardMaterials
Array.<Object>
打开的文件信息数组
referrerInfo 的结构
属性
类型
说明
appId
string
来源小程序 或 App 的 appId
extraData
Object
来源小程序传过来的数据
forwardMaterials 的结构
属性
类型
说明
type
String
文件的 mimetype 类型
name
Object
文件名
path
String
文件路径(如果是 webview 则是 url)
size
Number
文件大小
返回有效 referrerInfo 的场景
场景值
场景
appId 含义
1037
小程序打开小程序
来源小程序
1038
从另一个小程序返回
来源小程序

offAppShow

说明:
该 API 小程序支持,小游戏不支持。
功能说明:该 API 使用方法为 wx.offAppShow(function listener) 移除小程序切前台事件的监听函数。
参数及说明:function listener,onAppShow 传入的监听函数。不传此参数则移除所有监听函数。
示例代码:
const listener = function (res) { console.log(res) }

wx.onAppShow(listener)
wx.offAppShow(listener) // 需传入与监听时同一个的函数对象

onAppHide

说明:
该 API 小程序支持,小游戏不支持。
功能说明:该 API 使用方法为 wx.onAppHide(function listener) 监听小程序切后台事件。该事件与 App.onHide 的回调时机一致。
参数及说明:function listener,小程序切后台事件的监听函数。

offAppHide

说明:
该 API 小程序支持,小游戏不支持。
功能说明:该 API 使用方法为 wx.offAppHide(function listener) 移除小程序切前台事件的监听函数。
参数及说明:function listener,onAppHide 传入的监听函数。不传此参数则移除所有监听函数。
示例代码:
const listener = function (res) { console.log(res) }

wx.onAppHide(listener)
wx.offAppHide(listener) // 需传入与监听时同一个的函数对象

onShow

说明:
该 API 仅小游戏支持。
功能说明:该 API 使用方法为 wx.onShow(function listener) 小游戏回到前台的事件监听函数。
参数及说明:Object res 参数,function listener,小游戏回到前台的事件的监听函数。
属性
类型
说明
scene
number
场景值
query
Object
查询参数
shareTicket
string
shareTicket
referrerInfo
Object
来源信息。从另一个小程序 或 App 进入小程序时返回此字段。
referrerInfo 的结构
属性
类型
说明
appId
string
来源小程序 或 App 的 appId
extraData
Object
来源小程序传过来的数据

offShow

说明:
该 API 仅小游戏支持。
功能说明:该 API 使用方法为 wx.offShow(function listener) 移除小游戏回到前台的事件的监听函数。
参数及说明:function listener,onShow 传入的监听函数。不传此参数则移除所有监听函数。
示例代码:
const listener = function (res) { console.log(res) }

wx.onShow(listener)
wx.offShow(listener) // 需传入与监听时同一个的函数对象

onHide

说明:
该 API 仅小游戏支持。
功能说明:该 API 使用方法为 wx.onHide(function listener) 监听小游戏隐藏到后台事件。锁屏、按 HOME 键退到桌面等操作会触发此事件。
参数及说明:function listener,小游戏隐藏到后台事件的监听函数。

offHide

说明:
该 API 仅小游戏支持。
功能说明:该 API 使用方法为 wx.offHide(function listener) 移除小游戏隐藏到后台事件的监听函数。
参数及说明:function listener,onHide 传入的监听函数。不传此参数则移除所有监听函数。
示例代码:
const listener = function (res) { console.log(res) }

wx.onHide(listener)
wx.offHide(listener) // 需传入与监听时同一个的函数对象

onUnhandledRejection

说明:
该 API 小程序支持,小游戏暂不支持。
注意:
所有的 unhandledRejection 都可以被这一监听捕获,但只有 Error 类型的才会在小程序后台触发报警。
功能说明:该 API 使用方法为 wx.onUnhandledRejection(function listener) 监听未处理的 Promise 拒绝事件。
参数及说明:Object res 参数,function listener,未处理的 Promise 拒绝事件的监听函数。
属性
类型
说明
reason
string
拒绝原因,一般是一个 Error 对象
promise
Promise.<any>
被拒绝的 Promise 对象

offUnhandledRejection

说明:
该 API 小程序支持,小游戏暂不支持。
功能说明:该 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
})
说明:
在正式版打开调试还可以先在开发版或体验版打开调试,再切到正式版就能看到 vConsole。

getRealtimeLogManager

说明:
该 API 小程序支持,小游戏暂不支持。
功能说明: 该 API 使用方法为 RealtimeLogManager wx.getRealtimeLogManager(). Gets the real-time log manager object.
示例代码
// 小程序端
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表示会把AppPage的生命周期函数和命名空间下的函数调用写入日志,取值为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 输出日志。

LogManager

日志管理器实例,可以通过 getLogManager 获取,具体方法集如下。

RealtimeTagLogManager

性能

说明:
仅小游戏支持。

triggerGC

功能说明:该 API 使用方法为 wx.triggerGC() 加快触发 JavaScriptCore 垃圾回收(Garbage Collection)。GC 时机是由 JavaScriptCore 来控制的,并不能保证调用后马上触发 GC。

getPerformance

功能说明:该 API 使用方法为 wx.getPerformance() 获取性能管理器。
返回值:Performance,一个性能管理器对象。

Performance

.now

功能说明:该方法使用方式为 Performance.now() 可以获取当前时间以微秒为单位的时间戳。
返回值: number,时间戳。

分包加载

说明:
仅小游戏支持。

preDownloadSubpackage

功能说明:该方法使用方式为 wx.preDownloadSubpackage(Object object) 触发分包预下载。
参数及说明:Object object。
属性
类型
默认值
必填
说明
packageType
string
'normal'
分包的类型,填写 "workers" 后 name 字段失效。
name
string
-
分包的名字,可以填 name 或者 root。在独立分包内,填 __GAME__ 表示加载主包。
success
function
-
分包加载成功回调事件
fail
function
-
分包加载失败回调事件
complete
function
-
分包加载结束回调事件(加载成功、失败都会执行)
返回值: PreDownloadSubpackageTask,预下载分包任务实例,用于获取分包预下载状态。
注意事项:wx.preDownloadSubpackage 与 wx.loadSubpackage 的区别: wx.preDownloadSubpackage 只下载代码包,不自动执行代码;wx.loadSubpackage 下载完代码包后会自动执行代码。
示例代码:
worker分包示例代码:
// 首先要在 app.json / game.json 中配置workers作为分包
{
"workers": {
"path": "myWorkersFolder",
"isSubpackage": true // true 表示把 worker 打包为分包。默认 false。填 false 时等同于 { "workers": "myWorkersFolder" }
}
}
// 然后调用 wx.preDownloadSubpackage 下载 worker 分包,下载成功后才可以创建 worker
var task = wx.preDownloadSubpackage({
packageType: "workers",
success(res) {
console.log("load worker success", res)
wx.createWorker("myWorkersFolder/request/index.js") // 创建 worker。 如果 worker 分包没下载完就调 createWorker 的话将报错
},
fail(res) {
console.log("load worker fail", res)
}
})

task.onProgressUpdate(res => {
console.log(res.progress) // 可通过 onProgressUpdate 接口监听下载进度
console.log(res.totalBytesWritten)
console.log(res.totalBytesExpectedToWrite)
})

普通分包示例代码:
// 首先要在 app.json / game.json 中配置分包
{
"subPackages": [
{
"name": "ModuleA",
"root": "/ModuleA/"
}
]
}
var task = wx.preDownloadSubpackage({
name: "ModuleA",
success(res) {
console.log("load subpackage success", res)
// 执行分包代码
wx.loadSubpackage({
name: "ModuleA",
success(res) {
console.log(res)
},
})
},
fail(res) {
console.log("load subpackage fail", res)
}
})

task.onProgressUpdate(res => {
console.log(res.progress) // 可通过 onProgressUpdate 接口监听下载进度
console.log(res.totalBytesWritten)
console.log(res.totalBytesExpectedToWrite)
})

PreDownloadSubpackageTask

.onProgressUpdate

功能说明:该方法使用方式为 PreDownloadSubpackageTask.onProgressUpdate(function listener) 监听分包加载进度变化事件。
参数及说明:function listener,分包加载进度变化事件的监听函数,参数 Object.res 如下:
属性
类型
说明
progress
number
分包下载进度百分比
totalBytesWritten
number
已经下载的数据长度,单位 Bytes
totalBytesExpectedToWrite
number
预期需要下载的数据总长度,单位 Bytes

loadSubpackage

功能说明:该方法使用方式为 wx.loadSubpackage(Object object) 触发分包加载。
参数及说明:Object object。
属性
类型
默认值
必填
说明
packageType
string
'normal'
分包的类型,填写 "workers" 后 name 字段失效。
name
string
-
分包的名字,可以填 name 或者 root。在独立分包内,填 __GAME__ 表示加载主包。
success
function
-
分包加载成功回调事件
fail
function
-
分包加载失败回调事件
complete
function
-
分包加载结束回调事件(加载成功、失败都会执行)
返回值:LoadSubpackageTask,加载分包任务实例,用于获取分包加载状态。
注意事项:wx.preDownloadSubpackage 与 wx.loadSubpackage 的区别: wx.preDownloadSubpackage 只下载代码包,不自动执行代码;wx.loadSubpackage 下载完代码包后会自动执行代码。

LoadSubpackageTask

.onProgressUpdate

功能说明:该方法使用方式为 LoadSubpackageTask.onProgressUpdate(function listener) 监听分包加载进度变化事件。
参数及说明:function listener,分包加载进度变化事件的监听函数,参数 Object.res 如下:
属性
类型
说明
progress
number
分包下载进度百分比
totalBytesWritten
number
已经下载的数据长度,单位 Bytes
totalBytesExpectedToWrite
number
预期需要下载的数据总长度,单位 Bytes

本页内容是否解决了您的问题?
您也可以 联系销售 提交工单 以寻求帮助。

文档反馈