更新记录

1.0.3（2026-09-01） 下载此版本

• 修复uniapp x兼容问题

1.0.0（2026-08-03） 下载此版本

新增

• 全量权限中心：统一权限别名与归一状态，替代 -1 / 0 / 1。
• API：
  • check：只读检测，不弹授权框
  • request / requestMany：申请权限；特殊权限跳转设置页
  • ensure：检测 → 申请 → 按需打开设置 → 再检测
  • openSetting：按权限别名或 SettingType 打开应用 / 定位 / 通知 / 悬浮窗等设置页
  • isSupported / listPermissions / getPermissionMeta / getPlatform
• 状态：granted、denied、permanentlyDenied、limited、serviceOff、unsupported、unknown、needManifest。
• 权限别名（完整映射见 permissions.js、readme.md）：
  • 定位：location、locationCoarse、locationBackground、locationService
  • 媒体：camera、microphone、photoRead、photoWrite
  • 存储：storageRead、storageWrite、manageExternalStorage
  • 通讯录 / 日历 / 提醒：contacts、contactsWrite、calendar、calendarWrite、reminders
  • 电话短信：phone、phoneState、callLog、sms、smsSend、smsReceive
  • 蓝牙 / 通知 / 传感器：bluetooth、bluetoothService、notification、activityRecognition、sensors
  • 生物识别与 iOS 隐私：faceId、tracking、localNetwork、speechRecognition、mediaLibrary
  • Android 特殊权限：overlay、writeSettings、batteryOptimization、installPackages、scheduleExactAlarm、notificationListener
  • 小程序：mpUserInfo、mpUserLocationBackground、mpWerun、mpInvoice、mpAddress
• 端实现：
  • Android：plus.android.requestPermissions + 特殊权限 Intent；API 33+ 使用 READ_MEDIA_*、POST_NOTIFICATIONS
  • iOS：getAppAuthorizeSetting + 原生 authorization / request
  • 鸿蒙：uni 授权查询与 openAppAuthorizeSetting
  • 小程序：getSetting / authorize / openSetting，别名映射 scope.*
  • H5：Permissions API / getUserMedia / Notification；openSetting 返回 false
• 运行时：Vue2、Vue3、App-vue、nvue。Demo：/uni_modules/lf-permission/pages/demo/demo。

文档

• readme.md：安装引入、状态说明、API 示例、权限全表（各端原生映射）、各端配置、调用顺序。

说明

• 引入路径：@/uni_modules/lf-permission/index.js。
• uni-app x UTS 代码位于 utssdk.pending（避免 UTS 编译失败导致整包不可用）。启用时改名为 utssdk。
• 插件不写入工程权限声明，由业务在各端自行配置。

平台兼容性

uni-app(5.07)

uni-app x(5.07)

lf-permission 使用教程

全量权限中心：统一别名检测、申请、跳转系统 / 小程序设置。

平台兼容

图例：√ 已验证；u 未充分验证；- 本版不支持。

运行时：Vue2、Vue3、App-vue、nvue。

1. 安装

1. 将本目录放到项目 uni_modules/lf-permission
2. 在 pages.json 注册 Demo：

{
  "path": "uni_modules/lf-permission/pages/demo/demo",
  "style": {
    "navigationBarTitleText": "权限中心"
  }
}

3. 在各端声明业务所需权限。插件不写入 manifest。用到哪项，声明哪项（见「各端配置」）。

2. 引入

Vue / App / 小程序 / H5 使用 JS 入口：

import {
  check,
  request,
  requestMany,
  ensure,
  openSetting,
  isSupported,
  listPermissions,
  getPermissionMeta,
  explainAndEnsure,
  getPlatform,
  PermissionStatus,
  SettingType
} from '@/uni_modules/lf-permission/index.js'

3. 核心概念

3.1 权限种类 kind

3.2 统一状态 status

旧插件（如 594）迁移：1 → granted，0 → denied，-1 → permanentlyDenied。

3.3 返回值

{
  permission: 'camera',
  status: 'granted',
  platform: 'android',
  native: 'android.permission.CAMERA',
  kind: 'runtime',
  special: false,
  canRequest: true,
  supported: true,
  message: 'granted'
}

4. API

4.1 getPlatform()

const platform = getPlatform()
// android | ios | harmony | mp-weixin | web

4.2 check(name) — 只读检测，不弹授权框

const ret = await check('camera')
if (ret.status === PermissionStatus.GRANTED) {
  // 已授权
} else if (ret.status === PermissionStatus.UNSUPPORTED) {
  // 当前端不支持
} else {
  // 未授权
}

4.3 request(name) — 申请

• runtime：弹出系统授权框
• special / service：打开设置页，用户手动开启后再次 check

const ret = await request('location')
if (ret.status === PermissionStatus.GRANTED) {
  // 已授权
} else if (ret.status === PermissionStatus.PERMANENTLY_DENIED) {
  await openSetting({ permission: 'location' })
}

4.4 requestMany(names, options)

默认逐个申请，与 1.0.x 相同。Android 可加 batch: true，把 runtime 权限合并成一次系统弹框；特殊权限仍单独走设置页。其它端忽略 batch。

const list = await requestMany(['camera', 'microphone'], {
  stopOnDenied: true
})

// Android 可选：一次弹框
await requestMany(['camera', 'microphone'], { batch: true })

4.5 ensure(name, options)

流程：check → request（可关）→ 仍拒绝时 openSetting（可开）→ 再 check。

const ret = await ensure('microphone', {
  request: true,
  openSettingOnDenied: true
})
if (ret.status === PermissionStatus.GRANTED) {
  // 录音
}

4.5.1 explainAndEnsure(name, options)

申请前先 uni.showModal 说明用途。用户取消则返回 denied，不弹系统框。不调用此函数时，check / request / ensure 行为不变。

const ret = await explainAndEnsure('camera', {
  title: '相机权限',
  content: '用于拍摄证件照片，不会用于其它用途。',
  request: true
})

Vue 页也可用可选组件 lf-permission-sheet（easycom 自动扫描，不接则不影响现有页面）：

<lf-permission-sheet
  :show="sheetShow"
  permission="camera"
  title="相机权限"
  content="用于拍摄证件照片"
  @result="onPerm"
  @cancel="sheetShow = false"
/>

4.6 openSetting(options)

await openSetting({ permission: 'overlay' })

await openSetting({ type: SettingType.APP })
await openSetting({ type: SettingType.LOCATION_SERVICE })
await openSetting({ type: SettingType.NOTIFICATION })
await openSetting({ type: SettingType.OVERLAY })
await openSetting({ type: SettingType.BATTERY })
await openSetting({ type: SettingType.INSTALL })
await openSetting({ type: SettingType.MANAGE_STORAGE })
await openSetting({ type: SettingType.WRITE_SETTINGS })
await openSetting({ type: SettingType.BLUETOOTH })
await openSetting({ type: SettingType.WIFI })

4.7 查询

await isSupported('overlay')

listPermissions({ onlyCurrent: true })
listPermissions({ group: 'media' })
listPermissions({ kind: 'special' })

getPermissionMeta('camera')

4.8 示例：拍照

async function takePhoto() {
  const ret = await ensure('camera', {
    request: true,
    openSettingOnDenied: true
  })

  if (ret.status !== PermissionStatus.GRANTED) {
    uni.showToast({ title: '需要相机权限', icon: 'none' })
    return
  }

  uni.chooseImage({
    count: 1,
    sourceType: ['camera']
  })
}

4.9 示例：定位

async function getMyLocation() {
  let service = await check('locationService')
  if (service.status === PermissionStatus.SERVICE_OFF) {
    await openSetting({ type: SettingType.LOCATION_SERVICE })
    service = await check('locationService')
    if (service.status !== PermissionStatus.GRANTED) {
      uni.showToast({ title: '请开启系统定位', icon: 'none' })
      return
    }
  }

  const appLoc = await ensure('location', {
    request: true,
    openSettingOnDenied: true
  })
  if (appLoc.status !== PermissionStatus.GRANTED) {
    uni.showToast({ title: '需要定位权限', icon: 'none' })
    return
  }

  uni.getLocation({
    type: 'gcj02',
    success: (res) => {
      console.log(res.latitude, res.longitude)
    }
  })
}

5. 权限别名全表

• 别名：传给 check / request / ensure 的名称
• Android / iOS / 鸿蒙 / 小程序：内部映射的原生标识；- 表示该端无此项，返回 unsupported
• 支持直接传原生串：android.permission.CAMERA、scope.userLocation、ohos.permission.CAMERA

5.1 定位

5.2 媒体 / 相册

5.3 存储

manageExternalStorage 应用商店审核风险高，无强需求不要使用。

5.4 通讯录 / 日历 / 提醒

5.5 电话 / 短信

5.6 蓝牙 / 通知 / 传感器

5.7 生物识别 / iOS 隐私

5.8 Android 特殊权限

仅 check + openSetting，不走普通 requestPermissions。

const ret = await check('overlay')
if (ret.status !== PermissionStatus.GRANTED) {
  await openSetting({ permission: 'overlay' })
  // 从设置返回后，在 onShow 中再次 check
}

5.9 小程序扩展 scope

定位、相机等优先使用统一别名（location、camera），插件映射到对应 scope.*。

6. 各端配置

6.1 Android（manifest.json）

用到什么加什么：

<!-- 定位 -->
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>
<!-- 后台定位（Android 10+，须先具备前台定位） -->
<uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION"/>

<!-- 相机 / 麦克风 -->
<uses-permission android:name="android.permission.CAMERA"/>
<uses-permission android:name="android.permission.RECORD_AUDIO"/>

<!-- 存储 / 媒体 -->
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/>
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>
<!-- Android 13+ -->
<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.POST_NOTIFICATIONS"/>

<!-- 蓝牙 Android 12+ -->
<uses-permission android:name="android.permission.BLUETOOTH_SCAN"/>
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT"/>

特殊权限除声明外，须调用 openSetting 完成用户开启。

6.2 iOS（Privacy 描述）

在 manifest 的 iOS 隐私说明中填写：

未填写用途文案时，系统拒绝授权，状态为 permanentlyDenied 或 denied。

6.3 鸿蒙

在鸿蒙模块中声明上表对应的 ohos.permission.*。检测与跳转使用 uni 授权 API。

6.4 小程序

1. 在 app.json / 小程序后台配置所需隐私接口与权限
2. 用户拒绝后调用 openSetting
3. 用户信息类 scope 须由用户点击触发

6.5 H5

支持定位、通知、摄像头、麦克风的检测与申请。
openSetting 无法打开浏览器站点设置页，返回 false，由页面文案引导用户手动开启。

7. 调用顺序

进入功能页
  → check(别名)
  → denied：request / ensure
  → permanentlyDenied / serviceOff：openSetting，onShow 中再 check
  → granted / limited：调用 uni.chooseImage / getLocation 等业务 API

export default {
  async onShow() {
    if (this._waitingPermission) {
      const ret = await check(this._waitingPermission)
      this._waitingPermission = ''
      // 按 ret.status 继续业务
    }
  },
  methods: {
    async askOverlay() {
      this._waitingPermission = 'overlay'
      await openSetting({ permission: 'overlay' })
    }
  }
}

8. Demo

路径：/uni_modules/lf-permission/pages/demo/demo

按当前端列出权限，支持检查、申请、ensure、打开设置。

9. 约束

1. 未在各端声明的权限，申请失败或进入 permanentlyDenied。
2. 无业务需求时，不声明电话、短信、通话记录、所有文件访问等敏感权限。
3. 与 lf-file-share 等插件相互独立，无依赖。
4. 后台定位、悬浮窗、电池优化、安装未知应用须符合应用商店审核要求。
5. uni-app x：UTS 代码在 utssdk.pending；当前使用 index.js。启用 UTS 时将目录改名为 utssdk。

10. 联系

• ---

• Email：lingfugroup@gmail.com