更新记录

1.0.0（2026-09-04）

首次发布

平台兼容性

uni-app(5.23)

lucis-permission

检测、请求 App 运行时权限（录音、相机、存储/相册、定位、蓝牙）以及推送通知权限的 UTS 插件，兼容 iOS 和 Android 平台。

功能特性

• ✅ 检测权限状态（已授权 / 已拒绝 / 未决定 / 未知）
• ✅ 主动请求权限（弹出系统授权对话框）
• ✅ 跳转系统设置页面
• ✅ 支持权限：录音/麦克风、相机、存储/相册、定位、蓝牙
• ✅ 推送通知权限检测（checkPushPermission）与设置跳转（openPushSettings）
• ✅ 权限事件监听（requesting / granted / denied / checked，onPermissionEvent / offPermissionEvent）
• ✅ 兼容 iOS 12.0+
• ✅ 兼容 Android 6.0+ (API 23+)，适配 Android 13+ 媒体权限
• ✅ 支持 Vue 2 / Vue 3 + UTS

安装

将 lucis-permission 文件夹放入项目的 uni_modules 目录下即可。

使用方法

1. 引入插件

import {
  checkPermission,
  requestPermission,
  openPermissionSettings,
  checkPushPermission,
  openPushSettings,
  onPermissionEvent,
  offPermissionEvent
} from '@/uni_modules/lucis-permission'

2. 检测权限

// 检测录音权限状态（回调式 API，兼容 iOS 平台）
checkPermission({
  type: 'record',
  success: (result) => {
    console.log('权限类型:', result.type)     // 'record'
    console.log('权限状态:', result.status)   // 'granted' | 'denied' | 'not_determined' | 'unknown'
    console.log('是否已授权:', result.granted)
    console.log('描述信息:', result.message)
  },
  fail: (result) => {
    console.log('检测失败/未授权:', result.message, result.errCode)
  }
})

3. 请求权限

// 请求存储/相册权限（回调式 API，兼容 iOS 平台）
requestPermission({
  type: 'storage',
  complete: (result) => {
    if (result.granted) {
      console.log('权限已授予')
    } else {
      // 权限被拒绝，可引导用户打开设置
      uni.showModal({
        title: '需要权限',
        content: result.message,
        confirmText: '去设置',
        success: (res) => {
          if (res.confirm) {
            openPermissionSettings()
          }
        }
      })
    }
  }
})

4. 打开系统设置

openPermissionSettings((success) => {
  if (success) {
    console.log('已跳转到系统设置页面')
  }
})

5. 推送通知权限

推荐直接使用统一的 checkPermission 检测推送（type 为 'push'，与 checkPushPermission 等价，结果带 type: 'push'）：

import { checkPermission } from '@/uni_modules/lucis-permission'

// 统一入口：检测推送通知权限状态（等价于 checkPushPermission）
checkPermission({
  type: 'push',
  complete: (result) => {
    console.log('权限类型:', result.type)     // 'push'
    console.log('推送状态:', result.status)   // 'granted' | 'denied' | 'unknown' | 'not_determined'
    console.log('是否已授权:', result.granted)
    console.log('描述信息:', result.message)
  }
})

如需独立 API 或仅打开推送设置：

import { checkPushPermission, openPushSettings } from '@/uni_modules/lucis-permission'

// 独立检测推送权限（返回 PushPermissionResult，无 type 字段）
checkPushPermission({
  complete: (result) => {
    console.log('推送状态:', result.status, '是否授权:', result.granted)
  }
})

// 打开系统推送设置页面
openPushSettings((ok) => {
  console.log('跳转结果:', ok)
})

提示：requestPermission({ type: 'push' }) 不会弹出系统授权框（iOS/Android 推送授权均在系统设置中开启），会通过回调返回当前状态并提示"请在系统设置中开启"。

6. 权限事件监听

插件提供全局事件监听，覆盖 requesting / granted / denied / checked 四类事件，方便在页面统一处理授权结果（如弹窗引导用户去设置）：

// 注册监听，返回令牌 token
// 注意：uni-app（非 x）的 UTS 插件 JS 回调仅支持单参数，event 与 result 合并为 data 对象
const token = onPermissionEvent((data) => {
  // data.event: 'requesting' | 'granted' | 'denied' | 'checked'
  // data.result: PermissionResult
  const { event, result } = data
  console.log('权限事件:', event, '类型:', result.type, '状态:', result.status, result.message)

  if (event === 'denied' && !result.granted) {
    uni.showModal({
      title: '提示',
      content: '权限被拒绝',
      confirmText: '去设置',
      success: (e) => {
        if (e.confirm) openPermissionSettings()
      }
    })
  }
})

// 移除监听（传入注册时返回的 token）
offPermissionEvent(token)

事件说明：

• requesting：权限将要被请求（系统授权弹窗弹出前触发）
• granted：权限请求成功，已授权
• denied：权限请求被拒绝（含部分授权、拒绝且不再询问）
• checked：权限检测完成（checkPermission 返回结果后触发）

回调参数 data（PermissionEventData）：

• data.event：事件类型（requesting / granted / denied / checked）
• data.result：PermissionResult，关联的权限结果（字段见下方「checkPermission」回调结果说明）

API 说明

统一回调式 API：插件遵循 uni-app UTS 插件规范，使用 success / fail / complete 回调返回结果（不返回 Promise，因为 uni-app 的 iOS 端 UTS 插件不支持 Promise 返回值，前端 await 会拿到 undefined）。

• success：成功回调（errCode === 0 时触发）
• fail：失败回调（errCode !== 0，如被拒绝 / 未授权 / 异常）
• complete：完成回调（无论成功失败都会触发，参数与 success/fail 相同）

checkPermission(options)

检测指定权限的状态。

参数: options：

type 可选值：

回调结果 result（PermissionResult）：

注意：字段名为 granted（非 isGranted），Kotlin 对 is 前缀属性会生成特殊 getter/setter 导致跨桥字段丢失。

PermissionStatus 枚举值:

• granted - 已授权
• denied - 已拒绝
• not_determined - 用户尚未决定（可主动请求）
• unknown - 未知状态

requestPermission(options)

主动请求指定权限，弹出系统授权对话框。

参数: 同 checkPermission（{ type, success?, fail?, complete? }）

提示：请求前插件会自动检测，若权限已授予则直接回调成功，不会重复弹窗。请求过程会派发 requesting / granted / denied 事件。

openPermissionSettings(complete)

打开系统应用设置页面，引导用户手动开启权限。

参数: complete - 回调函数 (success: boolean) => void，是否成功跳转

checkPushPermission(options)

检测推送通知权限状态。

参数: options：

回调结果 result（PushPermissionResult）：

openPushSettings(complete)

打开系统推送通知设置页面。

参数: complete - 回调函数 (success: boolean) => void，是否成功跳转

onPermissionEvent(listener)

注册权限事件全局监听（requesting / granted / denied / checked）。

参数: listener - 回调函数 (data: PermissionEventData) => void

回调参数 data（PermissionEventData）：

注意：uni-app（非 x）的 UTS 插件 JS 回调仅支持单参数，故 event 与 result 合并为 data 对象。若按两参 (event, result) 书写，Android 端会抛 ClassCastException。

返回值: PermissionEventToken - 注册令牌，用于 offPermissionEvent 取消监听

注意：监听器为全局生效（模块级数组），页面退出时记得调用 offPermissionEvent 移除，避免重复注册导致事件日志成倍。建议在页面中使用模块级 token 管理（可参考 example 示例页）。

offPermissionEvent(token)

移除权限事件监听。

参数: token - onPermissionEvent 返回的注册令牌

平台兼容性

Android 版本适配

• Android 13+ (API 33+): 存储权限检测 READ_MEDIA_IMAGES、READ_MEDIA_VIDEO、READ_MEDIA_AUDIO
• Android 6.0-12 (API 23-32): 存储权限检测 READ_EXTERNAL_STORAGE、WRITE_EXTERNAL_STORAGE
• Android 6.0+: 运行时权限请求基于 UTSAndroid.requestSystemPermission

权限配置

插件的 app-android/AndroidManifest.xml 与 app-ios/Info.plist 已内置所需权限声明与使用说明，打包时自动合并。部分平台仍建议在 manifest.json 中补充声明：

Android

在 manifest.json 的 app-plus -> distribute -> android -> permissions 中添加需要的权限：

[
  "<uses-permission android:name=\"android.permission.RECORD_AUDIO\"/>",
  "<uses-permission android:name=\"android.permission.CAMERA\"/>",
  "<uses-permission android:name=\"android.permission.READ_EXTERNAL_STORAGE\"/>",
  "<uses-permission android:name=\"android.permission.WRITE_EXTERNAL_STORAGE\"/>",
  "<uses-permission android:name=\"android.permission.READ_MEDIA_IMAGES\"/>",
  "<uses-permission android:name=\"android.permission.READ_MEDIA_VIDEO\"/>",
  "<uses-permission android:name=\"android.permission.READ_MEDIA_AUDIO\"/>",
  "<uses-permission android:name=\"android.permission.ACCESS_FINE_LOCATION\"/>",
  "<uses-permission android:name=\"android.permission.ACCESS_COARSE_LOCATION\"/>",
  "<uses-permission android:name=\"android.permission.POST_NOTIFICATIONS\"/>",
  "<uses-permission android:name=\"android.permission.BLUETOOTH_SCAN\"/>",
  "<uses-permission android:name=\"android.permission.BLUETOOTH_CONNECT\"/>"
]

POST_NOTIFICATIONS 用于 Android 13+（API 33+）推送通知权限检测；BLUETOOTH_SCAN / BLUETOOTH_CONNECT 用于蓝牙权限检测（Android 12+ / API 31+）。

注意：真机运行 UTS 插件需要使用自定义基座，修改权限声明后需重新打包自定义基座或提交云打包。

iOS

插件内置 Info.plist 已包含以下使用说明，如需自定义文案可在项目的 manifest.json -> app-plus -> distribute -> ios -> privacyDescription 中覆盖：

• NSMicrophoneUsageDescription - 录音
• NSCameraUsageDescription - 相机
• NSPhotoLibraryUsageDescription - 相册读取
• NSPhotoLibraryAddUsageDescription - 相册写入
• NSLocationWhenInUseUsageDescription - 使用期间定位

错误码

更新记录

• 1.0.0：初始版本，支持权限检测、请求、设置跳转、推送通知权限与权限事件监听。

许可证

MIT License