手把手教你封装一个UniApp蓝牙权限工具函数（支持H5/App/小程序）

跨平台UniApp蓝牙权限工具封装实战一次编写多端运行在移动应用开发中蓝牙功能已经成为智能硬件连接、数据传输的重要桥梁。然而对于UniApp开发者而言每次启动蓝牙项目时都要面对繁琐的权限检查流程不同平台(H5、App、小程序)的差异处理更是让人头疼。本文将带你从零封装一个高度复用的蓝牙权限工具函数解决以下核心痛点多平台适配自动识别运行环境(H5/App/小程序)执行对应平台的权限逻辑优雅的错误处理采用Promise风格统一接口支持链式调用和async/await智能引导当用户拒绝权限时自动弹出友好提示并引导跳转系统设置页工程化封装提供Vue2/Vue3的适配方案可直接集成到现有项目架构中1. 环境准备与基础架构设计1.1 多平台权限机制差异分析在开始编码前我们需要明确各平台的权限特性平台类型蓝牙权限要求定位权限要求特殊说明H5需用户手动授权需要HTTPS环境依赖浏览器APIAndroid AppBLUETOOTH和BLUETOOTH_ADMINACCESS_FINE_LOCATION需要动态权限申请iOS AppNSBluetoothAlwaysUsageDescriptionNSLocationWhenInUseUsageDescription需在info.plist声明微信小程序scope.bluetoothscope.userLocation需在app.json声明关键发现Android 6.0和iOS 13都要求定位权限才能使用蓝牙扫描功能这是很多开发者容易忽略的点。1.2 项目初始化配置首先确保manifest.json包含必要的权限声明// manifest.json { permissions: { bluetooth: { description: 用于蓝牙设备连接 }, location: { description: 蓝牙扫描需要定位权限 } }, app-plus: { distribute: { android: { permissions: [ android.permission.BLUETOOTH, android.permission.BLUETOOTH_ADMIN, android.permission.ACCESS_FINE_LOCATION ] }, ios: { UIRequiredDeviceCapabilities: [bluetooth-le], NSBluetoothAlwaysUsageDescription: 需要蓝牙权限连接智能设备, NSLocationWhenInUseUsageDescription: 需要定位权限扫描周边设备 } } } }对于微信小程序还需在uniapp项目的src/manifest.json中添加mp-weixin: { appid: 你的小程序APPID, permission: { scope.userLocation: { desc: 你的位置信息将用于蓝牙设备扫描 } } }2. 核心工具类实现2.1 平台检测与适配层创建bluetooth-permission.js作为工具类入口// utils/bluetooth-permission.js const PLATFORM { H5: h5, APP: app, MP_WEIXIN: mp-weixin, // 其他小程序平台可扩展 } function getPlatform() { // 通过uni.getSystemInfoSync获取运行环境 const systemInfo uni.getSystemInfoSync() if (systemInfo.platform devtools) { return PLATFORM.MP_WEIXIN // 开发者工具视为小程序 } return systemInfo.platform.toLowerCase() }2.2 Promise风格权限检查器实现核心的权限检查逻辑export function checkBluetoothPermission() { return new Promise((resolve, reject) { const platform getPlatform() switch (platform) { case PLATFORM.H5: handleH5Permission(resolve, reject) break case PLATFORM.APP: handleAppPermission(resolve, reject) break case PLATFORM.MP_WEIXIN: handleMpPermission(resolve, reject) break default: reject(new Error(Unsupported platform: ${platform})) } }) } // 各平台具体实现 async function handleAppPermission(resolve, reject) { try { const isAndroid uni.getSystemInfoSync().platform android if (isAndroid) { // Android需要检查定位权限 const locationGranted await checkAndroidLocationPermission() if (!locationGranted) { return reject(new Error(LOCATION_PERMISSION_REQUIRED)) } } // 检查蓝牙状态 const bluetoothEnabled await checkBluetoothEnabled() if (!bluetoothEnabled) { return reject(new Error(BLUETOOTH_DISABLED)) } resolve(true) } catch (error) { reject(error) } }2.3 权限引导与错误处理当用户拒绝权限时提供友好的引导方案function showPermissionGuide(platform, permissionType) { const guides { [PLATFORM.APP]: { bluetooth: { title: 蓝牙权限未开启, content: 请到系统设置中开启蓝牙权限, openSetting: () uni.openAppAuthorizeSetting() }, location: { title: 定位权限未开启, content: 蓝牙扫描需要定位权限请开启定位服务, openSetting: () uni.openAppAuthorizeSetting() } }, [PLATFORM.MP_WEIXIN]: { bluetooth: { title: 蓝牙权限申请, content: 需要您授权蓝牙权限才能连接设备, openSetting: () uni.openSetting() } } } return new Promise((resolve) { uni.showModal({ title: guides[platform][permissionType].title, content: guides[platform][permissionType].content, success(res) { if (res.confirm) { guides[platform][permissionType].openSetting() } resolve(false) } }) }) }3. Vue项目集成方案3.1 Vue3组合式API用法创建可复用的Composable函数// composables/useBluetooth.js import { checkBluetoothPermission } from /utils/bluetooth-permission export function useBluetooth() { const isReady ref(false) const error ref(null) const init async () { try { await checkBluetoothPermission() isReady.value true } catch (err) { error.value err // 自动处理常见错误 handleCommonError(err) } } return { isReady, error, init } } // 组件中使用 import { useBluetooth } from /composables/useBluetooth export default { setup() { const { isReady, error, init } useBluetooth() onMounted(() { init() }) return { isReady, error } } }3.2 Vue2全局混入方案对于Vue2项目可以通过mixin提供统一接口// mixins/bluetooth.js import { checkBluetoothPermission } from ../utils/bluetooth-permission export default { data() { return { bluetoothReady: false, bluetoothError: null } }, methods: { async $checkBluetooth() { try { await checkBluetoothPermission() this.bluetoothReady true return true } catch (error) { this.bluetoothError error this.$handleBluetoothError(error) return false } }, $handleBluetoothError(error) { // 统一错误处理逻辑 } } } // main.js中全局注册 import BluetoothMixin from ./mixins/bluetooth Vue.mixin(BluetoothMixin)4. 高级功能扩展4.1 权限状态监听通过uni.onNeedPrivacyAuthorization实现实时监听let permissionListener null export function watchPermissionChange(callback) { if (permissionListener) { permissionListener.off() } permissionListener uni.onNeedPrivacyAuthorization((res) { if (res.type bluetooth) { callback(bluetooth, res.status) } }) return () { permissionListener?.off() permissionListener null } }4.2 性能优化策略针对频繁调用的场景添加缓存机制const PERMISSION_CACHE { lastCheck: 0, result: null, ttl: 5 * 60 * 1000 // 5分钟缓存 } export async function cachedCheckBluetooth() { const now Date.now() if (PERMISSION_CACHE.result now - PERMISSION_CACHE.lastCheck PERMISSION_CACHE.ttl) { return PERMISSION_CACHE.result } try { const result await checkBluetoothPermission() PERMISSION_CACHE.result result PERMISSION_CACHE.lastCheck now return result } catch (error) { PERMISSION_CACHE.result null throw error } }4.3 单元测试方案使用jest编写测试用例确保多平台兼容性describe(Bluetooth Permission Utility, () { beforeEach(() { jest.resetModules() }) it(should resolve on Android with granted permissions, async () { // Mock uni.getSystemInfoSync uni.getSystemInfoSync jest.fn().mockReturnValue({ platform: android }) // Mock permission APIs uni.getSetting jest.fn().mockResolvedValue({ authSetting: { scope.bluetooth: true } }) const { checkBluetoothPermission } require(./bluetooth-permission) await expect(checkBluetoothPermission()).resolves.toBe(true) }) it(should guide to settings when permission denied, async () { uni.getSystemInfoSync jest.fn().mockReturnValue({ platform: android }) uni.getSetting jest.fn().mockResolvedValue({ authSetting: { scope.bluetooth: false } }) uni.showModal jest.fn().mockResolvedValue({ confirm: true }) const { checkBluetoothPermission } require(./bluetooth-permission) await expect(checkBluetoothPermission()).rejects.toThrow() expect(uni.showModal).toHaveBeenCalled() }) })5. 实战应用技巧5.1 页面生命周期集成在页面中使用最佳实践export default { data() { return { bluetoothStatus: checking // checking, ready, denied } }, async onLoad() { this.bluetoothStatus checking try { await this.$checkBluetooth() this.bluetoothStatus ready this.startBluetoothProcess() } catch (error) { this.bluetoothStatus denied } }, methods: { startBluetoothProcess() { // 实际的蓝牙操作逻辑 } } }5.2 错误边界处理建议的错误处理流程分类处理错误类型蓝牙未开启定位权限缺失用户手动拒绝系统限制分级恢复策略function handleError(error) { switch (error.message) { case BLUETOOTH_DISABLED: return showEnableBluetoothGuide() case LOCATION_PERMISSION_REQUIRED: return showLocationPermissionGuide() case USER_DENIED: return showCustomDeniedModal() default: return showGenericError() } }重试机制async function withRetry(fn, maxRetries 2) { let attempts 0 while (attempts maxRetries) { try { return await fn() } catch (error) { attempts if (attempts maxRetries) throw error await new Promise(resolve setTimeout(resolve, 1000)) } } }5.3 多平台UI适配根据不同平台展示不同的UI引导template div v-ifbluetoothStatus denied template v-ifplatform app app-permission-guide / /template template v-else-ifplatform mp-weixin wechat-guide / /template template v-else h5-guide / /template button clickretry重新检查权限/button /div /template在真实项目中这个工具函数已经帮助我们将蓝牙权限相关的代码量减少了70%特别是处理多平台差异时不再需要每个页面重复编写兼容逻辑。一个典型的蓝牙扫描页面从原来的200行权限处理代码缩减到现在的30行核心业务逻辑。