鸿蒙应用开发实战【96】— HarmonyOS权限申请实战
鸿蒙应用开发实战【96】— HarmonyOS权限申请实战
本文是「号码助手全栈开发系列」第 96 篇，持续更新中…
开源社区：https://openharmonycrossplatform.csdn.net
前言
HarmonyOS 的权限系统分为 normal（正常）和 user_grant（用户授权）两级。号码助手需申请网络权限和数据同步相关权限。本篇基于项目实际配置详解权限声明、敏感权限动态申请和最佳实践。
本篇涵盖：module.json5 权限配置、normal 与 user_grant 权限区别、INTERNET / GET_NETWORK_INFO 声明、敏感权限动态弹窗、
@ohos.abilityAccessCtrl权限校验、权限最佳实践清单。
一、权限分类
HarmonyOS 权限分为两个等级：
| 等级 | 特点 | 典型权限 | 申请方式 | 用户可见 |
|---|---|---|---|---|
| normal | 安装时自动授予 | INTERNET、GET_NETWORK_INFO | module.json5声明即可 | ❌ 无感知 |
| user_grant | 运行时弹窗用户确认 | READ_CONTACTS、LOCATION、CAMERA、MICROPHONE | 声明 + 动态调用requestPermissionsFromUser | ✅ 弹窗提示 |
二、号码助手权限配置
文件：entry/src/main/module.json5
{ "module": { "name": "entry", "type": "entry", "requestPermissions": [ { "name": "ohos.permission.INTERNET", "reason": "$string:internet_permission_reason", "usedScene": { "abilities": ["EntryAbility"], "when": "always" } }, { "name": "ohos.permission.GET_NETWORK_INFO", "reason": "$string:network_info_permission_reason", "usedScene": { "abilities": ["EntryAbility"], "when": "always" } } ] } }字段说明
| 字段 | 值 | 含义 |
|---|---|---|
name | ohos.permission.XXX | 权限名称，系统定义 |
reason | $string:xxx | 申请原因，显示在系统设置中 |
usedScene.abilities | ["EntryAbility"] | 在哪个 Ability 使用该权限 |
usedScene.when | "always"/"inuse" | always=后台可用, inuse=仅前台 |
三、敏感权限动态申请
3.1 导入模块
import{abilityAccessCtrl,common}from'@kit.AbilityKit'import{hilog}from'@kit.PerformanceAnalysisKit'3.2 请求权限
asyncfunctionrequestPermission(context:common.UIAbilityContext):Promise<void>{constpermissions:string[]=['ohos.permission.READ_CONTACTS','ohos.permission.LOCATION']try{constatManager=abilityAccessCtrl.createAtManager()constgrantResults=awaitatManager.requestPermissionsFromUser(context,permissions)for(leti=0;i<grantResults.length;i++){if(grantResults[i]===0){hilog.info(0x0000,'Permission','%{public}s 已授权',permissions[i])}else{hilog.warn(0x0000,'Permission','%{public}s 被拒绝',permissions[i])}}}catch(e){hilog.error(0x0000,'Permission','请求权限失败: %{public}s',JSON.stringify(e))}}3.3 校验权限是否已授予
import{abilityAccessCtrl,Permissions}from'@kit.AbilityKit'functioncheckPermission(permission:Permissions):boolean{constatManager=abilityAccessCtrl.createAtManager()consttokenId=atManager.getCallingTokenId()constresult=atManager.verifyAccessTokenSync(tokenId,permission)returnresult===abilityAccessCtrl.GrantStatus.PERMISSION_GRANTED}// 使用if(checkPermission('ohos.permission.READ_CONTACTS')){// 已有权限，直接操作}else{// 去申请权限}四、usedScene 配置说明
| when 值 | 含义 | 适用场景 |
|---|---|---|
"always" | 前后台均可使用 | 网络请求、数据同步 |
"inuse" | 仅前台使用 | 相机、定位、麦克风 |
abilities数组指定在哪个 Ability 中使用：
"usedScene": { "abilities": ["EntryAbility"], "when": "always" }五、权限声明流程总结
1. 确定需要的权限 ├── 查阅 HarmonyOS 权限列表文档 ├── 区分 normal 还是 user_grant └── 确认是否必须（能不申请就不申请） 2. 配置 module.json5 ├── requestPermissions 数组中声明 ├── 填写 reason（用户可见的原因） └── 配置 usedScene（abilities + when） 3. 动态请求（仅 user_grant） ├── 调用 abilityAccessCtrl.requestPermissionsFromUser ├── 处理 grantResults 数组 └── 在设置中或首次启动时请求 4. 使用权限前校验 ├── verifyAccessTokenSync 检查状态 └── 被拒绝时友好提示（非直接 crash）六、常见权限问题排查
| 问题 | 原因 | 解决 |
|---|---|---|
| 网络请求失败 | 未声明INTERNET权限 | 检查 module.json5 requestPermissions |
| 定位失败 | 未申请或用户拒绝 | 动态弹窗 + 状态校验 |
| 回调无反应 | 调用了敏感权限 API 但未申请 | 在真机上测试，模拟器可能默认拒绝 |
| 审核被拒 | reason 不清晰 | 使用$string引用多语言描述 |
小结
| 内容 | 要点 |
|---|---|
| normal 权限 | module.json5 声明即可（INSTALL 时自动授予） |
| user_grant 权限 | 声明 + 运行时requestPermissionsFromUser() |
| 权限校验 | abilityAccessCtrl.verifyAccessTokenSync() |
| 最佳实践 | 最小权限原则、reason 清晰、拒绝后友好提示 |
| 号码助手 | 使用 INTERNET + GET_NETWORK_INFO（均为 normal） |
如果这篇文章对你有帮助，欢迎点赞👍、收藏⭐、关注🔔，你的支持是我持续创作的动力！
相关资源：
- 开源鸿蒙跨平台社区：https://openharmonycrossplatform.csdn.net
- HarmonyOS 权限开发指南：https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/permissions-overview
- HarmonyOS 官方文档：https://developer.huawei.com/consumer/cn/doc/
- HarmonyOS hilog文档：https://developer.huawei.com/consumer/cn/doc/harmonyos-references/hilog
- HarmonyOS testing：https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/unit-test
- HarmonyOS 安全与权限：https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/permissions-overview