提交 426bfb3d 编写于 作者: D DCloud_LXH

feat(mp-weixin): getSystemInfo、getDeviceInfo、getAppBaseInfo、getWindowInfo

上级 1b07c50e
### uni.getAppBaseInfo()
获取微信 APP 基础信息
|App|H5|微信小程序|支付宝小程序|字节跳动小程序|快手小程序|QQ小程序|百度小程序|京东小程序|钉钉小程序|飞书小程序|
|:-|:-|:-|:-|:-|:-|:-|:-|:-|:-|:-|
|√ `(3.4.13+)`|√ `(3.4.13+)`|√|x|x|x|x|x|x|x|x|
**返回参数说明**
|参数名|类型|说明|平台差异说明|
|:-|:-|:-|:-|
|appId|string|`manifest.json` 中应用appid,即DCloud appid。 ||
|appName|string|`manifest.json` 中应用名称 ||
|appVersion|string|`manifest.json` 中应用版本名称。||
|appVersionCode|string|`manifest.json` 中应用版本名号。||
|language|string|宿主、浏览器设置的语言、微信设置的语言|`App 仅 UNIMPSDK 支持`|
|appLanguage|string|应用设置的语言`en``zh-Hans``zh-Hant``fr``es`|`App``H5`|
|hostLanguage|string|浏览器语言、小程序宿主语言|`App 仅 UNIMPSDK 支持`|
|hostVersion|string|App、小程序宿主版本。如:微信版本号。Web 端为浏览器版本|`App 仅 UNIMPSDK 支持`|
|hostName|string|浏览器名称、小程序宿主名称|`App 仅 UNIMPSDK 支持``H5`|
|hostPackageName|string|小程序宿主包名|`仅 UNIMPSDK 支持`|
|hostFontSizeSetting|string|用户字体大小设置。以“我-设置-通用-字体大小”中的设置为准,单位:px|`仅 UNIMPSDK 支持`|
|hostSDKVersion|string|客户端基础库版本|`仅微信小程序`|
|hostTheme|string|系统当前主题,取值为light或dark,全局配置"darkmode":true时才能获取,否则为 undefined (不支持小游戏)|`仅微信小程序`|
|SDKVersion|string|客户端基础库版本|`仅微信小程序`|
|enableDebug|boolean|是否已打开调试。可通过右上角菜单或 wx.setEnableDebug 打开调试|`仅微信小程序`|
|host|Object|当前小程序运行的宿主环境|`仅微信小程序`|
|version|string|引擎版本号、微信版本号||
|theme|string|系统当前主题,取值为light或dark,全局配置"darkmode":true时才能获取,否则为 undefined (不支持小游戏)|`仅微信小程序`|
\ No newline at end of file
### uni.getDeviceInfo()
获取设备基础信息
|App|H5|微信小程序|支付宝小程序|字节跳动小程序|快手小程序|QQ小程序|百度小程序|京东小程序|钉钉小程序|飞书小程序|
|:-|:-|:-|:-|:-|:-|:-|:-|:-|:-|:-|
|√ `(3.4.13+)`|√ `(3.4.13+)`|√|x|x|x|x|x|x|x|x|
**返回参数说明**
|参数名|类型|说明|平台差异说明|
|:-|:-|:-|:-|
|deviceBrand|string|设备品牌。如:`apple``huawei`||
|deviceId|string|设备 id 。由 uni-app 框架生成并存储,清空 Storage 会导致改变||
|deviceModel|string|设备型号||
|deviceType|string|设备类型`phone``pad``pc`||
|brand|string|设备品牌||
|model|string|设备型号。新机型刚推出一段时间会显示unknown,微信会尽快进行适配。||
|system|string|操作系统及版本||
|platform|string|客户端平台||
|deviceOrientation|string|设备方向 `竖屏 portrait``横屏 landscape`|`App、H5`|
|devicePixelRatio|string|设备像素比|`App、H5`|
|abi |String|应用二进制接口类型(仅 Android 支持)|`仅微信小程序`|
|benchmarkLevel|Number|设备性能等级(仅 Android 支持)。取值为:-2 或 0(该设备无法运行小游戏),-1(性能未知),>=1(设备性能值,该值越高,设备性能越好,目前最高不到50)|`仅微信小程序`|
\ No newline at end of file
### uni.getWindowInfo()
获取窗口信息
|App|H5|微信小程序|支付宝小程序|字节跳动小程序|快手小程序|QQ小程序|百度小程序|京东小程序|钉钉小程序|飞书小程序|
|:-|:-|:-|:-|:-|:-|:-|:-|:-|:-|:-|
|√ `(3.4.13+)`|√ `(3.4.13+)`|√|x|x|x|x|x|x|x|x|
**返回参数说明**
|参数名|类型|说明|平台差异说明|
|:-|:-|:-|:-|
|pixelRatio |number|设备像素比||
|screenWidth |number|屏幕宽度||
|screenHeight |number|屏幕高度||
|windowWidth |number|可使用窗口宽度||
|windowHeight |number|可使用窗口高度||
|windowTop |number|可使用窗口的顶部位置||
|windowBottom |number|可使用窗口的底部位置||
|statusBarHeight |number|手机状态栏的高度||
|screenTop |number|窗口上边缘的 y 值||
|safeArea |object|在竖屏正方向下的安全区域|App、Web、微信小程序||
|safeAreaInsets |object|在竖屏正方向下的安全区域插入位置||
**safeArea 的结构**
|参数 |类型 |说明 |
|:- |:- |:- |
|left |Number |安全区域左上角横坐标 |
|right |Number |安全区域右下角横坐标 |
|top |Number |安全区域左上角纵坐标 |
|bottom |Number |安全区域右下角纵坐标 |
|width |Number |安全区域的宽度,单位逻辑像素 |
|height |Number |安全区域的高度,单位逻辑像素 |
**safeAreaInsets 的结构**
|参数 |类型 |说明 |
|:- |:- |:- |
|left |Number |安全区域左侧插入位置 |
|right |Number |安全区域右侧插入位置 |
|top |Number |安全区顶部插入位置 |
|bottom |Number |安全区域底部插入位置 |
\ No newline at end of file
### 系统信息的概念
uni-app提供了同步(`uni.getSystemInfo`)和异步(`uni.getSystemInfoSync`)的2个API获取系统信息。
系统信息返回的内容非常多,各操作系统、各家小程序、各浏览器对它们的定义也不相同。uni-app里重新梳理了这些概念,同时为了向下兼容也保留了这些平台原来的概念,但不推荐使用。
按照运行环境层级排序,从底层向上,共有6个概念:
- `device`:运行应用的设备,如iphone、huawei
- `os`:运行应用的操作系统,如 ios、andriod、windows、mac、linux
- `rom`:Android系统特有概念,如miui、鸿蒙
- `host`:运行应用的宿主程序,即OS和应用之间的运行环境,如浏览器、微信、集成uniMPSDK的App
- `uni`:uni-app框架相关的信息,如uni-app框架版本
- `app`:开发者的应用相关的信息,如app版本
### uni.getSystemInfo(OBJECT)
获取系统信息。
异步获取系统信息
**OBJECT 参数说明:**
......@@ -11,58 +25,52 @@
**success 返回参数说明:**
|参数分类 |参数 |说明 |App平台值域 |Web平台值域 |小程序平台值域 |平台差异说明 |uni框架版本要求 |
|:- |:- |:- |:- |:- |:- |:- |:- |
|device |deviceId |设备 id 。由 uni-app 框架生成并存储,清空 Storage 会导致改变 | | | | | |
| |deviceType |设备类型 |`phone``pad``pc`|`phone``pad``pc`|`phone``pad``pc`| |`uni-app (3.4.10+)` |
| |deviceBrand |设备品牌。如:`apple``huawei` | |部分设备无法获取 | | |`uni-app (3.4.10+)` |
| |deviceModel |设备型号 | |部分设备无法获取 | | |`uni-app (3.4.10+)` |
| |devicePixelRatio |设备像素比 | | | | |`uni-app (3.4.13+)` |
| |deviceOrientation |设备方向 |`竖屏 portrait``横屏 landscape`|`竖屏 portrait``横屏 landscape`|`竖屏 portrait``横屏 landscape`|小程序端仅`微信小程序``百度小程序`支持|`uni-app (3.4.13+)` |
|os |osName |系统名称|ios、android|ios、android、windows、macos、linux|ios、android、windows、macos| |`uni-app (3.4.10+)`|
| |osVersion |操作系统版本。如 ios 版本,andriod 版本| | | | |`uni-app (3.4.10+)` |
| |osLanguage |操作系统语言 |`zh-CN 中文简体``zh-TW 中文繁体``en-US English``bo-CN 藏文``ug-CN 维吾尔语`等 |与浏览器语言一致 |不支持 | |`uni-app (3.4.10+)` |
| |osTheme |操作系统主题。 |light、dark|不支持 |不支持 | |`uni-app (3.4.10+)`
|browser |browserName |浏览器名称或App平台系统webview名称|系统 webview 名称,wkwebview、chrome |chrome、edge、safari、firefox |不支持||`uni-app (3.4.10+)`|
| |browseVersion |浏览器版本、webview 版本| | |不支持 | |`uni-app (3.4.10+)`|
|host |hostName |App、小程序宿主名称,如:`WeChat``FeiShu`。Web 端为浏览器名称 |仅UniMPSDK 支持 |浏览器名称|宿主应用名称|微信小程序真机运行才有真值|`uni-app (3.4.10+)` |
| |hostVersion |App、小程序宿主版本。如:微信版本号。Web 端为浏览器版本|仅UniMPSDK 支持 |浏览器版本|小程序宿主版本| |`uni-app (3.4.10+)` |
| |hostLanguage |浏览器语言、小程序宿主语言、app 语言|仅UniMPSDK 支持 |与浏览器语言一致|小程序宿主语言| |`uni-app (3.4.10+)` |
| |hostTheme |App 主题 `light``dark`。小程序端为系统当前主题|仅UniMPSDK 支持 |不支持|`light``dark`|仅微信小程序全局配置"darkmode":true时才能获取|`uni-app (3.4.10+)` |
| |hostPackageName |小程序宿主包名。仅 App 支持|仅UniMPSDK 支持 |不支持|不支持| |`uni-app (3.4.10+)`|
| |hostSDKVersion |客户端基础库版本|仅UniMPSDK 支持 |不支持|| |`uni-app (3.4.13+)`|
| |hostFontSizeSetting |用户字体大小设置。以“我-设置-通用-字体大小”中的设置为准,单位:px|不支持|不支持||微信小程序、支付宝小程序、百度小程序、QQ小程序、字节小程序(2.53.0+)|`uni-app (3.4.13+)`|
|uni-app框架 |uniPlatform |uni-app 运行平台。取值见下。|-|-|-| |`uni-app (3.4.10+)`|
| |uniCompileVersion |uni 编译器版本号|`3.4.10``3.2.9` 等|`3.4.10``3.2.9` 等|`3.4.10``3.2.9` 等| |`uni-app (3.4.10+)`|
| |uniRuntimeVersion |uni 运行时版本|`3.4.10``3.2.9` 等|`3.4.10``3.2.9` 等|`3.4.10``3.2.9` 等| |`uni-app (3.4.10+)`|
|app |appId |`manifest.json` 中应用appid,即DCloud appid。 | | | | |`uni-app (3.4.10+)`|
| |appName |`manifest.json` 中应用名称。和`字节跳动小程序`字段冲突,原字段与`hostName`一致 | | | | |`uni-app (3.4.10+)`|
| |appVersion |`manifest.json` 中应用版本名称。 | | | | |`uni-app (3.4.10+)`|
| |appVersionCode |`manifest.json` 中应用版本名号。 | | | | |`uni-app (3.4.10+)`|
| |appLanguage |应用设置的语言|`en``zh-Hans``zh-Hant``fr``es`|`en``zh-Hans``zh-Hant``fr``es`|不支持||`uni-app (3.4.13+)`|
|rom |romName |rom 名称|Android 部分机型获取不到值。iOS 恒为 `ios`|不支持|不支持| |`uni-app (3.4.13+)` |
| |romVersion |rom 版本|Android 部分机型获取不到值。iOS 恒为 `ios 版本号`|不支持|不支持| |`uni-app (3.4.13+)` |
|其他 |ua | userAgent标识 | | |不支持 | |`uni-app (3.4.10+)` |
| |screenWidth |屏幕宽度| | | | | |
| |screenHeight |屏幕高度 | | | | | |
| |windowWidth |可使用窗口宽度 | | | | | |
| |windowHeight |可使用窗口高度 | | | | | |
| |windowTop |可使用窗口的顶部位置 | | | | | |
| |windowBottom |可使用窗口的底部位置 | | | | | |
| |statusBarHeight |手机状态栏的高度| | | | | |
| |safeArea |在竖屏正方向下的安全区域|App、Web、微信小程序| | | | |
| |safeAreaInsets |在竖屏正方向下的安全区域插入位置(2.5.3+)|App、Web、微信小程序|||||
某些小程序特殊的返回参数
|参数|说明|平台差异说明|
|:-|:-|:-|
|appId |`manifest.json` 中应用appid。 |`HBuilderX (3.4.10+)`|
|appName|`manifest.json` 中应用名称。和`字节跳动小程序、飞书小程序`字段冲突,原字端与`hostName`一致|`HBuilderX (3.4.10+)`|
|appVersion |`manifest.json` 中应用版本名称。 |`HBuilderX (3.4.10+)`|
|appVersionCode |`manifest.json` 中应用版本名号。 |`HBuilderX (3.4.10+)`|
|deviceId|设备 id|非 App 端由 uni-app 框架生成并存储,清空 Storage 会导致改变|
|deviceBrand|设备品牌。如:`apple``huawei`|`HBuilderX (3.4.10+)`。H5 端部分设备无法获取具体品牌|
|deviceModel|设备型号 |`HBuilderX (3.4.10+)`。H5 端部分设备无法获取具体品牌|
|deviceType|设备类型。`phone``pad``pc` |`HBuilderX (3.4.10+)`|
|osName |ios、android、windows、mac、linux |`HBuilderX (3.4.10+)`|
|osVersion |操作系统版本。如 ios 版本,andriod 版本 |`HBuilderX (3.4.10+)`|
|osLanguage |操作系统语言,小程序端与 `version` 相同,H5 与浏览器语言一致 |`HBuilderX (3.4.10+)`|
|osTheme |操作系统主题 light、dark。小程序端为小程序主题 |`HBuilderX (3.4.10+)``H5 不支持`|
|hostName |App、小程序宿主名称,如:`WeChat``FeiShu`。H5 端为浏览器名称|`HBuilderX (3.4.10+)``App 端 UniMPSDK 支持`|
|hostVersion |App、小程序宿主版本。如:微信版本号。H5 端为浏览器版本 |`HBuilderX (3.4.10+)``App 端 UniMPSDK 支持`|
|hostLanguage |浏览器语言、小程序宿主语言、app 语言 |`HBuilderX (3.4.10+)``App 端 UniMPSDK 支持`|
|hostTheme |App 主题 `light``dark`。小程序端为系统当前主题 |`HBuilderX (3.4.10+)``App 端 UniMPSDK 支持``H5 不支持`|
|hostPackageName |小程序宿主包名。仅 App 支持 |`HBuilderX (3.4.10+)``仅 App 端 UniMPSDK 支持`|
|uniPlatform|uni-app 运行平台。取值见下。 |`HBuilderX (3.4.10+)`|
|uniCompileVersion| uni 编译器版本号 |`HBuilderX (3.4.10+)`|
|uniRuntimeVersion| uni 运行时版本 |`HBuilderX (3.4.10+)`|
|pixelRatio|设备像素比||
|screenWidth|屏幕宽度||
|screenHeight|屏幕高度||
|windowWidth|可使用窗口宽度||
|windowHeight|可使用窗口高度||
|windowTop|可使用窗口的顶部位置|App、H5|
|windowBottom|可使用窗口的底部位置|App、H5|
|statusBarHeight|状态栏的高度||
|system|操作系统名称及版本,如Android 10||
|language|应用设置的语言||
|version|引擎版本号|H5不支持|
|platform|客户端平台,值域为:`ios``android``mac(3.1.10+)``windows(3.1.10+)``linux(3.1.10+)`||
|safeArea|在竖屏正方向下的安全区域|App、H5、微信小程序|
|safeAreaInsets|在竖屏正方向下的安全区域插入位置(2.5.3+)|App、H5、微信小程序|
|ua| 用户标识 |`HBuilderX (3.4.10+)``小程序不支持`|
|browserName | 浏览器名称。`App` 端是系统 webview 的名字,比如 wkwebview、chrome |`HBuilderX (3.4.10+)``小程序不支持`|
|browseVersion | 浏览器版本、webview 版本 |`HBuilderX (3.4.10+)``小程序不支持`|
|fontSizeSetting|用户字体大小设置。以“我-设置-通用-字体大小”中的设置为准,单位:px|微信小程序、支付宝小程序、百度小程序、QQ小程序、字节小程序(2.53.0+)|
|brand|设备品牌(不推荐使用)|App、微信小程序、百度小程序、字节跳动小程序、飞书小程序、QQ小程序|
|model|设备型号(不推荐使用)|全平台支持。H5 端部分设备无法获取具体型号|
|SDKVersion|客户端基础库版本|支付宝小程序和H5不支持|
|cacheLocation|上一次缓存的位置信息|百度小程序|
|host|宿主平台|百度小程序|
|navigationBarHeight|导航栏的高度|百度小程序|
|swanNativeVersion|宿主平台版本号|百度小程序|
|titleBarHeight|标题栏高度|支付宝小程序|
|storage|设备磁盘容量|支付宝小程序|
|currentBattery|当前电量百分比|支付宝小程序|
|app|当前运行的客户端|支付宝小程序|
|AppPlatform|App平台|QQ小程序|
|benchmarkLevel|设备性能等级。取值为:-2 或 0(该设备无法运行小游戏),-1(性能未知),>=1(设备性能值,该值越高,设备性能越好,目前最高不到50)|微信小程序Android版、QQ小程序Android版|
|batteryLevel | 剩余电量百分比(仅 iOS 有效) |微信小程序|
|albumAuthorized | 允许微信使用相册的开关(仅 iOS 有效) |微信小程序|
......@@ -76,16 +84,36 @@
|bluetoothEnabled | 蓝牙的系统开关 |微信小程序|
|locationEnabled | 地理位置的系统开关 |微信小程序|
|wifiEnabled | Wi-Fi 的系统开关 |微信小程序|
|cacheLocation|上一次缓存的位置信息|百度小程序|
|navigationBarHeight|导航栏的高度|百度小程序|
|titleBarHeight|标题栏高度|支付宝小程序|
|storage|设备磁盘容量|支付宝小程序|
|currentBattery|当前电量百分比|支付宝小程序|
不推荐使用的返回参数,仅为向下兼容保留
|参数|说明|平台差异说明|
|:-|:-|:-|
|pixelRatio |设备像素比 | |
|brand|设备品牌|App、微信小程序、百度小程序、字节跳动小程序、飞书小程序、QQ小程序|
|model|设备型号|全平台支持。Web 端部分设备无法获取具体型号|
|system|操作系统名称及版本,如Android 10||
|language|应用设置的语言||
|version|引擎版本号|Web不支持|
|platform|客户端平台,值域为:`ios``android``mac(3.1.10+)``windows(3.1.10+)``linux(3.1.10+)`||
|host|宿主平台|百度小程序|
|SDKVersion|客户端基础库版本|支付宝小程序和Web不支持|
|swanNativeVersion|宿主平台版本号|百度小程序|
|app|当前运行的客户端|支付宝小程序|
|AppPlatform|App平台|QQ小程序|
|fontSizeSetting|用户字体大小设置。以“我-设置-通用-字体大小”中的设置为准,单位:px|微信小程序、支付宝小程序、百度小程序、QQ小程序、字节小程序(2.53.0+)|
**Tips**
- 屏幕高度 = 原生NavigationBar高度(含状态栏高度)+ 可使用窗口高度 + 原生TabBar高度
- windowHeight不包含NavigationBar和TabBar的高度
- H5端,windowTop等于NavigationBar高度,windowBottom等于TabBar高度
- Web端,windowTop等于NavigationBar高度,windowBottom等于TabBar高度
- App端,windowTop等于透明状态NavigationBar高度,windowBottom等于透明状态TabBar高度
- 高度相关信息,要放在 onReady 里获取
- `device 概念`:运行应用的设备
- `os 概念`:运行应用的操作系统,如 iOS 系统、Andriod 系统
- `host 概念`:运行应用的主程序,如 微信应用、浏览器、使用 uni 小程序 SDK 的 uni-app 应用
**safeArea 的结构**
......@@ -112,7 +140,7 @@
|值|生效条件|
|:-|:-|
|app|App|
|web|H5|
|web|Web|
|mp-weixin|微信小程序|
|mp-alipay|支付宝小程序|
|mp-baidu|百度小程序|
......@@ -121,17 +149,11 @@
|mp-qq|QQ小程序|
|mp-kuaishou|快手小程序|
|mp-jd|京东小程序|
|MP-360|360小程序|
|mp-360|360小程序|
|quickapp-webview|快应用通用(包含联盟、华为)|
|quickapp-webview-union|快应用联盟|
|quickapp-webview-huawei|快应用华为|
**设备概念全景图**
||App|Web|小程序|UniMPSDK|
|:-:|:-:|:-:|:-:|:-:|
|device 设备|huawei、iphone、vivo、oppo等|-|huawei、iphone、vivo、oppo等|huawei、iphone、vivo、oppo等|
|OS 操作系统|windows、mac、linux、android、ios|pc、windows、mac、linux、android、ios|windows、mac、linux、android、ios|android、ios|
|host 宿主应用|-|chrome、firfox、edge、safari|weChat、baidu、alipay、feishu等|uni-app 应用、5 Plus 应用|
**示例**
......@@ -150,7 +172,7 @@ uni.getSystemInfo({
```
### uni.getSystemInfoSync()
获取系统信息同步接口。`同上getSystemInfo`
获取系统信息的同步接口。`返回值同上getSystemInfo`
**示例**
......@@ -172,14 +194,14 @@ try {
**获取设备标记**
H5、小程序、iOS,属于对用户隐私保护比较严格的平台,在这些平台很难获取有效的设备唯一标记。
Web、小程序、iOS,属于对用户隐私保护比较严格的平台,在这些平台很难获取有效的设备唯一标记。
Android已经改进用户隐私保护,在很多新手机上,获取imei等信息时需要弹框让用户授权。而Android10已经无法获取imei了。
- H5平台:
- Web平台:
常用的方式是uv,即在uni.storage里存一个随机数,本质是存在浏览器的localstorage里。将随机数发给服务器,进行用户身份识别和统计。当然如果用户浏览器清空了localstorage、更换了浏览器、或使用隐私模式,那么就统计数据就会有误差。
- 小程序平台:
小程序也可以采用与H5类似的方式,在uni.storage里存一个随机数。如果想获取用户的微信唯一ID,也可以弹框请求用户授权。
小程序也可以采用与Web类似的方式,在uni.storage里存一个随机数。如果想获取用户的微信唯一ID,也可以弹框请求用户授权。
- App iOS平台:
iOS并不提供imei的获取API,可通过[plus.device.getInfo](http://www.html5plus.org/doc/zh_cn/device.html#plus.device.getInfo) 可以获得设备的唯一标识(uuid),这个id其实也是一种随机数概念,类似于h5的uv计算,卸载app重装会发生变化;
......@@ -198,9 +220,9 @@ Android10以上,部分国产手机支持OAID,详见[匿名设备标识符(
平台差异说明
|App|H5|微信小程序|支付宝小程序|百度小程序|字节跳动小程序、飞书小程序|QQ程序|
|App|Web|微信小程序|支付宝小程序|百度小程序|字节跳动小程序、飞书小程序|QQ程序|
|:-:|:-:|:-:|:-:|:-:|:-:|:-:|
|√|√ (3.4.11 +)|√|√|√|√|√|
|√|x|√|√|√|√|√|
**String 参数说明**
......
Markdown is supported
0% .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑!
想要评论请 注册