示例工程前端移动开发跨平台【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址https://gitcode.com/gh_mirrors/un/uni-app点击查看免费下载本文以 uni-app 开源仓库中的uni-getSystemSettingUTS 插件为研究对象围绕其对外 API、跨端Android / iOS / HarmonyOS / 小程序实现原理与工程结构展开并结合仓库内的示例页面与自动化测试给出从安装、调用到权限配置的完整实战指南。读者读完可掌握如何用一行uni.getSystemSetting()读取蓝牙、定位、Wi-Fi 开关状态与设备方向并理解 UTS 插件在 uni-app x 中的组织方式。一、模块概览这个插件能做什么uni-getSystemSetting是一个以 UTSuni type script编写的 uni_modules 扩展插件其职责是获取系统设置类信息具体包括蓝牙是否开启bluetoothEnabled地理位置定位系统开关是否开启locationEnabledWi-Fi 是否开启wifiEnabled设备当前方向纵向portrait或横向landscapedeviceOrientation在 uni-app x 中它对外暴露为同步 APIuni.getSystemSetting()。从 API 规范文档 的兼容性表可见其平台支持情况| 平台 | Web | 微信小程序 | Android | iOS | HarmonyOS | | :- | :- | :- | :- | :- | :- | | 支持版本 | x不支持 | 4.41 | 3.9 | 4.11 | 4.61 |即该 API不支持 Web 平台需要运行到 App 或小程序端体验。二、UTS 语言与 UTS 插件本模块的底层技术背景2.1 uts 语言简介本插件源码全部使用 uts 编写。utsuni type script是 uni-app 生态中的一门跨平台、高性能、强类型的现代编程语言它与 TypeScript 语法基本一致支持绝大部分 ES6 API。其核心能力是同一份代码可编译为不同平台的对应语言| 目标平台 | 编译产物语言 | | -- | -- | | Android | Kotlin | | iOS | Swift | | HarmonyOS鸿蒙 | ArkTS | | Web / 小程序 | JavaScript |由于需要跨端uts 做了一些约束同时也为特定平台提供了增补语法。过去在 JS 引擎下可运行的语法大部分经 uts 处理后可以平滑地在 Kotlin 与 Swift 中继续使用但个别无法抹平的差异需要使用与 uni-app 条件编译类似机制的uts 条件编译在条件编译块内调用平台特有的扩展语法。2.2 UTS 插件与 utssdk 目录结构UTS 插件是一种特定的 uni_modules 插件其核心目的是让 uni-app / uni-app x 开发者使用 UTS 语法调用扩展 API封装原生系统 API 或三方 SDK。本仓库中的uni-getSystemSetting即属此类其实现代码全部位于utssdk目录下并按平台分离组织| 目录/文件 | 目标平台 | 实现语言 | 作用描述 | | -- | -- | -- | -- | |utssdk/app-android| Android | UTS、Kotlin、Java | UTS 插件在 Android 平台的具体实现源码 | |utssdk/app-ios| iOS | UTS、Swift | UTS 插件在 iOS 平台的具体实现源码 | |utssdk/app-harmony| HarmonyOS | UTS、ArkTS | UTS 插件在 HarmonyOS 平台的具体实现源码 | |utssdk/*.uts| 多平台共用 | UTS | 可供所有平台共用的实现源码如类型声明 |对照仓库实际结构插件目录可以清晰看到uni-getSystemSetting/ ├── readme.md ├── package.json # 插件元数据与 uni_modules 声明 ├── changelog.md └── utssdk/ ├── interface.uts # 多平台共用的类型与 API 声明 ├── app-android/ │ ├── index.uts # Android 平台入口实现 │ └── device/ │ └── DeviceUtil.uts # Android 设备工具类 ├── app-ios/ │ └── index.uts # iOS 平台入口实现 └── app-harmony/ └── index.uts # HarmonyOS 平台入口实现三、类型定义与 API 签名interface.uts 详解所有平台共享的类型声明集中在 utssdk/interface.uts它同时承载了面向开发者的 API 文档信息通过uniPlatform、tutorial、example等注释标注。3.1 返回值类型 GetSystemSettingResultexport type GetSystemSettingResult { /** 蓝牙是否开启 */ bluetoothEnabled?: boolean, /** 蓝牙的报错信息 */ bluetoothError?: string | null, /** 位置是否开启 */ locationEnabled: boolean, /** wifi是否开启 */ wifiEnabled?: boolean, /** wifi的报错信息 */ wifiError?: string | null, /** 设备方向portrait 纵向 | landscape 横向 */ deviceOrientation: portrait | landscape, }各字段属性汇总依据 API 规范文档 与 interface.uts 注释| 名称 | 类型 | 必备 | 兼容性 | 描述 | | :- | :- | :- | :-: | :- | |bluetoothEnabled| boolean | 否 | Web: x微信小程序: 4.41Android: 3.9iOS: 4.11HarmonyOS: 4.61 | 蓝牙是否开启 | |bluetoothError| string | 否 | 同上 | 蓝牙的报错信息 | |locationEnabled| boolean |是| 同上 | 位置是否开启 | |wifiEnabled| boolean | 否 | 同上 | wifi 是否开启 | |wifiError| string | 否 | Web: x微信小程序: 4.41Android: 3.9iOS: xHarmonyOS: 4.61 | wifi 的报错信息 | |deviceOrientation| string |是| 同上 | 设备方向 |其中deviceOrientation的合法值仅两个portrait纵向、landscape横向。注意两点易错细节必填字段只有两个locationEnabled与deviceOrientation是必备字段而bluetoothEnabled、bluetoothError、wifiEnabled、wifiError均为可选?业务代码访问时建议使用空值合并??兜底wifiError在 iOS 上不支持兼容性标为 x跨端开发时对 iOS 的 wifi 报错信息要按未定义处理。3.2 函数类型与 Uni 接口声明export type GetSystemSetting () GetSystemSettingResult export interface Uni { /** * 获取系统设置 * return {object} * example * uni.getSystemSetting() */ getSystemSetting(): GetSystemSettingResult; }从源码结构看GetSystemSetting被声明为同步函数类型无参数、直接返回结果对象并通过Uni接口挂载到uni全局命名空间上——这与示例页面中const res uni.getSystemSetting();的同步调用方式完全对应无回调、无 Promise。四、跨端实现原理三大原生平台的底层调用uni.getSystemSetting()之所以能同步返回结果是因为各平台实现都直接调用了系统级服务。下面逐一拆解三个平台的实现。4.1 AndroidDeviceUtil 工具类逐项探测Android 端入口 utssdk/app-android/index.uts 依赖UTSAndroid.getAppContext()获取应用上下文再调用工具类 utssdk/app-android/device/DeviceUtil.uts 完成各项探测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; }各探测逻辑的实现要点蓝牙开关blueToothEnablepublic static blueToothEnable(context: Context): boolean { if (Build.VERSION.SDK_INT 23 context.checkSelfPermission(Manifest.permission.BLUETOOTH) PackageManager.PERMISSION_DENIED) { throw new Exception(); } let bluetoothManager context.getSystemService(Context.BLUETOOTH_SERVICE) as BluetoothManager; let defaultAdapter bluetoothManager.getAdapter(); return defaultAdapter.isEnabled(); }当Build.VERSION.SDK_INT 23Android 6.0时先通过checkSelfPermission校验android.permission.BLUETOOTH权限未授予则直接抛异常异常被入口try/catch捕获后填入bluetoothError字段错误文案明确指向缺失的权限名android.permission.BLUETOOTH正常路径通过BluetoothManager.getAdapter().isEnabled()判断蓝牙适配器是否开启。位置开关locationEnable——按系统版本分两条路径public static locationEnable(context: Context): boolean { if (Build.VERSION.SDK_INT Build.VERSION_CODES.P){ let locationManager context.getSystemService(Context.LOCATION_SERVICE) as LocationManager; if (locationManager null) { return false; } return locationManager.isLocationEnabled(); }else{ const mode Settings.Secure.getInt(context.getContentResolver(), Settings.Secure.LOCATION_MODE, Settings.Secure.LOCATION_MODE_OFF); return (mode ! Settings.Secure.LOCATION_MODE_OFF); } }Android 9API 28Build.VERSION_CODES.P及以上使用LocationManager.isLocationEnabled()更早版本回退到读取Settings.Secure.LOCATION_MODE系统设置只要不等于LOCATION_MODE_OFF即视为开启。Wi-Fi 开关wifiEnablepublic static wifiEnable(context: Context): boolean { let wifiManager context.getApplicationContext().getSystemService(Context.WIFI_SERVICE) as WifiManager; let wifiState wifiManager.getWifiState(); return wifiState WifiManager.WIFI_STATE_ENABLED; }通过WifiManager.getWifiState()判断 Wi-Fi 是否处于WIFI_STATE_ENABLED状态若缺少android.permission.ACCESS_WIFI_STATE权限异常被捕获并写入wifiError。设备方向deviceOrientationpublic static deviceOrientation(context: Context): string { let configuration context.getResources().getConfiguration(); let orientation configuration.orientation; if (orientation Configuration.ORIENTATION_PORTRAIT) { return portrait; } else if (orientation Configuration.ORIENTATION_LANDSCAPE) { return landscape; } return ; }读取Resources.getConfiguration().orientation映射为portrait/landscape极端情况下方向未知返回空字符串。4.2 iOSUTSiOS 原生能力桥接iOS 端实现 utssdk/app-ios/index.uts 更为简洁——它通过DCloudUTSFoundation框架提供的UTSiOS.getSystemSetting()一次性取得全部系统设置再以Map形式逐项取出export const getSystemSetting : GetSystemSetting () : GetSystemSettingResult { let setting : Mapstring, any UTSiOS.getSystemSetting(); let result : GetSystemSettingResult { deviceOrientation: portrait, locationEnabled : false }; if (setting.has(bluetoothEnabled)) { result.bluetoothEnabled setting.get(bluetoothEnabled) as boolean; } // ... 依次处理 bluetoothError / locationEnabled / wifiEnabled / deviceOrientation return result; }值得注意的细节iOS 实现中先给deviceOrientation、locationEnabled设置了默认值portrait与false再根据原生返回的Map是否包含对应键来覆盖保证返回对象始终具备必填字段。4.3 HarmonyOSArkTS 系统 Kit 调用鸿蒙端实现 utssdk/app-harmony/index.uts 使用defineSyncApi定义同步 API并分别调用kit.ConnectivityKit、kit.LocationKit、kit.ArkUI等系统能力export const getSystemSetting: GetSystemSetting defineSyncApiGetSystemSettingResult( getSystemSetting, (): GetSystemSettingResult { const defaultDisplay display.getDefaultDisplaySync() const res: GetSystemSettingResult { bluetoothEnabled: false, bluetoothError: null, locationEnabled: false, wifiEnabled: false, wifiError: null, deviceOrientation: (defaultDisplay.orientation display.Orientation.PORTRAIT || defaultDisplay.orientation display.Orientation.PORTRAIT_INVERTED) ? portrait : landscape } try { if (access.getState() access.BluetoothState.STATE_ON) res.bluetoothEnabled true } catch (err) { res.bluetoothError (err as BusinessError).message } try { res.locationEnabled geoLocationManager.isLocationEnabled(); } catch (err) { } try { res.wifiEnabled wifiManager.isWifiActive(); } catch (err) { res.wifiError (err as BusinessError).message } return res } ) as GetSystemSetting对应关系总结| 返回字段 | HarmonyOS 底层调用 | | -- | -- | |bluetoothEnabled/bluetoothError|access.getState()与access.BluetoothState.STATE_ONConnectivityKit | |locationEnabled|geoLocationManager.isLocationEnabled()LocationKit | |wifiEnabled/wifiError|wifiManager.isWifiActive()ConnectivityKit | |deviceOrientation|display.getDefaultDisplaySync().orientationArkUI含正/倒竖屏两种竖屏判定 |4.4 小程序端uni.getSystemSetting同样在微信小程序等平台可用微信小程序版本要求 4.41。从 package.json 的uni_modules.platforms声明看该插件对 Vue 2 / Vue 3、AppAndroid/iOS、H5、各主流小程序均标记为支持不过依据 API 文档Web 平台并不支持getSystemSetting实际运行请以 App 端为准。五、插件工程元数据package.json 解读package.json 除了常规的插件 id、版本、名称外还有两个关键配置块engines声明插件要求的 HBuilderX 最低版本为^3.6.8uni_modules.uni-ext-api向编译器声明扩展 API 的注册信息——uni-ext-api: { uni: { getSystemSetting: { name: getSystemSetting, app: { js: false, kotlin: true, swift: true, arkts: true } } } }该配置说明getSystemSetting在 App 端并非 JS 实现而是分别编译到 KotlinAndroid、SwiftiOS、ArkTSHarmonyOS与前面看到的三个平台目录结构一一对应。此外sale块显示该插件定价为 0.00即作为免费公开插件随 uni-app 生态分发。六、实战调用示例页面完整代码仓库在示例工程中提供了可直接运行的演示页面 src/pages/API/get-system-setting/get-system-setting.uvue展示了最标准的调用写法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模板部分使用四个只读input分别展示「蓝牙的系统开关」「地理位置的系统开关」「Wi-Fi 的系统开关」「设备方向」并放置一个按钮触发getSystemSettingview classuni-list-cell view classuni-pd view classuni-label stylewidth:180px;text classsystem-info-text蓝牙的系统开关/text/view /view view classuni-list-cell-db input classsystem-info-input typetext :disabledtrue placeholder未获取 :valuedata.bluetoothEnabled / /view /view !-- 地理位置、Wi-Fi、设备方向 同理 -- button typeprimary tapgetSystemSetting获取系统设置/button这段示例蕴含的最佳实践可选字段务必空值合并res.bluetoothEnabled ?? false、res.wifiEnabled ?? false防止undefined直接渲染到界面优先展示错误信息当bluetoothError/wifiError非空时直接显示「无蓝牙权限」「无WiFi权限」而非布尔值帮助用户快速定位问题同步 API 直接赋值无需await或回调调用结果可立即用于界面渲染。七、权限注意事项错误信息即权限清单依据 API 规范文档 的「注意事项」如果出现bluetoothError、wifiError非空的情况就说明权限配置错误需要根据文档正确配置权限。结合 Android 实现源码两个错误信息本身就是完整的权限排查线索bluetoothError非空 → 缺少android.permission.BLUETOOTHwifiError非空 → 缺少android.permission.ACCESS_WIFI_STATE。对于 App 端开发需在原生资源如 Android 的 AndroidManifest.xml中正确声明上述权限后再构建运行。若在src/pages/API/get-system-setting/get-system-setting.test.js的自动化测试中观察也能看到对错误字段的断言逻辑当bluetoothEnabled为undefined或false时期望bluetoothError非空当wifiEnabled为undefined时期望wifiError非空——即错误信息字段被设计为权限缺失时的主要信号。八、自动化测试如何验证该 API仓库为示例页配套了端到端自动化测试 get-system-setting.test.js可作为自行验证 API 行为的参考describe(ExtApi-GetSystemSetting, () { // web 与 app-webview 环境下跳过仅做占位断言 beforeAll(async () { page await program.reLaunch(PAGE_PATH) await page.waitFor(600); res await uni.getSystemSetting() }); it(Check GetSystemSetting, async () { for (const key in res) { if (res[bluetoothEnabled] undefined || res[bluetoothEnabled] false) { expect(res[bluetoothError]).not.toBe() } else { expect(res[bluetoothError] undefined).toBe(true) } if (res[wifiEnabled] undefined) { expect(res[wifiError]).not.toBe() } else { expect(res[wifiError] undefined).toBe(true) } if (key deviceOrientation) { expect([portrait, landscape]).toContain(value); } } }); });测试要点归纳Web 与 App 内嵌 WebView 环境跳过真实断言因为该 API 不支持 Web通过program.reLaunch跳转到示例页并等待渲染后再调用uni.getSystemSetting()校验「开关关闭/缺失 → 对应 Error 非空」的联动关系校验deviceOrientation的取值只能落在[portrait, landscape]集合内。九、小结uni-getSystemSetting是理解「UTS 插件如何封装原生系统能力」的极佳范本一份 interface.uts 定义跨端统一类型三份平台实现Android / iOS / HarmonyOS各自调用系统级 API辅以 package.json 的扩展 API 注册与仓库中的示例页、自动化测试构成了一个完整可复用的 uni-app x 扩展 API 闭环。使用上只需记住三点同步调用直接取返回值、可选字段用??兜底、bluetoothError/wifiError非空即表示缺少对应权限。进一步了解 uts 语言与插件开发可参考仓库内文档如 uts 语言介绍、uts 插件开发想查看该 API 的完整官方规范说明可阅读仓库中的 get-system-setting API 文档。赞分享示例工程前端移动开发跨平台【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址https://gitcode.com/gh_mirrors/un/uni-app点击查看免费下载相关推荐uni-app最佳实践跨端开发的完整指南uni app最佳实践跨端开发的完整指南 前言为什么选择uni app 还在为多端开发而头疼吗每次新项目都要为不同平台重复编写相似代码uni app作示例工程uni-app x 事件总线完全指南uni.$on / uni.$off / uni.$once / uni.$emit 的跨端实践与源码解析uni app x 事件总线完全指南uni.$on / uni.$off / uni.$once / uni.$emit 的跨端实践与源码解析 本文档对应仓库示例工程前端移动开发跨平台uni-app x Worker 多线程开发指南uni.createWorker 完整 API 解析与跨端实践uni app x Worker 多线程开发指南uni.createWorker 完整 API 解析与跨端实践 现代 CPU 都是多核的而 uni app示例工程前端移动开发跨平台上一篇AudioSR音频超分辨率技术基于扩散模型的通用音频质量增强方案下一篇A2UI数据绑定实战教程构建动态响应的智能界面创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
uni-app 中 uni-getSystemSetting 扩展 API 解析：跨端获取系统开关状态的完整实践指南
示例工程前端移动开发跨平台【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址https://gitcode.com/gh_mirrors/un/uni-app点击查看免费下载本文以 uni-app 开源仓库中的uni-getSystemSettingUTS 插件为研究对象围绕其对外 API、跨端Android / iOS / HarmonyOS / 小程序实现原理与工程结构展开并结合仓库内的示例页面与自动化测试给出从安装、调用到权限配置的完整实战指南。读者读完可掌握如何用一行uni.getSystemSetting()读取蓝牙、定位、Wi-Fi 开关状态与设备方向并理解 UTS 插件在 uni-app x 中的组织方式。一、模块概览这个插件能做什么uni-getSystemSetting是一个以 UTSuni type script编写的 uni_modules 扩展插件其职责是获取系统设置类信息具体包括蓝牙是否开启bluetoothEnabled地理位置定位系统开关是否开启locationEnabledWi-Fi 是否开启wifiEnabled设备当前方向纵向portrait或横向landscapedeviceOrientation在 uni-app x 中它对外暴露为同步 APIuni.getSystemSetting()。从 API 规范文档 的兼容性表可见其平台支持情况| 平台 | Web | 微信小程序 | Android | iOS | HarmonyOS | | :- | :- | :- | :- | :- | :- | | 支持版本 | x不支持 | 4.41 | 3.9 | 4.11 | 4.61 |即该 API不支持 Web 平台需要运行到 App 或小程序端体验。二、UTS 语言与 UTS 插件本模块的底层技术背景2.1 uts 语言简介本插件源码全部使用 uts 编写。utsuni type script是 uni-app 生态中的一门跨平台、高性能、强类型的现代编程语言它与 TypeScript 语法基本一致支持绝大部分 ES6 API。其核心能力是同一份代码可编译为不同平台的对应语言| 目标平台 | 编译产物语言 | | -- | -- | | Android | Kotlin | | iOS | Swift | | HarmonyOS鸿蒙 | ArkTS | | Web / 小程序 | JavaScript |由于需要跨端uts 做了一些约束同时也为特定平台提供了增补语法。过去在 JS 引擎下可运行的语法大部分经 uts 处理后可以平滑地在 Kotlin 与 Swift 中继续使用但个别无法抹平的差异需要使用与 uni-app 条件编译类似机制的uts 条件编译在条件编译块内调用平台特有的扩展语法。2.2 UTS 插件与 utssdk 目录结构UTS 插件是一种特定的 uni_modules 插件其核心目的是让 uni-app / uni-app x 开发者使用 UTS 语法调用扩展 API封装原生系统 API 或三方 SDK。本仓库中的uni-getSystemSetting即属此类其实现代码全部位于utssdk目录下并按平台分离组织| 目录/文件 | 目标平台 | 实现语言 | 作用描述 | | -- | -- | -- | -- | |utssdk/app-android| Android | UTS、Kotlin、Java | UTS 插件在 Android 平台的具体实现源码 | |utssdk/app-ios| iOS | UTS、Swift | UTS 插件在 iOS 平台的具体实现源码 | |utssdk/app-harmony| HarmonyOS | UTS、ArkTS | UTS 插件在 HarmonyOS 平台的具体实现源码 | |utssdk/*.uts| 多平台共用 | UTS | 可供所有平台共用的实现源码如类型声明 |对照仓库实际结构插件目录可以清晰看到uni-getSystemSetting/ ├── readme.md ├── package.json # 插件元数据与 uni_modules 声明 ├── changelog.md └── utssdk/ ├── interface.uts # 多平台共用的类型与 API 声明 ├── app-android/ │ ├── index.uts # Android 平台入口实现 │ └── device/ │ └── DeviceUtil.uts # Android 设备工具类 ├── app-ios/ │ └── index.uts # iOS 平台入口实现 └── app-harmony/ └── index.uts # HarmonyOS 平台入口实现三、类型定义与 API 签名interface.uts 详解所有平台共享的类型声明集中在 utssdk/interface.uts它同时承载了面向开发者的 API 文档信息通过uniPlatform、tutorial、example等注释标注。3.1 返回值类型 GetSystemSettingResultexport type GetSystemSettingResult { /** 蓝牙是否开启 */ bluetoothEnabled?: boolean, /** 蓝牙的报错信息 */ bluetoothError?: string | null, /** 位置是否开启 */ locationEnabled: boolean, /** wifi是否开启 */ wifiEnabled?: boolean, /** wifi的报错信息 */ wifiError?: string | null, /** 设备方向portrait 纵向 | landscape 横向 */ deviceOrientation: portrait | landscape, }各字段属性汇总依据 API 规范文档 与 interface.uts 注释| 名称 | 类型 | 必备 | 兼容性 | 描述 | | :- | :- | :- | :-: | :- | |bluetoothEnabled| boolean | 否 | Web: x微信小程序: 4.41Android: 3.9iOS: 4.11HarmonyOS: 4.61 | 蓝牙是否开启 | |bluetoothError| string | 否 | 同上 | 蓝牙的报错信息 | |locationEnabled| boolean |是| 同上 | 位置是否开启 | |wifiEnabled| boolean | 否 | 同上 | wifi 是否开启 | |wifiError| string | 否 | Web: x微信小程序: 4.41Android: 3.9iOS: xHarmonyOS: 4.61 | wifi 的报错信息 | |deviceOrientation| string |是| 同上 | 设备方向 |其中deviceOrientation的合法值仅两个portrait纵向、landscape横向。注意两点易错细节必填字段只有两个locationEnabled与deviceOrientation是必备字段而bluetoothEnabled、bluetoothError、wifiEnabled、wifiError均为可选?业务代码访问时建议使用空值合并??兜底wifiError在 iOS 上不支持兼容性标为 x跨端开发时对 iOS 的 wifi 报错信息要按未定义处理。3.2 函数类型与 Uni 接口声明export type GetSystemSetting () GetSystemSettingResult export interface Uni { /** * 获取系统设置 * return {object} * example * uni.getSystemSetting() */ getSystemSetting(): GetSystemSettingResult; }从源码结构看GetSystemSetting被声明为同步函数类型无参数、直接返回结果对象并通过Uni接口挂载到uni全局命名空间上——这与示例页面中const res uni.getSystemSetting();的同步调用方式完全对应无回调、无 Promise。四、跨端实现原理三大原生平台的底层调用uni.getSystemSetting()之所以能同步返回结果是因为各平台实现都直接调用了系统级服务。下面逐一拆解三个平台的实现。4.1 AndroidDeviceUtil 工具类逐项探测Android 端入口 utssdk/app-android/index.uts 依赖UTSAndroid.getAppContext()获取应用上下文再调用工具类 utssdk/app-android/device/DeviceUtil.uts 完成各项探测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; }各探测逻辑的实现要点蓝牙开关blueToothEnablepublic static blueToothEnable(context: Context): boolean { if (Build.VERSION.SDK_INT 23 context.checkSelfPermission(Manifest.permission.BLUETOOTH) PackageManager.PERMISSION_DENIED) { throw new Exception(); } let bluetoothManager context.getSystemService(Context.BLUETOOTH_SERVICE) as BluetoothManager; let defaultAdapter bluetoothManager.getAdapter(); return defaultAdapter.isEnabled(); }当Build.VERSION.SDK_INT 23Android 6.0时先通过checkSelfPermission校验android.permission.BLUETOOTH权限未授予则直接抛异常异常被入口try/catch捕获后填入bluetoothError字段错误文案明确指向缺失的权限名android.permission.BLUETOOTH正常路径通过BluetoothManager.getAdapter().isEnabled()判断蓝牙适配器是否开启。位置开关locationEnable——按系统版本分两条路径public static locationEnable(context: Context): boolean { if (Build.VERSION.SDK_INT Build.VERSION_CODES.P){ let locationManager context.getSystemService(Context.LOCATION_SERVICE) as LocationManager; if (locationManager null) { return false; } return locationManager.isLocationEnabled(); }else{ const mode Settings.Secure.getInt(context.getContentResolver(), Settings.Secure.LOCATION_MODE, Settings.Secure.LOCATION_MODE_OFF); return (mode ! Settings.Secure.LOCATION_MODE_OFF); } }Android 9API 28Build.VERSION_CODES.P及以上使用LocationManager.isLocationEnabled()更早版本回退到读取Settings.Secure.LOCATION_MODE系统设置只要不等于LOCATION_MODE_OFF即视为开启。Wi-Fi 开关wifiEnablepublic static wifiEnable(context: Context): boolean { let wifiManager context.getApplicationContext().getSystemService(Context.WIFI_SERVICE) as WifiManager; let wifiState wifiManager.getWifiState(); return wifiState WifiManager.WIFI_STATE_ENABLED; }通过WifiManager.getWifiState()判断 Wi-Fi 是否处于WIFI_STATE_ENABLED状态若缺少android.permission.ACCESS_WIFI_STATE权限异常被捕获并写入wifiError。设备方向deviceOrientationpublic static deviceOrientation(context: Context): string { let configuration context.getResources().getConfiguration(); let orientation configuration.orientation; if (orientation Configuration.ORIENTATION_PORTRAIT) { return portrait; } else if (orientation Configuration.ORIENTATION_LANDSCAPE) { return landscape; } return ; }读取Resources.getConfiguration().orientation映射为portrait/landscape极端情况下方向未知返回空字符串。4.2 iOSUTSiOS 原生能力桥接iOS 端实现 utssdk/app-ios/index.uts 更为简洁——它通过DCloudUTSFoundation框架提供的UTSiOS.getSystemSetting()一次性取得全部系统设置再以Map形式逐项取出export const getSystemSetting : GetSystemSetting () : GetSystemSettingResult { let setting : Mapstring, any UTSiOS.getSystemSetting(); let result : GetSystemSettingResult { deviceOrientation: portrait, locationEnabled : false }; if (setting.has(bluetoothEnabled)) { result.bluetoothEnabled setting.get(bluetoothEnabled) as boolean; } // ... 依次处理 bluetoothError / locationEnabled / wifiEnabled / deviceOrientation return result; }值得注意的细节iOS 实现中先给deviceOrientation、locationEnabled设置了默认值portrait与false再根据原生返回的Map是否包含对应键来覆盖保证返回对象始终具备必填字段。4.3 HarmonyOSArkTS 系统 Kit 调用鸿蒙端实现 utssdk/app-harmony/index.uts 使用defineSyncApi定义同步 API并分别调用kit.ConnectivityKit、kit.LocationKit、kit.ArkUI等系统能力export const getSystemSetting: GetSystemSetting defineSyncApiGetSystemSettingResult( getSystemSetting, (): GetSystemSettingResult { const defaultDisplay display.getDefaultDisplaySync() const res: GetSystemSettingResult { bluetoothEnabled: false, bluetoothError: null, locationEnabled: false, wifiEnabled: false, wifiError: null, deviceOrientation: (defaultDisplay.orientation display.Orientation.PORTRAIT || defaultDisplay.orientation display.Orientation.PORTRAIT_INVERTED) ? portrait : landscape } try { if (access.getState() access.BluetoothState.STATE_ON) res.bluetoothEnabled true } catch (err) { res.bluetoothError (err as BusinessError).message } try { res.locationEnabled geoLocationManager.isLocationEnabled(); } catch (err) { } try { res.wifiEnabled wifiManager.isWifiActive(); } catch (err) { res.wifiError (err as BusinessError).message } return res } ) as GetSystemSetting对应关系总结| 返回字段 | HarmonyOS 底层调用 | | -- | -- | |bluetoothEnabled/bluetoothError|access.getState()与access.BluetoothState.STATE_ONConnectivityKit | |locationEnabled|geoLocationManager.isLocationEnabled()LocationKit | |wifiEnabled/wifiError|wifiManager.isWifiActive()ConnectivityKit | |deviceOrientation|display.getDefaultDisplaySync().orientationArkUI含正/倒竖屏两种竖屏判定 |4.4 小程序端uni.getSystemSetting同样在微信小程序等平台可用微信小程序版本要求 4.41。从 package.json 的uni_modules.platforms声明看该插件对 Vue 2 / Vue 3、AppAndroid/iOS、H5、各主流小程序均标记为支持不过依据 API 文档Web 平台并不支持getSystemSetting实际运行请以 App 端为准。五、插件工程元数据package.json 解读package.json 除了常规的插件 id、版本、名称外还有两个关键配置块engines声明插件要求的 HBuilderX 最低版本为^3.6.8uni_modules.uni-ext-api向编译器声明扩展 API 的注册信息——uni-ext-api: { uni: { getSystemSetting: { name: getSystemSetting, app: { js: false, kotlin: true, swift: true, arkts: true } } } }该配置说明getSystemSetting在 App 端并非 JS 实现而是分别编译到 KotlinAndroid、SwiftiOS、ArkTSHarmonyOS与前面看到的三个平台目录结构一一对应。此外sale块显示该插件定价为 0.00即作为免费公开插件随 uni-app 生态分发。六、实战调用示例页面完整代码仓库在示例工程中提供了可直接运行的演示页面 src/pages/API/get-system-setting/get-system-setting.uvue展示了最标准的调用写法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模板部分使用四个只读input分别展示「蓝牙的系统开关」「地理位置的系统开关」「Wi-Fi 的系统开关」「设备方向」并放置一个按钮触发getSystemSettingview classuni-list-cell view classuni-pd view classuni-label stylewidth:180px;text classsystem-info-text蓝牙的系统开关/text/view /view view classuni-list-cell-db input classsystem-info-input typetext :disabledtrue placeholder未获取 :valuedata.bluetoothEnabled / /view /view !-- 地理位置、Wi-Fi、设备方向 同理 -- button typeprimary tapgetSystemSetting获取系统设置/button这段示例蕴含的最佳实践可选字段务必空值合并res.bluetoothEnabled ?? false、res.wifiEnabled ?? false防止undefined直接渲染到界面优先展示错误信息当bluetoothError/wifiError非空时直接显示「无蓝牙权限」「无WiFi权限」而非布尔值帮助用户快速定位问题同步 API 直接赋值无需await或回调调用结果可立即用于界面渲染。七、权限注意事项错误信息即权限清单依据 API 规范文档 的「注意事项」如果出现bluetoothError、wifiError非空的情况就说明权限配置错误需要根据文档正确配置权限。结合 Android 实现源码两个错误信息本身就是完整的权限排查线索bluetoothError非空 → 缺少android.permission.BLUETOOTHwifiError非空 → 缺少android.permission.ACCESS_WIFI_STATE。对于 App 端开发需在原生资源如 Android 的 AndroidManifest.xml中正确声明上述权限后再构建运行。若在src/pages/API/get-system-setting/get-system-setting.test.js的自动化测试中观察也能看到对错误字段的断言逻辑当bluetoothEnabled为undefined或false时期望bluetoothError非空当wifiEnabled为undefined时期望wifiError非空——即错误信息字段被设计为权限缺失时的主要信号。八、自动化测试如何验证该 API仓库为示例页配套了端到端自动化测试 get-system-setting.test.js可作为自行验证 API 行为的参考describe(ExtApi-GetSystemSetting, () { // web 与 app-webview 环境下跳过仅做占位断言 beforeAll(async () { page await program.reLaunch(PAGE_PATH) await page.waitFor(600); res await uni.getSystemSetting() }); it(Check GetSystemSetting, async () { for (const key in res) { if (res[bluetoothEnabled] undefined || res[bluetoothEnabled] false) { expect(res[bluetoothError]).not.toBe() } else { expect(res[bluetoothError] undefined).toBe(true) } if (res[wifiEnabled] undefined) { expect(res[wifiError]).not.toBe() } else { expect(res[wifiError] undefined).toBe(true) } if (key deviceOrientation) { expect([portrait, landscape]).toContain(value); } } }); });测试要点归纳Web 与 App 内嵌 WebView 环境跳过真实断言因为该 API 不支持 Web通过program.reLaunch跳转到示例页并等待渲染后再调用uni.getSystemSetting()校验「开关关闭/缺失 → 对应 Error 非空」的联动关系校验deviceOrientation的取值只能落在[portrait, landscape]集合内。九、小结uni-getSystemSetting是理解「UTS 插件如何封装原生系统能力」的极佳范本一份 interface.uts 定义跨端统一类型三份平台实现Android / iOS / HarmonyOS各自调用系统级 API辅以 package.json 的扩展 API 注册与仓库中的示例页、自动化测试构成了一个完整可复用的 uni-app x 扩展 API 闭环。使用上只需记住三点同步调用直接取返回值、可选字段用??兜底、bluetoothError/wifiError非空即表示缺少对应权限。进一步了解 uts 语言与插件开发可参考仓库内文档如 uts 语言介绍、uts 插件开发想查看该 API 的完整官方规范说明可阅读仓库中的 get-system-setting API 文档。赞分享示例工程前端移动开发跨平台【免费下载链接】uni-appA cross-platform framework using Vue.js项目地址https://gitcode.com/gh_mirrors/un/uni-app点击查看免费下载相关推荐uni-app最佳实践跨端开发的完整指南uni app最佳实践跨端开发的完整指南 前言为什么选择uni app 还在为多端开发而头疼吗每次新项目都要为不同平台重复编写相似代码uni app作示例工程uni-app x 事件总线完全指南uni.$on / uni.$off / uni.$once / uni.$emit 的跨端实践与源码解析uni app x 事件总线完全指南uni.$on / uni.$off / uni.$once / uni.$emit 的跨端实践与源码解析 本文档对应仓库示例工程前端移动开发跨平台uni-app x Worker 多线程开发指南uni.createWorker 完整 API 解析与跨端实践uni app x Worker 多线程开发指南uni.createWorker 完整 API 解析与跨端实践 现代 CPU 都是多核的而 uni app示例工程前端移动开发跨平台上一篇AudioSR音频超分辨率技术基于扩散模型的通用音频质量增强方案下一篇A2UI数据绑定实战教程构建动态响应的智能界面创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
