Android 14蓝牙权限新变化：XXPermissions使用教程
项目地址: https://gitcode.com/GitHub_Trending/xx/XXPermissions 你是否在Android 14设备上遇到蓝牙功能频繁崩溃？还在为权限适配焦头烂额？本文将详解Android 14蓝牙权限体系重构，教你用XXPermissions框架3行代码搞定权限请求，适配成功率提升90%。读完你将掌握：
- 蓝牙权限三分法的实战意义
- XXPermissions的零侵入集成方案
- 适配Android 14的完整代码模板
- 权限被拒时的用户引导策略
一、蓝牙权限体系重构：从"一刀切"到"精细化"
Android 12起引入的蓝牙权限三分法在Android 14中得到强化，彻底取代了旧版BLUETOOTH权限的"一刀切"模式。这种拆分使权限管理更符合最小权限原则，但也带来了适配复杂度。
| 权限类型 | 对应常量 | 适用场景 | 最低Android版本 |
|---|---|---|---|
| 蓝牙扫描 | BLUETOOTH_SCAN | 搜索附近蓝牙设备 | 12 (API 31) |
| 蓝牙连接 | BLUETOOTH_CONNECT | 建立GATT连接 | 12 (API 31) |
| 蓝牙广播 | BLUETOOTH_ADVERTISE | 广播蓝牙服务 | 12 (API 31) |
⚠️ 注意：Android 14要求必须显式申请这三个权限，旧版
BLUETOOTH权限已标记为maxSdkVersion=30查看清单
二、XXPermissions框架：3行代码搞定权限请求
XXPermissions作为专注Android权限处理的框架，已完成对Android 14的深度适配。其核心优势在于：
- 自动处理权限兼容性（无需版本判断）
- 内置权限说明对话框
- 支持链式调用的流畅API
- 完整的权限回调体系
2.1 集成框架（两种方式任选）
Gradle集成（推荐）：
dependencies {
implementation 'com.hjq:xxpermissions:17.3' // 请使用最新版本
}
源码集成：直接引入library模块到项目中，包含所有权限处理逻辑。
2.2 申请蓝牙权限的完整代码
在Activity中发起权限请求仅需3行核心代码，框架会自动处理版本差异：
XXPermissions.with(this)
.permission(PermissionLists.getBluetoothScanPermission()) // 蓝牙扫描权限
.permission(PermissionLists.getBluetoothConnectPermission()) // 蓝牙连接权限
.permission(PermissionLists.getBluetoothAdvertisePermission()) // 蓝牙广播权限
.request(new OnPermissionCallback() {
@Override
public void onResult(List<IPermission> grantedList, List<IPermission> deniedList) {
if (deniedList.isEmpty()) {
// 所有权限已授予，开始蓝牙操作
initBluetooth();
} else {
// 处理权限被拒情况
showPermissionDeniedTip(deniedList);
}
}
});
上述代码中用到的权限对象定义在PermissionLists.java，框架已内置所有系统权限的封装。
三、实战：从权限申请到蓝牙通信的完整流程
3.1 权限申请触发时机
建议在用户首次使用蓝牙功能时触发权限请求，而非应用启动时。例如在按钮点击事件中：
findViewById(R.id.btn_main_request_bluetooth_permission).setOnClickListener(v -> {
// 触发权限申请逻辑（见2.2节代码）
});
3.2 权限申请界面展示
XXPermissions会自动显示符合Material Design规范的权限说明对话框，用户可清晰了解权限用途：
对话框布局定义在permission_description_popup.xml，可通过重写样式自定义外观。
3.3 权限回调处理策略
权限申请结果通过OnPermissionCallback返回，建议采用以下处理策略：
@Override
public void onResult(List<IPermission> grantedList, List<IPermission> deniedList) {
if (deniedList.isEmpty()) {
toast("蓝牙权限已获取，正在初始化...");
initBluetoothAdapter();
} else {
// 检查是否有永久拒绝的权限
if (XXPermissions.isPermanentDenied(this, deniedList)) {
// 引导用户到设置页面
showSettingDialog(deniedList);
} else {
// 仅本次拒绝，可再次请求
toast("请授予蓝牙权限以使用该功能");
}
}
}
3.4 跳转到应用设置页面
当用户永久拒绝权限时，提供清晰的设置引导至关重要：
private void showSettingDialog(List<IPermission> permissions) {
new AlertDialog.Builder(this)
.setTitle("权限必要说明")
.setMessage("蓝牙功能需要以下权限：\n" + PermissionConverter.toString(permissions))
.setPositiveButton("去设置", (dialog, which) -> {
// 跳转到应用权限设置页
XXPermissions.startPermissionActivity(this, permissions);
})
.show();
}
四、常见问题与解决方案
Q1：Android 14以下设备如何兼容？
A1：框架会自动降级处理，旧设备将使用BLUETOOTH和BLUETOOTH_ADMIN权限。代码中无需额外判断，查看适配逻辑
Q2：申请BLUETOOTH_SCAN时需要定位权限吗？
A2：如果扫描蓝牙仅用于非定位目的，需在清单文件中添加android:usesPermissionFlags="neverForLocation"属性查看示例，否则仍需申请定位权限。
Q3：如何检测权限是否已授予？
A3：使用框架提供的检查方法：
boolean hasScanPermission = XXPermissions.isGranted(this, PermissionLists.getBluetoothScanPermission());
五、完整资源与学习路径
- 官方文档：HelpDoc-zh.md
- Demo应用：直接运行app模块查看所有权限申请示例
- 权限定义：所有权限常量
- 版本更新：CHANGELOG
掌握XXPermissions不仅能解决蓝牙权限问题，其统一的权限处理模式可应用于所有Android系统权限。建议收藏本文，转发给团队成员，一起告别权限适配烦恼！
下期预告：Android 14健康数据权限的申请策略，敬请关注。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
