更新记录

1.2.3（2026-03-01）

• 优化文档

1.2.2（2026-01-09）

• 优化鸿蒙权限

1.2.1（2026-01-09）

• 优化鸿蒙权限

平台兼容性

uni-app(4.01)

uni-app x(4.01)

hmn-permission

一套跨端权限工具，统一封装 Android / iOS / 鸿蒙 的权限检查、申请与跳转设置页，适用于 uni-app 及 uni-app x。

功能特点

• 同一份 API 覆盖 Android、iOS、鸿蒙（OpenHarmony/HarmonyOS）
• checkPermissions / requestPermissions / openSystemPermissionPage 三个核心方法，返回统一的 PermissionResult
• iOS 内置 photo/camera/microphone/location/notification 的别名归一；鸿蒙内置应用详情页多候选兜底
• 鸿蒙支持通过伪权限 __NOTIFICATION__ 统一检测/申请通知开关
• 支持在用户勾选“不再询问”时，通过结果中的 doNotAskAgain 与 deniedDontAskAgainList 引导到系统设置

安装与引入

• 插件市场直接安装或将代码放入 uni_modules/hmn-permission
• 页面中引入：import { checkPermissions, requestPermissions, openSystemPermissionPage } from '@/uni_modules/hmn-permission'
• 调用时需保证页面已启动（如 onLoad / onShow 后），以便 Android/Harmony 拿到有效 Activity/UIAbilityContext

支持的权限名约定

• Android：可传任意系统权限常量（不限于示例常量），如 android.permission.CAMERA、android.permission.RECORD_AUDIO、android.permission.ACCESS_FINE_LOCATION 等
  • 相册/媒体在不同版本差异：Android 13+ 建议使用 android.permission.READ_MEDIA_IMAGES / READ_MEDIA_VIDEO / READ_MEDIA_AUDIO，旧版本可用 android.permission.READ_EXTERNAL_STORAGE
  • openSystemPermissionPage 可传需要引导的权限列表
• iOS：仅支持内置映射到系统 API 的字符串，其他会直接视为拒绝
  • 相册：photo / photos / photoLibrary
  • 相机：camera
  • 麦克风：microphone / mic
  • 定位（前台）：location / locationWhenInUse / location_when_in_use
  • 通知：notification / notifications / push
• 鸿蒙：传 @ohos.abilityAccessCtrl 的权限名（不局限于示例常量），如 ohos.permission.CAMERA、ohos.permission.MICROPHONE、ohos.permission.LOCATION等
  • 通知开关：使用常量 __NOTIFICATION__（可与其它权限并列传入）
  • 位置权限：推荐先模糊定位检测，再精确检测，示例：await checkPermissions(['ohos.permission.APPROXIMATELY_LOCATION', 'ohos.permission.LOCATION'])
  • openSystemPermissionPage 会兜底多种 Settings Ability，引导用户去开启权限

API 说明

checkPermissions(permissions)

• Android/iOS 同步返回，鸿蒙为 Promise，推荐统一使用 await checkPermissions(...)

import { checkPermissions } from '@/uni_modules/hmn-permission'

const res = await checkPermissions(['android.permission.CAMERA'])
if (!res.allGranted) {
  // TODO: 给出引导
}

通知权限示例：

import { checkPermissions } from '@/uni_modules/hmn-permission'

// Android 13+ 用 android.permission.POST_NOTIFICATIONS
// iOS 用 notification / notifications / push
// 鸿蒙用 __NOTIFICATION__
const res = await checkPermissions(['__NOTIFICATION__'])

requestPermissions(permissions)

• 申请权限并返回 Promise<PermissionResult>

import { requestPermissions, openSystemPermissionPage } from '@/uni_modules/hmn-permission'

const res = await requestPermissions(['android.permission.CAMERA'])
if (!res.allGranted && res.doNotAskAgain) {
  // 用户勾选“不再询问”，引导去系统设置
  openSystemPermissionPage(['android.permission.CAMERA'])
}

openSystemPermissionPage(permissions?)

• 打开系统权限设置页；Android 支持传入需要高亮/引导的权限列表，iOS 无视参数直接跳转 App 设置，鸿蒙返回 Promise 可 await
  • iOS 的通知检查为了保持同步，在 native 侧做了短暂等待；

PermissionResult 结构

• allGranted：是否全部授权
• grantedList / deniedList / deniedDontAskAgainList：按状态分组的权限列表
• doNotAskAgain：是否存在“不再询问”
• states：Map<string, PermissionState> / Record<string, PermissionState>，可按传入的原始权限名取状态

注意事项

• 请在 manifest.json（Android uses-permission、iOS InfoPlist usage description、鸿蒙 module.json5 权限声明）中提前声明需要的权限
• 避免一次申请过多与业务无关的权限，遵循最小授权原则
• 如需展示自定义提示，可先 checkPermissions 再决定是否触发 requestPermissions

鸿蒙开发配置

如果使用鸿蒙开发请确保你配置了 harmony-configs/entry/src/main/resources/base/element/string.json5以及harmony-configs/entry/src/main/module.json5（详细请参考uniapp鸿蒙开发文档）

示例代码：

// harmony-configs/entry/src/main/module.json5
{
  "module": {
    "name": "entry",
    "type": "entry",
    "description": "$string:module_desc",
    "mainElement": "EntryAbility",
    "deviceTypes": [
      "phone",
      "tablet",
      "2in1"
    ],
    "deliveryWithInstall": true,
    "installationFree": false,
    "pages": "$profile:main_pages",
    "abilities": [
      {
        "name": "EntryAbility",
        "srcEntry": "./ets/entryability/EntryAbility.ets",
        "description": "$string:EntryAbility_desc",
        "icon": "$media:layered_image",
        "label": "$string:EntryAbility_label",
        "startWindowIcon": "$media:startIcon",
        "startWindowBackground": "$color:start_window_background",
        "exported": true,
        "skills": [
          {
            "entities": ["entity.system.home"],
            "actions": ["action.system.home"]
          }
        ]
      }
    ],
    "requestPermissions": [
      {
        "name": "ohos.permission.APP_TRACKING_CONSENT",
        "reason": "$string:Reason_TRACKING",
        "usedScene": { "when": "inuse" }
      },
      {
        "name": "ohos.permission.INTERNET"
      },
      {
        "name": "ohos.permission.GET_NETWORK_INFO",
        "usedScene": { "when": "inuse" }
      },
      {
        "name": "ohos.permission.CAMERA",
        "reason": "$string:camera_reason",
        "usedScene": { "when": "inuse" }
      },
      {
        "name": "ohos.permission.MICROPHONE",
        "reason": "$string:mic_reason",
        "usedScene": { "when": "inuse" }
      },
      {
        "name": "ohos.permission.APPROXIMATELY_LOCATION",
        "reason": "$string:location_reason",
        "usedScene": {
          "when": "inuse"
        }
      },
      {
        "name": "ohos.permission.LOCATION",
        "reason": "$string:location_reason",
        "usedScene": {
          "when": "inuse"
        }
      }
    ],
    "metadata": [
      {
        "name": "GETUI_APPID",
        "value": "xxxxx"
      },
      {
        "name": "client_id",
        "value": "xxxxxx"
      }
    ]
  }
}

{
  "string": [
    {
      "name": "Reason_TRACKING",
      "value": "用于获取设备匿名标识"
    },
    {
      "name": "camera_reason",
      "value": "用于拍摄"
    },
    {
      "name": "mic_reason",
      "value": "用于从相册选择照片"
    },
    {
      "name": "location_reason",
      "value": "用于在您使用应用时获取位置信息"
    }
  ]
}