小程序——基础API

吴声子夜歌2026-03-11 23:49

基础API

  • 一、基础
    • 1.1、wx.env
    • [1.2、boolean wx.canIUse(string schema)](#1.2、boolean wx.canIUse(string schema))
    • [1.3、ArrayBuffer wx.base64ToArrayBuffer(string base64)](#1.3、ArrayBuffer wx.base64ToArrayBuffer(string base64))
    • [1.4、string wx.arrayBufferToBase64(ArrayBuffer arrayBuffer)](#1.4、string wx.arrayBufferToBase64(ArrayBuffer arrayBuffer))
  • 二、系统
    • [2.1、wx.openSystemBluetoothSetting(Object object)](#2.1、wx.openSystemBluetoothSetting(Object object))
    • [2.2、wx.openAppAuthorizeSetting(Object object)](#2.2、wx.openAppAuthorizeSetting(Object object))
    • [2.3、Object wx.getWindowInfo()](#2.3、Object wx.getWindowInfo())
    • [2.4、Object wx.getSystemSetting()](#2.4、Object wx.getSystemSetting())
    • [2.5、wx.getSystemInfoAsync(Object object)](#2.5、wx.getSystemInfoAsync(Object object))
    • [2.6、Promise wx.getRendererUserAgent(Object object)](#2.6、Promise wx.getRendererUserAgent(Object object))
    • [2.7、Object wx.getDeviceInfo()](#2.7、Object wx.getDeviceInfo())
    • [2.8、wx.getDeviceBenchmarkInfo(Object object)](#2.8、wx.getDeviceBenchmarkInfo(Object object))
    • [2.9、Object wx.getAppBaseInfo()](#2.9、Object wx.getAppBaseInfo())
    • [2.10、wx.setStorageSync(string key, any data)](#2.10、wx.setStorageSync(string key, any data))
  • 三、更新
    • [3.1、wx.updateWeChatApp(Object object)](#3.1、wx.updateWeChatApp(Object object))
    • [3.2、UpdateManager wx.getUpdateManager()](#3.2、UpdateManager wx.getUpdateManager())
  • 四、调试
    • [4.1、wx.setEnableDebug(Object object)](#4.1、wx.setEnableDebug(Object object))
    • [4.2、RealtimeLogManager wx.getRealtimeLogManager()](#4.2、RealtimeLogManager wx.getRealtimeLogManager())
    • [4.3、LogManager wx.getLogManager(Object object)](#4.3、LogManager wx.getLogManager(Object object))
    • 4.4、console
    • [4.5、wx.updateShareMenu(Object object)](#4.5、wx.updateShareMenu(Object object))
    • 4.6、gManager

一、基础

1.1、wx.env

环境变量

属性：

  • string USER_DATA_PATH：文件系统中的用户目录路径 (本地路径)

1.2、boolean wx.canIUse(string schema)

判断小程序的API，回调，参数，组件等是否在当前版本可用。

参数：string schema

复制代码 
使用 ${API}.${method}.${param}.${option} 

或者 ${component}.${attribute}.${option} 方式来调用

参数说明：

  • ${API} 代表 API 名字
  • ${method} 代表调用方式，有效值为return, success, object, callback
  • ${param} 代表参数或者返回值
  • ${option} 代表参数的可选值或者返回值的属性
  • ${component} 代表组件名字
  • ${attribute} 代表组件属性
  • ${option} 代表组件属性的可选值
js 复制代码 
// 对象的属性或方法
wx.canIUse('console.log')
wx.canIUse('CameraContext.onCameraFrame')
wx.canIUse('CameraFrameListener.start')
wx.canIUse('Image.src')

// wx接口参数、回调或者返回值
wx.canIUse('openBluetoothAdapter')
wx.canIUse('getSystemInfoSync.return.safeArea.left')
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')

1.3、ArrayBuffer wx.base64ToArrayBuffer(string base64)

将 Base64 字符串转成 ArrayBuffer 对象

  • 参数：
    • string base64：要转化成 ArrayBuffer 对象的 Base64 字符串
  • 返回值：
    • ArrayBuffer：ArrayBuffer对象
js 复制代码 
const base64 = 'CxYh'
const arrayBuffer = wx.base64ToArrayBuffer(base64)

1.4、string wx.arrayBufferToBase64(ArrayBuffer arrayBuffer)

将 ArrayBuffer 对象转成 Base64 字符串

  • 参数：
    • ArrayBuffer arrayBuffer：要转换成 Base64 字符串的 ArrayBuffer 对象
  • 返回值：
    • string：Base64 字符串
js 复制代码 
const arrayBuffer = new Uint8Array([11, 22, 33])
const base64 = wx.arrayBufferToBase64(arrayBuffer)

二、系统

2.1、wx.openSystemBluetoothSetting(Object object)

跳转系统蓝牙设置页。仅支持安卓。

参数：Object object

属性 类型 默认值 必填 说明
success function 否 接口调用成功的回调函数
fail function 否 接口调用失败的回调函数
complete function 否 接口调用结束的回调函数（调用成功、失败都会执行）
js 复制代码 
wx.openSystemBluetoothSetting({
  success (res) {
    console.log(res)
  }
})

2.2、wx.openAppAuthorizeSetting(Object object)

跳转系统微信授权管理页。

参数：Object object

属性 类型 默认值 必填 说明
success function 否 接口调用成功的回调函数
fail function 否 接口调用失败的回调函数
complete function 否 接口调用结束的回调函数（调用成功、失败都会执行）
js 复制代码 
wx.openAppAuthorizeSetting({
  success (res) {
    console.log(res)
  }
})

2.3、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 安全区域的高度，单位逻辑像素
js 复制代码 
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)

2.4、Object wx.getSystemSetting()

获取设备设置。

返回值：Object

属性 类型 说明
bluetoothEnabled boolean 蓝牙的系统开关
locationEnabled boolean 地理位置的系统开关
wifiEnabled boolean Wi-Fi 的系统开关
deviceOrientation string 设备方向（注意：IOS客户端横屏游戏获取deviceOrientation可能不准，建议以屏幕宽高为准），其中可选值为： portrait:竖屏 landscape:横屏
js 复制代码 
const systemSetting = wx.getSystemSetting()

console.log(systemSetting.bluetoothEnabled)
console.log(systemSetting.deviceOrientation)
console.log(systemSetting.locationEnabled)
console.log(systemSetting.wifiEnabled)

2.5、wx.getSystemInfoAsync(Object object)

异步获取系统信息。需要一定的微信客户端版本支持，在不支持的客户端上，会使用同步实现来返回。

参数：Object object

属性 类型 默认值 必填 说明
success function 否 接口调用成功的回调函数
fail function 否 接口调用失败的回调函数
complete function 否 接口调用结束的回调函数（调用成功、失败都会执行）
js 复制代码 
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)
  }
})

2.6、Promise wx.getRendererUserAgent(Object object)

获取 Webview 小程序的 UserAgent。

参数：Object object

属性 类型 默认值 必填 说明
success function 否 接口调用成功的回调函数
fail function 否 接口调用失败的回调函数
complete function 否 接口调用结束的回调函数（调用成功、失败都会执行）
js 复制代码 
// v2.30.4 前，仅支持 promise 风格调用
wx.getRendererUserAgent().then(userAgent => console.log(userAgent))
// v2.30.4 起，除 promise 风格调用外，也支持 invoke 风格使用
wx.getRendererUserAgent({
  success(res) { console.log(res.userAgent) }
})

2.7、Object wx.getDeviceInfo()

获取设备基础信息。

参数：Object object

属性 类型 说明
abi string 应用（微信APP）二进制接口类型（仅 Android 支持）
deviceAbi string 设备二进制接口类型（仅 Android 支持）
benchmarkLevel number 设备性能等级（仅 Android 支持）。取值为：-2 或 0（该设备无法运行小游戏），-1（性能未知），>=1（设备性能值，该值越高，设备性能越好，目前最高不到50）注意：从基础库3.4.5开始，本返回值停止维护，请使用wx.getDeviceBenchmarkInfo获取设备性能等级
brand string 设备品牌
model string 设备型号。新机型刚推出一段时间会显示unknown，微信会尽快进行适配。
system string 操作系统及版本
platform string 客户端平台
cpuType string 设备 CPU 型号（仅 Android 支持）（Tips: GPU 型号可通过 WebGLRenderingContext.getExtension('WEBGL_debug_renderer_info') 来获取）
memorySize string 设备内存大小，单位为 MB
js 复制代码 
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)

2.8、wx.getDeviceBenchmarkInfo(Object object)

获取设备性能得分和机型档位数据。

参数：Object object

属性 类型 默认值 必填 说明
success function 否 接口调用成功的回调函数
fail function 否 接口调用失败的回调函数
complete function 否 接口调用结束的回调函数（调用成功、失败都会执行）

object.success回调函数：

参数：Object res

属性 类型 说明
benchmarkLevel number 设备性能等级。-1（性能未知），>=1（设备性能值，该值越高，设备性能越好，目前最高不超过50）
注意：设备的benchmarkLevel值不会随着时间的推移而变化
modelLevel number 设备机型档位。0（档位未知），1（高档机），2（中档机），3（低档机）注意：设备的机型档位会随着时间的推移而变化，因此在使用时请谨慎对待；若业务逻辑依赖于机型档位，但担心受到机型档位变化的影响，请参考设备档位映射文档自行判断机型档位
js 复制代码 
wx.getDeviceBenchmarkInfo({
  success (res) {
    console.log(res.benchmarkLevel)
    console.log(res.modelLevel)
  }
})

2.9、Object wx.getAppBaseInfo()

获取微信APP基础信息。

返回值：Object

属性 类型 说明
SDKVersion string 客户端基础库版本
enableDebug boolean 是否已打开调试。可通过右上角菜单或 wx.setEnableDebug 打开调试。
host Object 当前小程序运行的宿主环境
language string 微信设置的语言
version string 微信版本号
PCKernelVersion string PC 内核版本号，仅在 PC 端存在该值
theme string 系统当前主题，取值为light或dark，全局配置"darkmode":true`时才能获取，否则为 undefined （不支持小游戏）
fontSizeScaleFactor number 微信字体大小缩放比例
fontSizeSetting number 微信字体大小，单位px
js 复制代码 
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)

2.10、wx.setStorageSync(string key, any data)

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

参数：

  • string key：本地缓存中指定的 key
  • any data：需要存储的内容。只支持原生类型、Date、及能够通过JSON.stringify序列化的对象。

注意：storage 应只用来进行数据的持久化存储，不应用于运行时的数据传递或全局状态管理。启动过程中过多的同步读写存储，会显著影响启动耗时。

js 复制代码 
try {
  wx.setStorageSync('key', 'value')
} catch (e) { }

三、更新

3.1、wx.updateWeChatApp(Object object)

更新客户端版本。当判断用户小程序所在客户端版本过低时，可使用该接口跳转到更新微信页面。

参数：Object object

属性 类型 默认值 必填 说明
success function 否 接口调用成功的回调函数
fail function 否 接口调用失败的回调函数
complete function 否 接口调用结束的回调函数（调用成功、失败都会执行）

3.2、UpdateManager wx.getUpdateManager()

获取全局唯一的版本更新管理器，用于管理小程序更新。关于小程序的更新机制，可以查看运行机制文档。

UpdateManager：

UpdateManager 对象，用来管理更新，可通过 wx.getUpdateManager 接口获取实例。

  • UpdateManager.applyUpdate()
    强制小程序重启并使用新版本。在小程序新版本下载完成后（即收到 onUpdateReady 回调）调用。
  • UpdateManager.onCheckForUpdate(function listener)
    监听向微信后台请求检查更新结果事件。微信在小程序每次启动（包括热启动）时自动检查更新，不需由开发者主动触发。
  • UpdateManager.onUpdateReady(function listener)
    监听小程序有版本更新事件。客户端主动触发下载（无需开发者触发），下载成功后回调
  • UpdateManager.onUpdateFailed(function listener)
    监听小程序更新失败事件。小程序有新版本，客户端主动触发下载（无需开发者触发），下载失败（可能是网络原因等）后回调
js 复制代码 
const updateManager = wx.getUpdateManager()

updateManager.onCheckForUpdate(function (res) {
  // 请求完新版本信息的回调
  console.log(res.hasUpdate)
})

updateManager.onUpdateReady(function () {
  wx.showModal({
    title: '更新提示',
    content: '新版本已经准备好，是否重启应用？',
    success: function (res) {
      if (res.confirm) {
        // 新的版本已经下载好，调用 applyUpdate 应用新版本并重启
        updateManager.applyUpdate()
      }
    }
  })
})

updateManager.onUpdateFailed(function () {
  // 新版本下载失败
})

四、调试

4.1、wx.setEnableDebug(Object object)

设置是否打开调试开关。此开关对正式版也能生效。

参数：Object object

属性 类型 默认值 必填 说明
enableDebug boolean 是 是否打开调试
success function 否 接口调用成功的回调函数
fail function 否 接口调用失败的回调函数
complete function 否 接口调用结束的回调函数（调用成功、失败都会执行）
js 复制代码 
// 打开调试
wx.setEnableDebug({
  enableDebug: true
})

// 关闭调试
wx.setEnableDebug({
  enableDebug: false
})

4.2、RealtimeLogManager wx.getRealtimeLogManager()

获取实时日志管理器对象。

js 复制代码 
// 小程序端
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')

4.3、LogManager wx.getLogManager(Object object)

获取日志管理器对象。

参数：Object object

属性 类型 默认值 必填 说明
level number 0 否 取值为0/1，取值为0表示会把 App、Page 的生命周期函数和 wx 命名空间下的函数调用写入日志，取值为1则不会。默认值是 0
js 复制代码 
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])

4.4、console

向调试面板中打印日志。console 是一个全局对象，可以直接访问。在微信客户端中，向 vConsole 中输出日志。

  • console.debug()
    向调试面板中打印 debug 日志
  • console.log()
    向调试面板中打印 log 日志
  • console.info()
    向调试面板中打印 info 日志
  • console.warn()
    向调试面板中打印 warn 日志
  • console.error()
    向调试面板中打印 error 日志
  • console.group(string label)
    在调试面板中创建一个新的分组。随后输出的内容都会被添加一个缩进，表示该内容属于当前分组。调用 console.groupEnd之后分组结束。
  • console.groupEnd()
    结束由 console.group 创建的分组

4.5、wx.updateShareMenu(Object object)

更新转发属性。

参数：Object object

属性 类型 默认值 必填 说明
withShareTicket boolean false 否 是否使用带 shareTicket 的转发详情
isUpdatableMessage boolean false 否 是否是动态消息，详见动态消息
activityId string 否 动态消息的 activityId。通过 updatableMessage.createActivityId 接口获取
toDoActivityId string 否 群待办消息的id，通过toDoActivityId可以把多个群待办消息聚合为同一个。通过 updatableMessage.createActivityId 接口获取。详见群待办消息
templateInfo Object 否 动态消息的模板信息
isPrivateMessage boolean 否 是否是私密消息。详见 小程序私密消息
participant Array.<string> [] 否 参与用户此聊天室下的 group_openid 列表
useForChatTool boolean false 否 聊天工具模式特殊动态消息
chooseType number 1 否 指定成员的方式
success function 否 接口调用成功的回调函数
fail function 否 接口调用失败的回调函数
complete function 否 接口调用结束的回调函数（调用成功、失败都会执行）

其中templateInfo结构如下：

结构属性 类型 默认值 必填 说明
parameterList Array.<Object> 是 参数列表
templateId string 是 模板ID
js 复制代码 
wx.updateShareMenu({
  withShareTicket: true,
  success () { }
})
js 复制代码 
// 转发私密消息
wx.updateShareMenu({
  isPrivateMessage: true,
  activityId: 'xxx',
  templateInfo: {},
  success () { },
  fail () {}
})

4.6、gManager

实时日志管理器实例，可以通过 wx.getRealtimeLogManager 获取。

  • RealtimeLogManager.info()
    写 info 日志，暂不支持在插件使用
  • RealtimeLogManager.warn()
    写 warn 日志，暂不支持在插件使用
  • RealtimeLogManager.error()
    写 error 日志，暂不支持在插件使用
  • RealtimeLogManager.setFilterMsg(string msg)
    设置过滤关键字，暂不支持在插件使用
  • RealtimeLogManager.addFilterMsg(string msg)
    添加过滤关键字，暂不支持在插件使用
相关推荐
CHU7290352 小时前
指尖践行环保——旧衣服回收小程序前端功能玩法详解
前端·小程序
my小新2 小时前
微信小程序引用echarts做统计图
微信小程序·小程序·echarts
吴声子夜歌2 小时前
小程序——图片
小程序
杰建云1672 小时前
门店小程序是否有必要做
小程序·小程序搭建
Greg_Zhong2 小时前
小程序中页面和组件的区别
小程序
小马_xiaoen2 小时前
常规优化已用尽？小程序体积深层次优化实战！！！
前端·小程序·uniapp
2501_915918412 小时前
iOS App HTTPS 抓包工具，代理抓包和数据线直连 iPhone 抓包的流程
android·ios·小程序·https·uni-app·iphone·webview
TE-茶叶蛋2 小时前
从零实现H5 表格协同编辑：Yjs + WebSocket 实战
websocket·小程序·excel
吴声子夜歌3 小时前
小程序——跳转API
服务器·前端·小程序
热门推荐
01GitHub 镜像站点02OpenClaw 使用和管理 MCP 完全指南03本地部署 OpenClaw + DeepSeek-R1 完全指南04OpenClaw 连接飞书完整指南：插件安装、配置与踩坑记录05OpenClaw 飞书机器人不回复消息？3 小时踩坑总结06Window 10部署openclaw报错node.exe : npm error code 12807OpenClaw macOS 完整安装与本地模型配置教程（实战版）08npm-error code 128问题解决方法09OpenClaw 接入 QQ Bot 完整实践指南10得物前端部门，没了