2021-11-26发表2024-01-25更新微信 / 微信小程序16 分钟读完 (大约2390个字)0次访问

微信小程序框架API

微信小程序框架所提供的API接口也是相当完备的,如果说小程序组件是用来构建小程序的视图层,那么小程序API则在小程序逻辑层担当重任。随着小程序版本的更新迭代,目前小程序框架 API分类已经达到了 19个大类,如下图所示。

当然这么多API并不需要读者一个个去详细研究,而是建议大家重点掌握其中常用的API如何查阅和使用,然后即可触类旁通使用其他的API。其实查阅API有点类似于查词典,我们只需要知道如何去查阅的方法即可, 而没必要将整部词典学会,故而掌握查阅API定义以及如何使用才是至关重要的。接下来,就开始重点讲解小程序框架中一些常用的API,通过这些API的学习和理解,希望读者能够对小程序 API如何查阅和使用形成一定的思维认知。

基础

微信小程序基础API包含一些环境变量，转码，系统信息，更新，小程序生命周期，应用及事件，调试，性能，加密等功能;

wx.getSystemInfo 获取系统信息实例

wx.getSystemInfo(Object object)

以 Promise 风格调用：支持

小程序插件：支持，需要小程序基础库版本不低于 1.9.6

微信 Windows 版：支持

微信 Mac 版：支持

获取系统信息。由于历史原因，wx.getSystemInfo 是异步的调用格式，但是是同步返回，需要异步获取系统信息请使用 wx.getSystemInfoAsync。

参数

Object object

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

object.success 回调函数

参数

Object res

属性	类型	说明	最低版本
brand	string	设备品牌	1.5.0
model	string	设备型号。新机型刚推出一段时间会显示unknown，微信会尽快进行适配。
pixelRatio	number	设备像素比
screenWidth	number	屏幕宽度，单位px	1.1.0
screenHeight	number	屏幕高度，单位px	1.1.0
windowWidth	number	可使用窗口宽度，单位px
windowHeight	number	可使用窗口高度，单位px
statusBarHeight	number	状态栏的高度，单位px	1.9.0
language	string	微信设置的语言
version	string	微信版本号
system	string	操作系统及版本
platform	string	客户端平台
fontSizeSetting	number	用户字体大小（单位px）。以微信客户端「我-设置-通用-字体大小」中的设置为准	1.5.0
SDKVersion	string	客户端基础库版本	1.1.0
benchmarkLevel	number	设备性能等级（仅 Android）。取值为：-2 或 0（该设备无法运行小游戏），-1（性能未知），>=1（设备性能值，该值越高，设备性能越好，目前最高不到50）	1.8.0
albumAuthorized	boolean	允许微信使用相册的开关（仅 iOS 有效）	2.6.0
cameraAuthorized	boolean	允许微信使用摄像头的开关	2.6.0
locationAuthorized	boolean	允许微信使用定位的开关	2.6.0
microphoneAuthorized	boolean	允许微信使用麦克风的开关	2.6.0
notificationAuthorized	boolean	允许微信通知的开关	2.6.0
notificationAlertAuthorized	boolean	允许微信通知带有提醒的开关（仅 iOS 有效）	2.6.0
notificationBadgeAuthorized	boolean	允许微信通知带有标记的开关（仅 iOS 有效）	2.6.0
notificationSoundAuthorized	boolean	允许微信通知带有声音的开关（仅 iOS 有效）	2.6.0
phoneCalendarAuthorized	boolean	允许微信使用日历的开关	2.19.3
bluetoothEnabled	boolean	蓝牙的系统开关	2.6.0
locationEnabled	boolean	地理位置的系统开关	2.6.0
wifiEnabled	boolean	Wi-Fi 的系统开关	2.6.0
safeArea	Object	在竖屏正方向下的安全区域	2.7.0
locationReducedAccuracy	boolean	`true` 表示模糊定位，`false` 表示精确定位，仅 iOS 支持
theme	string	系统当前主题，取值为`light`或`dark`，全局配置`"darkmode":true`时才能获取，否则为 undefined （不支持小游戏）	2.11.0
host	Object	当前小程序运行的宿主环境	2.12.3
enableDebug	boolean	是否已打开调试。可通过右上角菜单或 wx.setEnableDebug 打开调试。	2.15.0
deviceOrientation	string	设备方向

safeArea 的结构

属性	类型	说明
left	number	安全区域左上角横坐标
right	number	安全区域右下角横坐标
top	number	安全区域左上角纵坐标
bottom	number	安全区域右下角纵坐标
width	number	安全区域的宽度，单位逻辑像素
height	number	安全区域的高度，单位逻辑像素

theme 的合法值

值	说明	最低版本
dark	深色主题
light	浅色主题

host 的结构

属性	类型	说明
appId	string	宿主 app 对应的 appId

deviceOrientation 的合法值

值	说明	最低版本
portrait	竖屏
landscape	横屏

示例代码

在开发者工具中预览效果

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
}