 跨端实现与权限实战)
示例工程前端移动开发跨平台【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址https://gitcode.com/gh_mirrors/un/uni-app点击查看免费下载本篇技术指南围绕 uni-app xuni-app 跨端框架的下一代演进基于 UTS 语言提供的uni.getSystemSetting()API 展开讲解如何同步读取设备蓝牙、Wi-Fi、定位开关状态与设备方向等系统设置。文档主体与配套源码位于 docs/api/get-system-setting.md 及 src/uni_modules/uni-getSystemSetting 插件目录。读完本文你将掌握该 API 的完整返回结构、各平台Android/iOS/HarmonyOS/微信小程序的兼容性差异与底层实现原理并能基于仓库示例编写可运行的系统设置读取页面、正确处理权限缺失场景。一、API 概览什么是 uni.getSystemSetting()uni.getSystemSetting()是一个同步API用于获取当前设备的系统级设置状态包括蓝牙是否开启、地理位置服务是否开启、Wi-Fi 是否开启以及当前设备方向横屏/竖屏。它不需要任何参数直接返回一个GetSystemSettingResult对象const res uni.getSystemSetting();从 接口定义 可以看到其类型签名export type GetSystemSetting () GetSystemSettingResult也就是说调用该 API 时无需传入任何配置调用后立即拿到结果非常适合在页面初始化、权限检查或功能入口前判断系统环境。平台兼容性| Web | 微信小程序 | Android | iOS | HarmonyOS | | :- | :- | :- | :- | :- | | 不支持x | 4.41 | 3.9 | 4.11 | 4.61 |兼容性说明Web 端完全不支持调用无效该 API 仅面向 App 与小程序场景微信小程序自基础库 4.41 起支持App 端三个平台的支持版本分别标注在 interface.uts 的uniPlatform注释中Android 需 uni-app x 3.9iOS 需 4.11HarmonyOS 需 uni-app x 4.61uniVer标注的 4.25/4.31 为 uni-app 编译器版本号unixVer才是 uni-app x 版本号除微信小程序外支付宝、百度、抖音、飞书Lark、QQ、快手、京东等小程序平台在 uni-app x 中均未实现标注为x。二、返回值 GetSystemSettingResult 属性详解调用uni.getSystemSetting()后返回的GetSystemSettingResult对象共包含 6 个属性| 名称 | 类型 | 必备 | 描述 | | :- | :- | :- | :- | | bluetoothEnabled | boolean | 否 | 蓝牙是否开启 | | bluetoothError | string | 否 | 蓝牙的报错信息 | | locationEnabled | boolean | 是 | 位置服务是否开启 | | wifiEnabled | boolean | 否 | Wi-Fi 是否开启 | | wifiError | string | 否 | Wi-Fi 的报错信息 | | deviceOrientation | string | 是 | 设备方向 |各属性的平台差异对照 interface.uts 中每个字段的uniPlatform注释可以精确还原各平台支持情况bluetoothEnabled / bluetoothError微信小程序 4.41、Android 3.9、iOS 4.11、HarmonyOS 4.61 均支持Web 不支持。locationEnabled所有支持该 API 的平台均返回必备字段用于判断系统定位总开关。wifiEnabled / wifiError注意差异——微信小程序与 Android、HarmonyOS 支持iOS 不支持 Wi-Fi 状态读取标注为x因此 iOS 上不会返回这两个字段。deviceOrientation所有平台均返回必备字段。deviceOrientation 合法值| 合法值 | 描述 | | :- | :- | | portrait | 纵向竖屏 | | landscape | 横向横屏 |在类型定义中该字段被声明为字符串字面量联合类型deviceOrientation: /** * 纵向 */ portrait | /** * 横向 */ landscape,这表示返回结果只会是portrait或landscape两者之一便于开发者直接进行类型安全的判断。关于返回字段为空的说明bluetoothEnabled、wifiEnabled是可选属性在平台不支持、或权限不足导致无法读取时可能为undefined而locationEnabled与deviceOrientation是必备字段任何支持平台上都会返回明确值。示例代码中正是通过res.bluetoothEnabled ?? false这样的空值合并写法来兜底避免undefined影响布尔判断。三、各平台底层实现原理源码级解析作为 UTS 插件实现uni-getSystemSetting 按平台拆分实现位于utssdk目录下各平台编译为目标平台原生语言Android 编译为 Kotlin、iOS 编译为 Swift、HarmonyOS 编译为 ArkTS。下面逐一分析其底层读取逻辑。3.1 AndroidDeviceUtil 工具类Android 入口 app-android/index.uts 首先构造基础结果再分别读取蓝牙与 Wi-Fi 状态并使用try/catch捕获权限异常export const getSystemSetting : GetSystemSetting () : GetSystemSettingResult { let context UTSAndroid.getAppContext(); let result : GetSystemSettingResult { deviceOrientation : DeviceUtil.deviceOrientation(context!), locationEnabled : DeviceUtil.locationEnable(context!), }; try { let blueToothEnable DeviceUtil.blueToothEnable(context!); result.bluetoothEnabled blueToothEnable; } catch (e : Exception) { result.bluetoothError Missing permissions required by BluetoothAdapter.isEnabled: android.permission.BLUETOOTH; } try { result.wifiEnabled DeviceUtil.wifiEnable(context!); } catch (e : Exception) { result.wifiError Missing permissions required by WifiManager.isWifiEnabled: android.permission.ACCESS_WIFI_STATE; } return result; }具体读取逻辑封装在 app-android/device/DeviceUtil.uts 中蓝牙状态Android 6.0API 23及以上会先通过context.checkSelfPermission(Manifest.permission.BLUETOOTH)检查蓝牙权限若被拒绝则直接抛出异常随后通过BluetoothManager.getAdapter().isEnabled()判断蓝牙是否开启。定位状态Android 9API 28及以上使用LocationManager.isLocationEnabled()读取系统定位总开关低版本则回退读取Settings.Secure.LOCATION_MODE设置项与LOCATION_MODE_OFF比较。Wi-Fi 状态通过WifiManager.getWifiState()与WifiManager.WIFI_STATE_ENABLED比较判断。设备方向读取Resources.getConfiguration().orientation与ORIENTATION_PORTRAIT/ORIENTATION_LANDSCAPE比对后映射为portrait/landscape其余情况返回空字符串。从实现可见蓝牙与 Wi-Fi 的读取依赖对应权限未配置权限时 API 不会崩溃而是把错误信息写入bluetoothError/wifiError字段。3.2 iOS原生桥接 UTSiOS.getSystemSetting()iOS 实现 app-ios/index.uts 直接调用框架层提供的原生方法UTSiOS.getSystemSetting()返回一个Map随后逐字段取出并装配成GetSystemSettingResultexport const getSystemSetting : GetSystemSetting () : GetSystemSettingResult { let setting : Mapstring, any UTSiOS.getSystemSetting(); let result : GetSystemSettingResult { deviceOrientation: portrait, locationEnabled : false }; ... }值得注意的是iOS 端deviceOrientation默认初始化为portrait、locationEnabled默认false再根据原生返回的 Map 中实际存在的键覆盖更新。由于 iOS 不提供 Wi-Fi 状态读取对应文档中wifiError在 iOS 标注为x该字段在 iOS 上不会返回。3.3 HarmonyOSArkTS 系统能力封装鸿蒙实现 app-harmony/index.uts 使用了defineSyncApi定义同步 API并调用鸿蒙系统 Kit 能力设备方向通过display.getDefaultDisplaySync().orientation判断PORTRAIT或PORTRAIT_INVERTED归为portrait其余归为landscape蓝牙access.getState() access.BluetoothState.STATE_ON来自kit.ConnectivityKit定位geoLocationManager.isLocationEnabled()来自kit.LocationKitWi-FiwifiManager.isWifiActive()来自kit.ConnectivityKit。与 Android 一致的容错策略是蓝牙与 Wi-Fi 读取均包裹在try/catch中异常时把BusinessError.message写入对应的bluetoothError/wifiError字段。四、完整可运行示例hello uni-app x 页面官方示例页面位于仓库 src/pages/API/get-system-setting/get-system-setting.uvue与 docs/api/get-system-setting.md 中给出的示例一致。页面 UI 上展示蓝牙开关、定位开关、Wi-Fi 开关与设备方向四个只读输入框点击按钮后调用 API 填充数据template view classuni-common-mt view classuni-list view classuni-list-cell view classuni-pd view classuni-label stylewidth:180px;蓝牙的系统开关/view /view view classuni-list-cell-db input typetext :disabledtrue placeholder未获取 :valuedata.bluetoothEnabled / /view /view !-- 地理位置的系统开关 / Wi-Fi 的系统开关 / 设备方向 结构相同 -- /view view classuni-padding-wrap view classuni-btn-v button typeprimary tapgetSystemSetting获取系统设置/button /view /view /view /template script setup languts type DataType { bluetoothEnabled: string; locationEnabled: string; wifiEnabled: string; deviceOrientation: string; } const title ref(getSystemSetting) const data reactive({ bluetoothEnabled: , locationEnabled: , wifiEnabled: , deviceOrientation: } as DataType) const getSystemSetting () { const res uni.getSystemSetting(); data.bluetoothEnabled (res.bluetoothEnabled ?? false) ? 开启 : 关闭; data.locationEnabled res.locationEnabled ? 开启 : 关闭; data.wifiEnabled (res.wifiEnabled ?? false) ? 开启 : 关闭; data.deviceOrientation res.deviceOrientation if (res.bluetoothError ! null) { data.bluetoothEnabled 无蓝牙权限 } if (res.wifiError ! null) { data.wifiEnabled 无WiFi权限 } } /script示例要点解读??空值合并由于bluetoothEnabled、wifiEnabled是可选字段部分平台不返回用?? false保证三元判断永远可用错误提示透出当bluetoothError/wifiError非空时直接把 UI 文案置为“无蓝牙权限”“无WiFi权限”即错误字段既承担诊断信息、又可直接映射为用户提示该 API 为同步调用无需async/await页面中可直接在事件回调里读取结果。注意由于 Web 端不支持请将示例运行到 App 平台Android/iOS/HarmonyOS 真机或模拟器体验。五、注意事项与权限配置官方文档中明确指出如果出现bluetoothError、wifiError非空的情况就说明权限配置错误需要根据文档正确配置权限。结合 Android 实现 的源码可以精确确认各平台所需权限| 平台 | 能力 | 所需权限 | 缺失时表现 | | :- | :- | :- | :- | | Android | 蓝牙状态 |android.permission.BLUETOOTH|bluetoothError非空 | | Android | Wi-Fi 状态 |android.permission.ACCESS_WIFI_STATE|wifiError非空 | | HarmonyOS | 蓝牙/定位/Wi-Fi | 对应系统 Kit 能力 | 写入对应*Error字段 | | iOS | 蓝牙/定位 | 由框架层UTSiOS.getSystemSetting()处理 | 不返回或返回错误字段 |在 App 端Android 原生权限的声明需要配置在原生工程中具体配置方法可参考仓库内 app-nativeresource-android.md 文档中关于权限permissions的说明章节。此外仓库根目录 AndroidManifest.xml 是 App 端工程清单文件的参考实现可对照检查权限声明。排查建议如果bluetoothError出现Missing permissions required by BluetoothAdapter.isEnabled: android.permission.BLUETOOTH字样说明 Android 工程未声明蓝牙权限如果wifiError出现Missing permissions required by WifiManager.isWifiEnabled: android.permission.ACCESS_WIFI_STATE字样说明未声明 Wi-Fi 状态读取权限定位开关locationEnabled的读取在 Android 上不依赖运行时权限但如果你后续要使用定位功能仍需按定位 API 的要求申请ACCESS_FINE_LOCATION/ACCESS_COARSE_LOCATION由于 Web 不支持、且各小程序平台支持度不一详见 interface.uts 的uniPlatform注释建议在调用前使用条件编译或平台判断避免在 Web 端误用。六、自动化测试行为契约验证仓库为getSystemSetting提供了自动化测试用例 src/pages/API/get-system-setting/get-system-setting.test.js从中可以提炼出 API 的行为契约Web 与 App WebView 环境直接跳过测试呼应“不支持 Web”测试断言若bluetoothEnabled为undefined或false则bluetoothError必须非空——即蓝牙未开启或权限缺失必然伴随错误信息反之若bluetoothEnabled为true则bluetoothError应为undefined——成功读取时不得有错误信息Wi-Fi 字段遵循同样的互斥逻辑deviceOrientation的取值必须落在[portrait, landscape]集合内即返回值的合法范围是强约束。这套测试也印证了文档中返回字段的设计意图bluetoothEnabled/bluetoothError、wifiEnabled/wifiError是“成对出现”的状态与诊断信息任何一次调用都能明确区分“已开启 / 已关闭 / 无法读取权限问题”三种情况。七、典型应用场景功能入口引导进入蓝牙配对、扫码、地图等页面之前先判断系统开关是否打开未打开时弹出提示引导用户去系统设置开启横竖屏适配判断根据deviceOrientation动态调整 UI 布局或提示用户旋转设备权限自助诊断把bluetoothError/wifiError直接展示给用户说明是权限配置问题而非功能不可用与 getSystemInfo 互补uni.getSystemSetting()关注“系统设置开关”而 get-system-info 关注设备信息与硬件参数两者可组合使用构建完整的设备环境画像。八、延伸阅读API 官方说明docs/api/get-system-setting.md本文档原始出处插件实现源码src/uni_modules/uni-getSystemSetting类型定义与平台标注src/uni_modules/uni-getSystemSetting/utssdk/interface.utsAndroid 实现src/uni_modules/uni-getSystemSetting/utssdk/app-android/index.utsHarmonyOS 实现src/uni_modules/uni-getSystemSetting/utssdk/app-harmony/index.utsiOS 实现src/uni_modules/uni-getSystemSetting/utssdk/app-ios/index.uts示例页面src/pages/API/get-system-setting/get-system-setting.uvue自动化测试src/pages/API/get-system-setting/get-system-setting.test.jsAndroid 原生权限配置docs/collocation/app-nativeresource-android.md此外GeneralCallbackResult是 uni-app x 通用错误回调类型含errMsg字段详见 docs/api/get-system-setting.md 末尾的“通用类型”一节可供理解其他 API 的错误信息结构时参考。赞分享示例工程前端移动开发跨平台【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址https://gitcode.com/gh_mirrors/un/uni-app点击查看免费下载相关推荐uni-app x 系统分享插件 uni-shareWithSystem跨端调用系统分享的 UTS 实现与实战指南uni app x 系统分享插件 uni shareWithSystem跨端调用系统分享的 UTS 实现与实战指南 本篇技术指南聚焦 uni app x 生态示例工程前端移动开发跨平台uni-app x 权限管理实战uni.openAppAuthorizeSetting 跳转系统授权管理页完全指南uni app x 权限管理实战uni.openAppAuthorizeSetting 跳转系统授权管理页完全指南 导读 uni.openAppAuthori示例工程前端移动开发跨平台uni-app x 网络类型获取指南uni.getNetworkType 跨端实现与源码解析uni app x 网络类型获取指南uni.getNetworkType 跨端实现与源码解析 获取设备当前网络类型Wi Fi、2G/3G/4G/5G、无网络示例工程前端移动开发跨平台创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
uni-app x 系统设置读取指南：uni.getSystemSetting() 跨端实现与权限实战
示例工程前端移动开发跨平台【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址https://gitcode.com/gh_mirrors/un/uni-app点击查看免费下载本篇技术指南围绕 uni-app xuni-app 跨端框架的下一代演进基于 UTS 语言提供的uni.getSystemSetting()API 展开讲解如何同步读取设备蓝牙、Wi-Fi、定位开关状态与设备方向等系统设置。文档主体与配套源码位于 docs/api/get-system-setting.md 及 src/uni_modules/uni-getSystemSetting 插件目录。读完本文你将掌握该 API 的完整返回结构、各平台Android/iOS/HarmonyOS/微信小程序的兼容性差异与底层实现原理并能基于仓库示例编写可运行的系统设置读取页面、正确处理权限缺失场景。一、API 概览什么是 uni.getSystemSetting()uni.getSystemSetting()是一个同步API用于获取当前设备的系统级设置状态包括蓝牙是否开启、地理位置服务是否开启、Wi-Fi 是否开启以及当前设备方向横屏/竖屏。它不需要任何参数直接返回一个GetSystemSettingResult对象const res uni.getSystemSetting();从 接口定义 可以看到其类型签名export type GetSystemSetting () GetSystemSettingResult也就是说调用该 API 时无需传入任何配置调用后立即拿到结果非常适合在页面初始化、权限检查或功能入口前判断系统环境。平台兼容性| Web | 微信小程序 | Android | iOS | HarmonyOS | | :- | :- | :- | :- | :- | | 不支持x | 4.41 | 3.9 | 4.11 | 4.61 |兼容性说明Web 端完全不支持调用无效该 API 仅面向 App 与小程序场景微信小程序自基础库 4.41 起支持App 端三个平台的支持版本分别标注在 interface.uts 的uniPlatform注释中Android 需 uni-app x 3.9iOS 需 4.11HarmonyOS 需 uni-app x 4.61uniVer标注的 4.25/4.31 为 uni-app 编译器版本号unixVer才是 uni-app x 版本号除微信小程序外支付宝、百度、抖音、飞书Lark、QQ、快手、京东等小程序平台在 uni-app x 中均未实现标注为x。二、返回值 GetSystemSettingResult 属性详解调用uni.getSystemSetting()后返回的GetSystemSettingResult对象共包含 6 个属性| 名称 | 类型 | 必备 | 描述 | | :- | :- | :- | :- | | bluetoothEnabled | boolean | 否 | 蓝牙是否开启 | | bluetoothError | string | 否 | 蓝牙的报错信息 | | locationEnabled | boolean | 是 | 位置服务是否开启 | | wifiEnabled | boolean | 否 | Wi-Fi 是否开启 | | wifiError | string | 否 | Wi-Fi 的报错信息 | | deviceOrientation | string | 是 | 设备方向 |各属性的平台差异对照 interface.uts 中每个字段的uniPlatform注释可以精确还原各平台支持情况bluetoothEnabled / bluetoothError微信小程序 4.41、Android 3.9、iOS 4.11、HarmonyOS 4.61 均支持Web 不支持。locationEnabled所有支持该 API 的平台均返回必备字段用于判断系统定位总开关。wifiEnabled / wifiError注意差异——微信小程序与 Android、HarmonyOS 支持iOS 不支持 Wi-Fi 状态读取标注为x因此 iOS 上不会返回这两个字段。deviceOrientation所有平台均返回必备字段。deviceOrientation 合法值| 合法值 | 描述 | | :- | :- | | portrait | 纵向竖屏 | | landscape | 横向横屏 |在类型定义中该字段被声明为字符串字面量联合类型deviceOrientation: /** * 纵向 */ portrait | /** * 横向 */ landscape,这表示返回结果只会是portrait或landscape两者之一便于开发者直接进行类型安全的判断。关于返回字段为空的说明bluetoothEnabled、wifiEnabled是可选属性在平台不支持、或权限不足导致无法读取时可能为undefined而locationEnabled与deviceOrientation是必备字段任何支持平台上都会返回明确值。示例代码中正是通过res.bluetoothEnabled ?? false这样的空值合并写法来兜底避免undefined影响布尔判断。三、各平台底层实现原理源码级解析作为 UTS 插件实现uni-getSystemSetting 按平台拆分实现位于utssdk目录下各平台编译为目标平台原生语言Android 编译为 Kotlin、iOS 编译为 Swift、HarmonyOS 编译为 ArkTS。下面逐一分析其底层读取逻辑。3.1 AndroidDeviceUtil 工具类Android 入口 app-android/index.uts 首先构造基础结果再分别读取蓝牙与 Wi-Fi 状态并使用try/catch捕获权限异常export const getSystemSetting : GetSystemSetting () : GetSystemSettingResult { let context UTSAndroid.getAppContext(); let result : GetSystemSettingResult { deviceOrientation : DeviceUtil.deviceOrientation(context!), locationEnabled : DeviceUtil.locationEnable(context!), }; try { let blueToothEnable DeviceUtil.blueToothEnable(context!); result.bluetoothEnabled blueToothEnable; } catch (e : Exception) { result.bluetoothError Missing permissions required by BluetoothAdapter.isEnabled: android.permission.BLUETOOTH; } try { result.wifiEnabled DeviceUtil.wifiEnable(context!); } catch (e : Exception) { result.wifiError Missing permissions required by WifiManager.isWifiEnabled: android.permission.ACCESS_WIFI_STATE; } return result; }具体读取逻辑封装在 app-android/device/DeviceUtil.uts 中蓝牙状态Android 6.0API 23及以上会先通过context.checkSelfPermission(Manifest.permission.BLUETOOTH)检查蓝牙权限若被拒绝则直接抛出异常随后通过BluetoothManager.getAdapter().isEnabled()判断蓝牙是否开启。定位状态Android 9API 28及以上使用LocationManager.isLocationEnabled()读取系统定位总开关低版本则回退读取Settings.Secure.LOCATION_MODE设置项与LOCATION_MODE_OFF比较。Wi-Fi 状态通过WifiManager.getWifiState()与WifiManager.WIFI_STATE_ENABLED比较判断。设备方向读取Resources.getConfiguration().orientation与ORIENTATION_PORTRAIT/ORIENTATION_LANDSCAPE比对后映射为portrait/landscape其余情况返回空字符串。从实现可见蓝牙与 Wi-Fi 的读取依赖对应权限未配置权限时 API 不会崩溃而是把错误信息写入bluetoothError/wifiError字段。3.2 iOS原生桥接 UTSiOS.getSystemSetting()iOS 实现 app-ios/index.uts 直接调用框架层提供的原生方法UTSiOS.getSystemSetting()返回一个Map随后逐字段取出并装配成GetSystemSettingResultexport const getSystemSetting : GetSystemSetting () : GetSystemSettingResult { let setting : Mapstring, any UTSiOS.getSystemSetting(); let result : GetSystemSettingResult { deviceOrientation: portrait, locationEnabled : false }; ... }值得注意的是iOS 端deviceOrientation默认初始化为portrait、locationEnabled默认false再根据原生返回的 Map 中实际存在的键覆盖更新。由于 iOS 不提供 Wi-Fi 状态读取对应文档中wifiError在 iOS 标注为x该字段在 iOS 上不会返回。3.3 HarmonyOSArkTS 系统能力封装鸿蒙实现 app-harmony/index.uts 使用了defineSyncApi定义同步 API并调用鸿蒙系统 Kit 能力设备方向通过display.getDefaultDisplaySync().orientation判断PORTRAIT或PORTRAIT_INVERTED归为portrait其余归为landscape蓝牙access.getState() access.BluetoothState.STATE_ON来自kit.ConnectivityKit定位geoLocationManager.isLocationEnabled()来自kit.LocationKitWi-FiwifiManager.isWifiActive()来自kit.ConnectivityKit。与 Android 一致的容错策略是蓝牙与 Wi-Fi 读取均包裹在try/catch中异常时把BusinessError.message写入对应的bluetoothError/wifiError字段。四、完整可运行示例hello uni-app x 页面官方示例页面位于仓库 src/pages/API/get-system-setting/get-system-setting.uvue与 docs/api/get-system-setting.md 中给出的示例一致。页面 UI 上展示蓝牙开关、定位开关、Wi-Fi 开关与设备方向四个只读输入框点击按钮后调用 API 填充数据template view classuni-common-mt view classuni-list view classuni-list-cell view classuni-pd view classuni-label stylewidth:180px;蓝牙的系统开关/view /view view classuni-list-cell-db input typetext :disabledtrue placeholder未获取 :valuedata.bluetoothEnabled / /view /view !-- 地理位置的系统开关 / Wi-Fi 的系统开关 / 设备方向 结构相同 -- /view view classuni-padding-wrap view classuni-btn-v button typeprimary tapgetSystemSetting获取系统设置/button /view /view /view /template script setup languts type DataType { bluetoothEnabled: string; locationEnabled: string; wifiEnabled: string; deviceOrientation: string; } const title ref(getSystemSetting) const data reactive({ bluetoothEnabled: , locationEnabled: , wifiEnabled: , deviceOrientation: } as DataType) const getSystemSetting () { const res uni.getSystemSetting(); data.bluetoothEnabled (res.bluetoothEnabled ?? false) ? 开启 : 关闭; data.locationEnabled res.locationEnabled ? 开启 : 关闭; data.wifiEnabled (res.wifiEnabled ?? false) ? 开启 : 关闭; data.deviceOrientation res.deviceOrientation if (res.bluetoothError ! null) { data.bluetoothEnabled 无蓝牙权限 } if (res.wifiError ! null) { data.wifiEnabled 无WiFi权限 } } /script示例要点解读??空值合并由于bluetoothEnabled、wifiEnabled是可选字段部分平台不返回用?? false保证三元判断永远可用错误提示透出当bluetoothError/wifiError非空时直接把 UI 文案置为“无蓝牙权限”“无WiFi权限”即错误字段既承担诊断信息、又可直接映射为用户提示该 API 为同步调用无需async/await页面中可直接在事件回调里读取结果。注意由于 Web 端不支持请将示例运行到 App 平台Android/iOS/HarmonyOS 真机或模拟器体验。五、注意事项与权限配置官方文档中明确指出如果出现bluetoothError、wifiError非空的情况就说明权限配置错误需要根据文档正确配置权限。结合 Android 实现 的源码可以精确确认各平台所需权限| 平台 | 能力 | 所需权限 | 缺失时表现 | | :- | :- | :- | :- | | Android | 蓝牙状态 |android.permission.BLUETOOTH|bluetoothError非空 | | Android | Wi-Fi 状态 |android.permission.ACCESS_WIFI_STATE|wifiError非空 | | HarmonyOS | 蓝牙/定位/Wi-Fi | 对应系统 Kit 能力 | 写入对应*Error字段 | | iOS | 蓝牙/定位 | 由框架层UTSiOS.getSystemSetting()处理 | 不返回或返回错误字段 |在 App 端Android 原生权限的声明需要配置在原生工程中具体配置方法可参考仓库内 app-nativeresource-android.md 文档中关于权限permissions的说明章节。此外仓库根目录 AndroidManifest.xml 是 App 端工程清单文件的参考实现可对照检查权限声明。排查建议如果bluetoothError出现Missing permissions required by BluetoothAdapter.isEnabled: android.permission.BLUETOOTH字样说明 Android 工程未声明蓝牙权限如果wifiError出现Missing permissions required by WifiManager.isWifiEnabled: android.permission.ACCESS_WIFI_STATE字样说明未声明 Wi-Fi 状态读取权限定位开关locationEnabled的读取在 Android 上不依赖运行时权限但如果你后续要使用定位功能仍需按定位 API 的要求申请ACCESS_FINE_LOCATION/ACCESS_COARSE_LOCATION由于 Web 不支持、且各小程序平台支持度不一详见 interface.uts 的uniPlatform注释建议在调用前使用条件编译或平台判断避免在 Web 端误用。六、自动化测试行为契约验证仓库为getSystemSetting提供了自动化测试用例 src/pages/API/get-system-setting/get-system-setting.test.js从中可以提炼出 API 的行为契约Web 与 App WebView 环境直接跳过测试呼应“不支持 Web”测试断言若bluetoothEnabled为undefined或false则bluetoothError必须非空——即蓝牙未开启或权限缺失必然伴随错误信息反之若bluetoothEnabled为true则bluetoothError应为undefined——成功读取时不得有错误信息Wi-Fi 字段遵循同样的互斥逻辑deviceOrientation的取值必须落在[portrait, landscape]集合内即返回值的合法范围是强约束。这套测试也印证了文档中返回字段的设计意图bluetoothEnabled/bluetoothError、wifiEnabled/wifiError是“成对出现”的状态与诊断信息任何一次调用都能明确区分“已开启 / 已关闭 / 无法读取权限问题”三种情况。七、典型应用场景功能入口引导进入蓝牙配对、扫码、地图等页面之前先判断系统开关是否打开未打开时弹出提示引导用户去系统设置开启横竖屏适配判断根据deviceOrientation动态调整 UI 布局或提示用户旋转设备权限自助诊断把bluetoothError/wifiError直接展示给用户说明是权限配置问题而非功能不可用与 getSystemInfo 互补uni.getSystemSetting()关注“系统设置开关”而 get-system-info 关注设备信息与硬件参数两者可组合使用构建完整的设备环境画像。八、延伸阅读API 官方说明docs/api/get-system-setting.md本文档原始出处插件实现源码src/uni_modules/uni-getSystemSetting类型定义与平台标注src/uni_modules/uni-getSystemSetting/utssdk/interface.utsAndroid 实现src/uni_modules/uni-getSystemSetting/utssdk/app-android/index.utsHarmonyOS 实现src/uni_modules/uni-getSystemSetting/utssdk/app-harmony/index.utsiOS 实现src/uni_modules/uni-getSystemSetting/utssdk/app-ios/index.uts示例页面src/pages/API/get-system-setting/get-system-setting.uvue自动化测试src/pages/API/get-system-setting/get-system-setting.test.jsAndroid 原生权限配置docs/collocation/app-nativeresource-android.md此外GeneralCallbackResult是 uni-app x 通用错误回调类型含errMsg字段详见 docs/api/get-system-setting.md 末尾的“通用类型”一节可供理解其他 API 的错误信息结构时参考。赞分享示例工程前端移动开发跨平台【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址https://gitcode.com/gh_mirrors/un/uni-app点击查看免费下载相关推荐uni-app x 系统分享插件 uni-shareWithSystem跨端调用系统分享的 UTS 实现与实战指南uni app x 系统分享插件 uni shareWithSystem跨端调用系统分享的 UTS 实现与实战指南 本篇技术指南聚焦 uni app x 生态示例工程前端移动开发跨平台uni-app x 权限管理实战uni.openAppAuthorizeSetting 跳转系统授权管理页完全指南uni app x 权限管理实战uni.openAppAuthorizeSetting 跳转系统授权管理页完全指南 导读 uni.openAppAuthori示例工程前端移动开发跨平台uni-app x 网络类型获取指南uni.getNetworkType 跨端实现与源码解析uni app x 网络类型获取指南uni.getNetworkType 跨端实现与源码解析 获取设备当前网络类型Wi Fi、2G/3G/4G/5G、无网络示例工程前端移动开发跨平台创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考