HarmonyOS APP联动授权、批量申请与权限组管理策略

📌 核心要点：鸿蒙权限组将相关权限打包管理，同组权限联动授权——用户授权组内任一权限时，同组其他权限自动获得授权。理解权限组的联动机制、掌握批量申请策略、区分权限组与单权限的差异，是高效管理多权限场景的关键。

一、背景与动机

你有没有遇到过这种情况：一个 App 既要用相机拍照，又要录音录像，还要访问相册保存。如果每个权限都单独弹窗问用户，那用户体验简直灾难——弹窗一个接一个，像查户口一样。

鸿蒙的权限组机制就是为了解决这个问题。它把"逻辑上相关"的权限归到同一个组里，用户只需要授权一次，同组的其他权限就自动生效了。就像你去银行办业务，不需要一个窗口办存款、另一个窗口办转账、再来一个窗口办理财——一个综合窗口全搞定。

但权限组也有它的"坑"。最典型的就是联动授权——你以为只申请了相机权限，结果麦克风权限也一起被授权了，因为它们属于同一个"音视频"权限组。如果你不了解这个机制，可能会在不知情的情况下获取了超出预期的权限，这在隐私合规审查中是大忌。

所以，理解权限组的工作机制，不是可选项，而是必修课。

二、核心原理

2.1 权限组的联动授权流程

2.2 鸿蒙系统权限组一览

鸿蒙系统定义了以下主要权限组：

关键理解：权限组是系统预定义的，开发者不能自定义权限组。你只能选择使用或不使用某个权限组中的权限。

2.3 联动授权的"已声明"前提

这是权限组最容易误解的地方：联动授权只对你在 module.json5 中声明过的权限生效。

举个例子：

• 你在 module.json5 中声明了 CAMERA 和 MICROPHONE（虽然它们不在同一组，这里只是举例概念）
• 如果你只声明了 CAMERA，即使它所在的权限组里有其他权限，那些没声明的权限也不会被联动授权

再以位置权限组为例：

• 你声明了 APPROXIMATELY_LOCATION 和 LOCATION
• 用户授权了其中一个，另一个自动获得授权
• 但如果你只声明了 LOCATION 而没声明 APPROXIMATELY_LOCATION，那授权 LOCATION 时不会联动授权 APPROXIMATELY_LOCATION

2.4 权限组 vs 单权限的区别

三、代码实战

示例1：权限组信息查询工具

开发一个工具类，可以查询任意权限所属的权限组信息，帮助开发者在声明权限时做出正确决策：

// utils/PermissionGroupHelper.ets - 权限组查询工具
import { bundleManager } from '@kit.AbilityKit';

// 权限组定义接口
interface PermissionGroupDef {
  groupName: string;           // 权限组名称
  groupLabel: string;          // 权限组中文名
  permissions: string[];       // 组内权限列表
  grantMode: string;           // 授权方式
  aplLevel: string;            // APL级别
  description: string;         // 用途描述
}

// 权限到权限组的映射结果
interface PermissionGroupMapping {
  permission: string;          // 权限名称
  groupName: string;           // 所属权限组
  groupLabel: string;          // 权限组中文名
  siblingPermissions: string[];// 同组其他权限
  isDeclared: boolean;         // 是否已在module.json5中声明
}

export class PermissionGroupHelper {
  // 鸿蒙系统权限组定义表
  private static readonly GROUP_DEFINITIONS: PermissionGroupDef[] = [
    {
      groupName: 'ohos.permission-group.LOCATION',
      groupLabel: '位置',
      permissions: [
        'ohos.permission.APPROXIMATELY_LOCATION',
        'ohos.permission.LOCATION',
        'ohos.permission.LOCATION_IN_BACKGROUND'
      ],
      grantMode: 'user_grant',
      aplLevel: 'system_basic',
      description: '用于获取设备位置信息'
    },
    {
      groupName: 'ohos.permission-group.CAMERA',
      groupLabel: '相机',
      permissions: [
        'ohos.permission.CAMERA'
      ],
      grantMode: 'user_grant',
      aplLevel: 'normal',
      description: '用于访问设备相机'
    },
    {
      groupName: 'ohos.permission-group.MICROPHONE',
      groupLabel: '麦克风',
      permissions: [
        'ohos.permission.MICROPHONE'
      ],
      grantMode: 'user_grant',
      aplLevel: 'normal',
      description: '用于访问设备麦克风'
    },
    {
      groupName: 'ohos.permission-group.CALENDAR',
      groupLabel: '日历',
      permissions: [
        'ohos.permission.READ_CALENDAR',
        'ohos.permission.WRITE_CALENDAR'
      ],
      grantMode: 'user_grant',
      aplLevel: 'system_basic',
      description: '用于读写日历信息'
    },
    {
      groupName: 'ohos.permission-group.CONTACTS',
      groupLabel: '通讯录',
      permissions: [
        'ohos.permission.READ_CONTACTS',
        'ohos.permission.WRITE_CONTACTS'
      ],
      grantMode: 'user_grant',
      aplLevel: 'system_basic',
      description: '用于读写联系人信息'
    },
    {
      groupName: 'ohos.permission-group.MEDIA',
      groupLabel: '媒体',
      permissions: [
        'ohos.permission.READ_MEDIA',
        'ohos.permission.WRITE_MEDIA'
      ],
      grantMode: 'user_grant',
      aplLevel: 'system_basic',
      description: '用于读写媒体文件'
    }
  ];

  /**
   * 查询指定权限所属的权限组信息
   * @param permission 权限名称
   * @returns 权限组映射信息，未找到返回null
   */
  static getPermissionGroup(permission: string): PermissionGroupMapping | null {
    for (const group of PermissionGroupHelper.GROUP_DEFINITIONS) {
      const index = group.permissions.indexOf(permission);
      if (index !== -1) {
        // 获取同组其他权限（排除自身）
        const siblings = group.permissions.filter(p => p !== permission);
        return {
          permission: permission,
          groupName: group.groupName,
          groupLabel: group.groupLabel,
          siblingPermissions: siblings,
          isDeclared: false // 需要运行时检查
        };
      }
    }
    return null;
  }

  /**
   * 获取所有权限组定义
   * @returns 权限组定义列表
   */
  static getAllGroups(): PermissionGroupDef[] {
    return [...PermissionGroupHelper.GROUP_DEFINITIONS];
  }

  /**
   * 检查一组权限是否属于同一权限组
   * @param permissions 权限名称数组
   * @returns 是否属于同一权限组
   */
  static areInSameGroup(permissions: string[]): boolean {
    if (permissions.length <= 1) return true;

    const groups = new Set<string>();
    for (const perm of permissions) {
      const mapping = PermissionGroupHelper.getPermissionGroup(perm);
      if (mapping) {
        groups.add(mapping.groupName);
      } else {
        // 不属于任何权限组的权限，视为独立组
        groups.add(`_independent_${perm}`);
      }
    }

    return groups.size === 1;
  }

  /**
   * 获取指定权限组的完整权限列表
   * @param groupName 权限组名称
   * @returns 组内权限列表
   */
  static getGroupPermissions(groupName: string): string[] {
    const group = PermissionGroupHelper.GROUP_DEFINITIONS.find(
      g => g.groupName === groupName
    );
    return group ? [...group.permissions] : [];
  }

  /**
   * 分析权限声明中的联动授权风险
   * @param declaredPermissions 已声明的权限列表
   * @returns 风险分析结果
   */
  static analyzeLinkageRisk(declaredPermissions: string[]): Array<{
    group: string;
    groupLabel: string;
    declaredInGroup: string[];
    notDeclaredInGroup: string[];
    riskLevel: 'none' | 'low' | 'medium' | 'high';
  }> {
    const results: Array<{
      group: string;
      groupLabel: string;
      declaredInGroup: string[];
      notDeclaredInGroup: string[];
      riskLevel: 'none' | 'low' | 'medium' | 'high';
    }> = [];

    for (const groupDef of PermissionGroupHelper.GROUP_DEFINITIONS) {
      const declaredInGroup = groupDef.permissions.filter(
        p => declaredPermissions.includes(p)
      );
      const notDeclaredInGroup = groupDef.permissions.filter(
        p => !declaredPermissions.includes(p)
      );

      // 只有声明了组内部分权限时才有风险
      if (declaredInGroup.length > 0) {
        let riskLevel: 'none' | 'low' | 'medium' | 'high' = 'none';
        if (notDeclaredInGroup.length > 0) {
          riskLevel = declaredInGroup.length >= notDeclaredInGroup.length ? 'low' : 'medium';
        }
        // 如果声明了后台位置但没声明前台位置，风险高
        if (groupDef.groupName === 'ohos.permission-group.LOCATION') {
          if (declaredInGroup.includes('ohos.permission.LOCATION_IN_BACKGROUND') &&
            !declaredInGroup.includes('ohos.permission.LOCATION')) {
            riskLevel = 'high';
          }
        }

        results.push({
          group: groupDef.groupName,
          groupLabel: groupDef.groupLabel,
          declaredInGroup,
          notDeclaredInGroup,
          riskLevel
        });
      }
    }

    return results;
  }
}

示例2：基于权限组的批量申请管理器

封装一个权限组感知的批量申请管理器，智能判断哪些权限可以合并请求，哪些需要单独处理：

// utils/GroupAwarePermissionManager.ets - 权限组感知的权限管理器
import { abilityAccessCtrl, common, Permissions } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { PermissionGroupHelper } from './PermissionGroupHelper';

// 批量申请结果
interface BatchRequestResult {
  totalRequested: number;       // 总共请求的权限数
  grantedCount: number;         // 已授权数量
  deniedCount: number;          // 被拒绝数量
  neverAskCount: number;        // 不再询问数量
  details: Array<{
    permission: string;
    isGranted: boolean;
    groupName: string;
    groupLabel: string;
  }>;
  linkedPermissions: string[];  // 因联动授权而额外获得的权限
}

export class GroupAwarePermissionManager {
  private atManager: abilityAccessCtrl.AtManager;

  constructor() {
    this.atManager = abilityAccessCtrl.createAtManager();
  }

  /**
   * 智能批量申请权限
   * 自动识别权限组，同组权限合并请求
   * @param context UIAbility上下文
   * @param permissions 需要申请的权限列表
   * @returns 批量申请结果
   */
  async requestPermissionsSmart(
    context: common.UIAbilityContext,
    permissions: Permissions[]
  ): Promise<BatchRequestResult> {
    // 第一步：按权限组分类
    const groupedPermissions = this.groupPermissionsByGroup(permissions);

    console.info('[GroupAwarePerm] 权限分组结果:');
    for (const [groupName, perms] of groupedPermissions) {
      console.info(`[GroupAwarePerm]   ${groupName}: [${perms.join(', ')}]`);
    }

    // 第二步：逐组请求权限
    const allDetails: BatchRequestResult['details'] = [];
    const linkedPermissions: string[] = [];

    for (const [groupName, perms] of groupedPermissions) {
      console.info(`[GroupAwarePerm] 正在请求权限组 ${groupName} 的权限...`);

      try {
        // 同组权限一起请求
        const result = await this.atManager.requestPermissionsFromUser(
          context,
          perms
        );

        // 处理每个权限的授权结果
        for (let i = 0; i < perms.length; i++) {
          const authResult = result.authResults[i];
          const isGranted = authResult === 0;
          const groupInfo = PermissionGroupHelper.getPermissionGroup(perms[i]);

          allDetails.push({
            permission: perms[i],
            isGranted: isGranted,
            groupName: groupInfo?.groupName || 'unknown',
            groupLabel: groupInfo?.groupLabel || '未知'
          });

          // 如果授权了，检查是否有联动权限
          if (isGranted && groupInfo) {
            const siblings = groupInfo.siblingPermissions;
            for (const sibling of siblings) {
              // 检查联动权限是否也在请求列表中但未被单独处理
              if (perms.includes(sibling) && !linkedPermissions.includes(sibling)) {
                linkedPermissions.push(sibling);
              }
            }
          }
        }
      } catch (error) {
        const err = error as BusinessError;
        console.error(`[GroupAwarePerm] 请求权限组 ${groupName} 失败: ${err.message}`);
        // 标记该组所有权限为失败
        for (const perm of perms) {
          const groupInfo = PermissionGroupHelper.getPermissionGroup(perm);
          allDetails.push({
            permission: perm,
            isGranted: false,
            groupName: groupInfo?.groupName || 'unknown',
            groupLabel: groupInfo?.groupLabel || '未知'
          });
        }
      }
    }

    // 第三步：汇总结果
    const grantedCount = allDetails.filter(d => d.isGranted).length;
    const deniedCount = allDetails.filter(d => !d.isGranted).length;

    return {
      totalRequested: permissions.length,
      grantedCount,
      deniedCount,
      neverAskCount: allDetails.filter(d => !d.isGranted).length, // 简化处理
      details: allDetails,
      linkedPermissions
    };
  }

  /**
   * 按权限组对权限进行分类
   * 同一权限组的权限归到一起
   * @param permissions 权限列表
   * @returns 权限组名 → 权限列表 的映射
   */
  private groupPermissionsByGroup(permissions: Permissions[]): Map<string, Permissions[]> {
    const groupMap = new Map<string, Permissions[]>();

    for (const perm of permissions) {
      const groupInfo = PermissionGroupHelper.getPermissionGroup(perm);
      const groupKey = groupInfo ? groupInfo.groupName : `_independent_${perm}`;

      if (!groupMap.has(groupKey)) {
        groupMap.set(groupKey, []);
      }
      groupMap.get(groupKey)!.push(perm);
    }

    return groupMap;
  }

  /**
   * 检查权限组的完整授权状态
   * @param context 上下文
   * @param groupName 权限组名称
   * @returns 组内所有权限的授权状态
   */
  async checkGroupStatus(
    context: common.UIAbilityContext,
    groupName: string
  ): Promise<Array<{ permission: string; isGranted: boolean }>> {
    const groupPermissions = PermissionGroupHelper.getGroupPermissions(groupName);
    const tokenId = context.applicationInfo.accessTokenId;
    const results: Array<{ permission: string; isGranted: boolean }> = [];

    for (const perm of groupPermissions) {
      try {
        const status = await this.atManager.checkAccessToken(
          tokenId,
          perm as Permissions
        );
        results.push({
          permission: perm,
          isGranted: status === abilityAccessCtrl.GrantStatus.PERMISSION_GRANTED
        });
      } catch (error) {
        results.push({
          permission: perm,
          isGranted: false
        });
      }
    }

    return results;
  }

  /**
   * 获取权限组的授权摘要
   * @param groupStatus 组内权限状态列表
   * @returns 摘要信息
   */
  getGroupSummary(
    groupStatus: Array<{ permission: string; isGranted: boolean }>
  ): { allGranted: boolean; grantedCount: number; totalCount: number } {
    const grantedCount = groupStatus.filter(s => s.isGranted).length;
    return {
      allGranted: grantedCount === groupStatus.length,
      grantedCount,
      totalCount: groupStatus.length
    };
  }
}

示例3：权限组可视化展示页面

创建一个完整的权限组管理页面，直观展示权限组关系、联动授权状态，并提供批量操作功能：

// pages/PermissionGroupPage.ets - 权限组管理展示页面
import { common, Permissions } from '@kit.AbilityKit';
import { PermissionGroupHelper } from '../utils/PermissionGroupHelper';
import { GroupAwarePermissionManager, BatchRequestResult } from '../utils/GroupAwarePermissionManager';

// 权限组UI数据模型
interface GroupUIData {
  groupName: string;
  groupLabel: string;
  permissions: Array<{
    name: string;
    shortName: string;
    isGranted: boolean;
  }>;
  allGranted: boolean;
  isExpanded: boolean;
}

@Entry
@Component
struct PermissionGroupPage {
  // 权限组数据列表
  @State groupDataList: GroupUIData[] = [];
  // 批量申请结果
  @State batchResult: string = '';
  // 加载状态
  @State isLoading: boolean = true;
  // 权限组管理器
  private groupManager: GroupAwarePermissionManager = new GroupAwarePermissionManager();

  private getContext(): common.UIAbilityContext {
    return this.getUIContext().getHostContext() as common.UIAbilityContext;
  }

  async aboutToAppear() {
    await this.loadGroupData();
  }

  /**
   * 加载权限组数据
   */
  private async loadGroupData(): Promise<void> {
    const allGroups = PermissionGroupHelper.getAllGroups();
    const context = this.getContext();
    const uiDataList: GroupUIData[] = [];

    for (const group of allGroups) {
      // 检查组内每个权限的授权状态
      const permStatuses = await this.groupManager.checkGroupStatus(
        context,
        group.groupName
      );

      const permissions = group.permissions.map((perm, index) => {
        // 提取权限短名称
        const shortName = perm.replace('ohos.permission.', '');
        return {
          name: perm,
          shortName: shortName,
          isGranted: permStatuses[index]?.isGranted ?? false
        };
      });

      const allGranted = permissions.every(p => p.isGranted);

      uiDataList.push({
        groupName: group.groupName,
        groupLabel: group.groupLabel,
        permissions: permissions,
        allGranted: allGranted,
        isExpanded: false
      });
    }

    this.groupDataList = uiDataList;
    this.isLoading = false;
  }

  build() {
    Column() {
      // 标题区域
      Row() {
        Text('权限组管理')
          .fontSize(24)
          .fontWeight(FontWeight.Bold)
          .layoutWeight(1)

        Text(`共 ${this.groupDataList.length} 个权限组`)
          .fontSize(14)
          .fontColor('#999999')
      }
      .width('100%')
      .padding({ left: 16, right: 16, top: 20, bottom: 12 })

      // 批量操作按钮
      Row({ space: 12 }) {
        Button('一键申请所有权限')
          .height(40)
          .fontSize(14)
          .backgroundColor('#4CAF50')
          .fontColor(Color.White)
          .borderRadius(20)
          .layoutWeight(1)
          .onClick(() => {
            this.requestAllPermissions();
          })

        Button('刷新状态')
          .height(40)
          .fontSize(14)
          .backgroundColor('#2196F3')
          .fontColor(Color.White)
          .borderRadius(20)
          .layoutWeight(1)
          .onClick(() => {
            this.isLoading = true;
            this.loadGroupData();
          })
      }
      .width('100%')
      .padding({ left: 16, right: 16, bottom: 12 })

      // 批量结果提示
      if (this.batchResult) {
        Text(this.batchResult)
          .fontSize(13)
          .fontColor('#666666')
          .padding({ left: 16, right: 16, bottom: 8 })
      }

      // 权限组列表
      if (this.isLoading) {
        Column() {
          LoadingProgress()
            .width(48)
            .height(48)
            .color('#4CAF50')
        }
        .width('100%')
        .layoutWeight(1)
        .justifyContent(FlexAlign.Center)
      } else {
        List({ space: 12 }) {
          ForEach(this.groupDataList, (groupData: GroupUIData, index: number) => {
            ListItem() {
              this.GroupCardBuilder(groupData, index)
            }
          }, (groupData: GroupUIData) => groupData.groupName)
        }
        .width('100%')
        .layoutWeight(1)
        .padding({ left: 16, right: 16 })
      }
    }
    .width('100%')
    .height('100%')
    .backgroundColor('#F5F5F5')
  }

  /**
   * 权限组卡片
   */
  @Builder
  GroupCardBuilder(groupData: GroupUIData, index: number) {
    Column() {
      // 权限组头部
      Row() {
        // 授权状态指示器
        Circle({ width: 10, height: 10 })
          .fill(groupData.allGranted ? '#4CAF50' : '#FF9800')
          .margin({ right: 8 })

        // 权限组名称
        Text(groupData.groupLabel)
          .fontSize(17)
          .fontWeight(FontWeight.Medium)
          .layoutWeight(1)

        // 授权进度
        Text(`${groupData.permissions.filter(p => p.isGranted).length}/${groupData.permissions.length}`)
          .fontSize(14)
          .fontColor('#999999')
          .margin({ right: 8 })

        // 展开/收起箭头
        Text(groupData.isExpanded ? '▲' : '▼')
          .fontSize(12)
          .fontColor('#999999')
      }
      .width('100%')
      .padding(16)
      .onClick(() => {
        // 切换展开状态
        this.groupDataList[index].isExpanded = !this.groupDataList[index].isExpanded;
        // 触发UI刷新
        this.groupDataList = [...this.groupDataList];
      })

      // 联动授权提示
      if (groupData.permissions.length > 1) {
        Row() {
          Text('🔗 联动授权：授权组内任一权限，同组其他权限自动授权')
            .fontSize(12)
            .fontColor('#FF9800')
            .padding({ left: 16, right: 16, bottom: 8 })
        }
      }

      // 展开的权限详情
      if (groupData.isExpanded) {
        Divider().color('#E0E0E0')
        ForEach(groupData.permissions, (perm: { name: string; shortName: string; isGranted: boolean }) => {
          Row() {
            Text(perm.isGranted ? '✅' : '❌')
              .fontSize(16)
              .margin({ right: 8 })

            Column() {
              Text(perm.shortName)
                .fontSize(14)
                .fontWeight(FontWeight.Medium)

              Text(perm.name)
                .fontSize(11)
                .fontColor('#BBBBBB')
                .margin({ top: 2 })
            }
            .alignItems(HorizontalAlign.Start)
            .layoutWeight(1)

            // 单独申请按钮
            Button('申请')
              .height(28)
              .fontSize(12)
              .backgroundColor(perm.isGranted ? '#E0E0E0' : '#4CAF50')
              .fontColor(perm.isGranted ? '#999999' : Color.White)
              .borderRadius(14)
              .padding({ left: 12, right: 12 })
              .enabled(!perm.isGranted)
              .onClick(() => {
                this.requestSinglePermission(perm.name as Permissions);
              })
          }
          .width('100%')
          .padding({ left: 16, right: 16, top: 10, bottom: 10 })
        }, (perm: { name: string }) => perm.name)
      }
    }
    .width('100%')
    .backgroundColor(Color.White)
    .borderRadius(12)
    .shadow({ radius: 2, color: '#1A000000', offsetY: 1 })
  }

  /**
   * 请求单个权限
   */
  private async requestSinglePermission(permission: Permissions): Promise<void> {
    const context = this.getContext();
    const result = await this.groupManager.requestPermissionsSmart(context, [permission]);

    // 更新UI状态
    this.updateGroupDataAfterRequest(result);
    this.batchResult = `申请完成：已授权 ${result.grantedCount} 个，被拒绝 ${result.deniedCount} 个`;
  }

  /**
   * 一键申请所有权限
   */
  private async requestAllPermissions(): Promise<void> {
    const context = this.getContext();

    // 收集所有未授权的权限
    const ungrantedPermissions: Permissions[] = [];
    for (const groupData of this.groupDataList) {
      for (const perm of groupData.permissions) {
        if (!perm.isGranted) {
          ungrantedPermissions.push(perm.name as Permissions);
        }
      }
    }

    if (ungrantedPermissions.length === 0) {
      this.batchResult = '所有权限均已授权 ✅';
      return;
    }

    // 智能批量申请
    const result = await this.groupManager.requestPermissionsSmart(context, ungrantedPermissions);

    // 更新UI状态
    this.updateGroupDataAfterRequest(result);
    this.batchResult = `批量申请完成：已授权 ${result.grantedCount}/${result.totalRequested} 个权限`;

    // 如果有联动授权的权限，提示用户
    if (result.linkedPermissions.length > 0) {
      this.batchResult += `\n联动授权：${result.linkedPermissions.join(', ')}`;
    }
  }

  /**
   * 根据申请结果更新UI数据
   */
  private updateGroupDataAfterRequest(result: BatchRequestResult): void {
    // 根据申请结果更新每个权限的授权状态
    for (const detail of result.details) {
      for (const groupData of this.groupDataList) {
        for (const perm of groupData.permissions) {
          if (perm.name === detail.permission) {
            perm.isGranted = detail.isGranted;
          }
        }
        // 更新组级别的授权状态
        groupData.allGranted = groupData.permissions.every(p => p.isGranted);
      }
    }

    // 触发UI刷新
    this.groupDataList = [...this.groupDataList];
  }
}

四、踩坑与注意事项

坑1：联动授权导致"过度授权"

现象：你只需要读取日历（READ_CALENDAR），但声明时也写了 WRITE_CALENDAR。用户授权时，两个权限一起被授权了，你的应用获得了超出实际需求的写入权限。

解决方案：遵循最小权限原则，只声明真正需要的权限。如果只需要读取，就不要声明写入。

// ❌ 错误：声明了不需要的写入权限
"requestPermissions": [
  { "name": "ohos.permission.READ_CALENDAR" },
  { "name": "ohos.permission.WRITE_CALENDAR" }  // 不需要就不声明
]

// ✅ 正确：只声明需要的读取权限
"requestPermissions": [
  { "name": "ohos.permission.READ_CALENDAR" }
]

坑2：位置权限组的特殊依赖关系

现象：你声明了 LOCATION_IN_BACKGROUND（后台位置），但没有声明 LOCATION（前台位置）。结果后台位置权限永远无法获得授权。

原因：位置权限组有特殊的依赖链：APPROXIMATELY_LOCATION → LOCATION → LOCATION_IN_BACKGROUND。必须先获得前置权限，才能申请后续权限。

授权依赖链：
APPROXIMATELY_LOCATION（大概位置）
    ↓ 前置
LOCATION（精确位置）
    ↓ 前置
LOCATION_IN_BACKGROUND（后台位置）

坑3：批量申请时权限组的弹窗合并

现象：你同时请求了 READ_CONTACTS 和 WRITE_CONTACTS，以为会弹两次窗，结果只弹了一次。

原因：同组权限在批量请求时，系统会合并为一个弹窗。用户授权一次，组内所有请求的权限同时获得。

注意：这是正常行为，不是 bug。但你需要意识到，用户可能以为只授权了"读取"，实际上"写入"也被授权了。

坑4：权限组内部分权限被用户单独关闭

现象：用户在系统设置中单独关闭了 WRITE_CALENDAR，但 READ_CALENDAR 仍然授权。你的应用在写入日历时崩溃。

原因：权限组的联动授权只在"授权"时生效，"取消授权"时不会联动。用户可以单独关闭组内的某个权限。

解决方案：每次使用权限前都要检查授权状态，不能因为之前授权过就假设现在还有权限。

// ✅ 正确：每次使用前检查
const isGranted = await this.permManager.checkPermission(context, 'ohos.permission.WRITE_CALENDAR');
if (isGranted) {
  // 写入日历
} else {
  // 重新请求或降级处理
}

坑5：跨权限组的权限误判为联动

现象：开发者以为相机和麦克风属于同一权限组，授权相机后麦克风也会自动授权。实际上它们属于不同的权限组。

澄清：相机和麦克风虽然在功能上经常一起使用（如视频通话），但它们属于不同的权限组。授权相机不会联动授权麦克风，需要分别申请。

五、HarmonyOS 6 适配

5.1 权限组的变化

5.2 新增权限组

HarmonyOS 6 新增了以下权限组：

• AI 权限组：包含 ohos.permission.AI_VOICE、ohos.permission.AI_VISION 等
• 健康权限组：包含 ohos.permission.READ_HEALTH_DATA、ohos.permission.WRITE_HEALTH_DATA 等
• 车机权限组：包含 ohos.permission.CONTROL_VEHICLE_DOOR 等车载相关权限

5.3 迁移建议

1. 使用新增的 bundleManager.getPermissionGroup() API 动态查询权限组信息，替代硬编码的权限组映射表
2. 检查应用是否声明了同一权限组中不需要的权限，移除冗余声明
3. 为新增的 AI 权限组添加对应的授权流程和说明文案

六、总结

权限组知识图谱
├── 基本概念
│   ├── 系统预定义权限组（不可自定义）
│   ├── 同组权限联动授权
│   └── 仅已声明的权限参与联动
├── 主要权限组
│   ├── 位置组 → APPROXIMATELY_LOCATION + LOCATION + LOCATION_IN_BACKGROUND
│   ├── 相机组 → CAMERA
│   ├── 麦克风组 → MICROPHONE
│   ├── 日历组 → READ_CALENDAR + WRITE_CALENDAR
│   ├── 通讯录组 → READ_CONTACTS + WRITE_CONTACTS
│   └── 媒体组 → READ_MEDIA + WRITE_MEDIA
├── 联动授权规则
│   ├── 授权时联动 → 组内已声明权限同时授权
│   ├── 取消时不联动 → 用户可单独关闭组内权限
│   └── 位置权限依赖链 → 大概→精确→后台
├── 批量申请策略
│   ├── 按组分批 → 同组权限合并请求
│   ├── 智能排序 → 先申请核心权限
│   └── 结果聚合 → 统一处理授权结果
└── 注意事项
    ├── 最小权限原则 → 不需要的权限不声明
    ├── 使用前检查 → 权限可能被用户单独关闭
    ├── 相机≠麦克风 → 不同权限组需分别申请
    └── 位置依赖链 → 必须按顺序声明和申请

核心记忆口诀：

1. 同组联动，只限已声明——联动授权只对 module.json5 中声明的权限生效
2. 授权联动，取消不联动——授权时一起生效，但用户可以单独关闭
3. 位置有链，从粗到细——大概位置→精确位置→后台位置，必须按序
4. 不同组别，分别申请——相机和麦克风是不同权限组
5. 用前必查，不要假设——每次使用权限前都要检查当前状态
6. 最小声明，避免过度——只声明真正需要的权限

权限组是鸿蒙权限体系中"简化用户体验"的核心设计。理解它的联动机制，既能减少不必要的弹窗打扰用户，又能避免在不知情中获取了超出需求的权限。用好权限组，让你的应用既方便又安全。