更新记录

1.0.2（2025-11-11）

明晰文档说明~

1.1.0（2025-09-30）

1.1.1更新

UTS权限管理插件 (uts-permission)

插件简介

这是一个基于 UTS (UniApp TypeScript) 实现的 Android与ios 动态权限申请插件，提供了简洁易用的 API 来管理 Android与ios 运行时权限。

特性

• ✅ 使用 UTS 语法编写，无需编译原生基座
• ✅ 支持多种常用权限的申请和管理
• ✅ 提供同步和异步两种调用方式
• ✅ 完整的 TypeScript 类型定义
• ✅ 支持单个和批量权限申请
• ✅ 支持特殊权限（悬浮窗、系统设置）

支持的权限类型

普通权限

• storage - 写入外部存储权限
• readStorage - 读取外部存储权限
• camera - 相机权限
• location - 精确定位权限
• coarseLocation - 大致定位权限
• microphone - 麦克风/录音权限
• phone - 拨打电话权限
• phoneState - 读取电话状态权限
• contacts - 读取通讯录权限
• writeContacts - 写入通讯录权限
• sms - 发送短信权限
• readSms - 读取短信权限
• receiveSms - 接收短信权限

特殊权限

• overlay - 悬浮窗权限
• writeSettings - 系统设置权限

安装方式

方式一：通过 HBuilderX 导入

1. 将 uts-permission 文件夹复制到项目的 uni_modules 目录下
2. 重新编译运行项目

方式二：通过插件市场导入

1. 在 HBuilderX 中打开插件市场
2. 搜索 "uts-permission"
3. 点击导入到项目

使用方法

#

平台兼容性

uni-app

uni-app x

Z-UTS权限管理插件 (z-uts-permission)

插件简介

这是一个基于 UTS (UniApp TypeScript) 实现的跨平台动态权限申请插件，支持 Android 和 iOS 平台，提供了简洁易用的 API 来管理运行时权限。

特性

• ✅ 使用 UTS 语法编写，需要编译原生基座
• ✅ 支持 Android 和 iOS 双平台
• ✅ 支持多种常用权限的申请和管理
• ✅ 提供同步和异步两种调用方式
• ✅ 完整的 TypeScript 类型定义
• ✅ 支持单个和批量权限申请
• ✅ 支持特殊权限（Android：悬浮窗、系统设置）

支持的权限类型

平台差异对比表

说明：

• ✅ 表示该平台支持此权限
• ❌ 表示该平台不支持此权限
• ✅* 表示该平台会映射到其他权限

Android 普通权限（13个）

• storage - 写入外部存储权限
• readStorage - 读取外部存储权限
• camera - 相机权限
• location - 精确定位权限
• coarseLocation - 大致定位权限
• microphone - 麦克风/录音权限
• bluetooth - 蓝牙权限
• phone - 拨打电话权限
• phoneState - 读取电话状态权限
• contacts - 读取通讯录权限
• writeContacts - 写入通讯录权限
• sms - 发送短信权限
• readSms - 读取短信权限
• receiveSms - 接收短信权限

Android 特殊权限（2个）

• overlay - 悬浮窗权限
• writeSettings - 系统设置权限

iOS 权限（6个）

• camera - 相机权限
• photoLibrary - 相册权限
• location - 定位权限
• microphone - 麦克风权限
• contacts - 通讯录权限
• bluetooth - 蓝牙权限

平台映射说明

iOS 平台映射：

• storage → photoLibrary (相册权限)
• readStorage → photoLibrary (相册权限)
• coarseLocation → location (定位权限)
• writeContacts → contacts (通讯录权限)

安装方式

方式一：通过 HBuilderX 导入

1. 将 z-uts-permission 文件夹复制到项目的 uni_modules 目录下
2. 重新编译运行项目

方式二：通过插件市场导入

1. 在 HBuilderX 中打开插件市场
2. 搜索 "z-uts-permission"
3. 点击导入到项目

使用方法

1. 导入插件

import { 
  checkPermission, 
  checkPermissions, 
  requestPermission, 
  requestPermissions,
  openAppSettings,
  openSystemSettings,
  getPermissionName,
  getSupportedPermissions
} from "@/uni_modules/z-uts-permission"

2. 检查单个权限

const result = checkPermission({ permission: "camera" })
console.log(result.granted) // true 或 false

3. 检查多个权限

const result = checkPermissions({ 
  permissions: ["camera", "storage", "location"] 
})
console.log(result.allGranted) // 是否全部授予
console.log(result.permissions) // 每个权限的详细状态

4. 申请单个权限

requestPermission({ permission: "camera" }, (result) => {
  if (result.granted) {
    console.log("相机权限已授予")
  } else {
    console.log("相机权限被拒绝")
  }
})

5. 申请多个权限

requestPermissions({ 
  permissions: ["camera", "storage", "microphone"] 
}, (result) => {
  if (result.allGranted) {
    console.log("所有权限已授予")
  } else {
    console.log("部分权限被拒绝")
    console.log(result.permissions)
  }
})

6. 申请蓝牙权限

// 申请蓝牙权限
requestPermission({ permission: "bluetooth" }, (result) => {
  if (result.granted) {
    console.log("蓝牙权限已授予")
  } else {
    console.log("蓝牙权限被拒绝")
  }
})

7. 申请特殊权限（仅 Android）

// 申请悬浮窗权限
requestPermission({ permission: "overlay" }, (result) => {
  console.log("悬浮窗权限:", result.granted)
})

// 申请系统设置权限
requestPermission({ permission: "writeSettings" }, (result) => {
  console.log("系统设置权限:", result.granted)
})

8. 打开设置页面

支持平台：Android 和 iOS

// 打开应用设置页面（引导用户手动开启权限）
openAppSettings({}, (result) => {
  console.log("已打开应用设置页面")
})

// 打开系统设置页面
// Android：打开系统设置主页面
// iOS：同应用设置页面（iOS 限制，只能打开应用设置）
openSystemSettings({}, (result) => {
  console.log("已打开系统设置页面")
})

平台差异说明：

使用场景：

• 用户拒绝权限后，引导用户去设置页面手动开启
• 权限被永久拒绝时，提示用户前往设置页面

9. 获取权限名称

const result = getPermissionName({ permission: "camera" })
console.log(result.name) // "相机权限"

10. 获取所有支持的权限

const result = getSupportedPermissions({})
console.log(result.permissions) // 所有支持的权限列表

API 文档

checkPermission(options)

检查单个权限状态（同步方法）

参数：

• options.permission (string) - 权限名称

返回值：

{
  success: boolean,
  permission: string,
  granted: boolean,
  message: string
}

checkPermissions(options)

检查多个权限状态（同步方法）

参数：

• options.permissions (string[]) - 权限名称数组

返回值：

{
  success: boolean,
  allGranted: boolean,
  permissions: Array<{
    permission: string,
    granted: boolean
  }>
}

requestPermission(options, callback)

申请单个权限（异步方法）

参数：

• options.permission (string) - 权限名称
• callback (function) - 回调函数

回调参数：

{
  success: boolean,
  permission: string,
  granted: boolean,
  message: string
}

requestPermissions(options, callback)

申请多个权限（异步方法）

参数：

• options.permissions (string[]) - 权限名称数组
• callback (function) - 回调函数

回调参数：

{
  success: boolean,
  allGranted: boolean,
  permissions: Array<{
    permission: string,
    granted: boolean
  }>,
  message: string
}

Android 权限配置

AndroidManifest.xml 配置

Android 需要在 AndroidManifest.xml 中声明权限，插件已经自动处理了常用权限，但如果需要自定义，可以在项目的 manifest.json 中配置：

{
  "app-plus": {
    "distribute": {
      "android": {
        "permissions": [
          "<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.ACCESS_FINE_LOCATION\"/>",
          "<uses-permission android:name=\"android.permission.ACCESS_COARSE_LOCATION\"/>",
          "<uses-permission android:name=\"android.permission.RECORD_AUDIO\"/>",
          "<uses-permission android:name=\"android.permission.BLUETOOTH_CONNECT\"/>",
          "<uses-permission android:name=\"android.permission.BLUETOOTH_SCAN\"/>",
          "<uses-permission android:name=\"android.permission.CALL_PHONE\"/>",
          "<uses-permission android:name=\"android.permission.READ_PHONE_STATE\"/>",
          "<uses-permission android:name=\"android.permission.READ_CONTACTS\"/>",
          "<uses-permission android:name=\"android.permission.WRITE_CONTACTS\"/>",
          "<uses-permission android:name=\"android.permission.SEND_SMS\"/>",
          "<uses-permission android:name=\"android.permission.READ_SMS\"/>",
          "<uses-permission android:name=\"android.permission.RECEIVE_SMS\"/>",
          "<uses-permission android:name=\"android.permission.SYSTEM_ALERT_WINDOW\"/>",
          "<uses-permission android:name=\"android.permission.WRITE_SETTINGS\"/>"
        ]
      }
    }
  }
}

Android 权限说明

• 蓝牙权限：Android 12 (API 31) 及以上需要 BLUETOOTH_CONNECT 和 BLUETOOTH_SCAN 权限
• 存储权限：Android 10 (API 29) 及以上推荐使用 Scoped Storage
• 定位权限：需要同时声明 ACCESS_FINE_LOCATION 和 ACCESS_COARSE_LOCATION
• 特殊权限：SYSTEM_ALERT_WINDOW 和 WRITE_SETTINGS 需要用户手动授权

iOS 权限配置

Info.plist 配置

iOS 需要在 Info.plist 中配置权限描述，插件已经内置了默认的权限描述，但你也可以在项目的 manifest.json 中自定义：

{
  "app-plus": {
    "distribute": {
      "ios": {
        "privacyDescription": {
          "NSCameraUsageDescription": "需要访问您的相机以拍摄照片和视频",
          "NSPhotoLibraryUsageDescription": "需要访问您的相册以选择照片和视频",
          "NSPhotoLibraryAddUsageDescription": "需要访问您的相册以保存照片和视频",
          "NSLocationWhenInUseUsageDescription": "需要访问您的位置信息以提供基于位置的服务",
          "NSLocationAlwaysUsageDescription": "需要始终访问您的位置信息",
          "NSLocationAlwaysAndWhenInUseUsageDescription": "需要访问您的位置信息以提供基于位置的服务",
          "NSMicrophoneUsageDescription": "需要访问您的麦克风以录制音频",
          "NSBluetoothAlwaysUsageDescription": "需要访问您的蓝牙以连接设备",
          "NSBluetoothPeripheralUsageDescription": "需要访问您的蓝牙以连接外围设备",
          "NSContactsUsageDescription": "需要访问您的通讯录"
        }
      }
    }
  }
}

iOS 权限说明

• 相机权限：需要配置 NSCameraUsageDescription
• 相册权限：需要配置 NSPhotoLibraryUsageDescription 和 NSPhotoLibraryAddUsageDescription
• 定位权限：需要配置 NSLocationWhenInUseUsageDescription 或 NSLocationAlwaysUsageDescription
• 麦克风权限：需要配置 NSMicrophoneUsageDescription
• 蓝牙权限：需要配置 NSBluetoothAlwaysUsageDescription 和 NSBluetoothPeripheralUsageDescription
• 通讯录权限：需要配置 NSContactsUsageDescription

注意事项

1. 编译原生基座：本插件需要编译原生基座才能使用，不能直接在标准基座中运行
2. 平台支持：支持 Android 和 iOS 双平台
3. Android 版本：部分权限在不同 Android 版本上的行为可能不同
4. iOS 权限：iOS 权限需要在 Info.plist 中配置权限描述
5. 特殊权限：Android 的悬浮窗和系统设置权限需要跳转到系统设置页面进行授权
6. 权限说明：建议在申请权限前向用户说明权限用途
7. 打开设置页面：
   • Android：openAppSettings 打开应用设置，openSystemSettings 打开系统设置
   • iOS：两个方法都打开应用设置页面（iOS 系统限制）
8. 编译基座步骤：
   • 在 HBuilderX 中选择"运行" -> "运行到手机或模拟器" -> "制作自定义调试基座"
   • 等待编译完成后，使用自定义基座运行项目

更新日志

1.0.0 (2025-09-30)

• 首次发布
• 支持常用权限的检查和申请
• 支持特殊权限（悬浮窗、系统设置）
• 提供完整的 TypeScript 类型定义

开发文档

• UTS 语法
• UTS API插件
• Hello UTS

许可证

MIT License

技术支持

如有问题或建议，欢迎提交 Issue。