桃夭: 桃夭是鸿蒙系统上的一个权限请求框架，封装了权限请求逻辑，采用链式调用的方式请求权限，极大的简化了权限请求的代码。

# 桃夭

## 申请权限的一般步骤
* 判断是否有权限，如果有权限，直接进行下一步。
* 如果没有权限，则开始申请权限。
* 如果用户授权，进行下一步。
* 如果用户拒绝授权，后面再次申请权限，系统为了不打扰用户，将不会出现系统的权限弹窗。在用户拒绝授权后，需要弹窗提示用户必须授权才能访问当前功能，并引导用户到系统设置中打开相应的权限。
 每次申请权限的时候，都需要经过以上几个步骤，当申请的权限越来越多，大量的重复代码就出现了。为了减少重复代码，我封装了一个权限请求框架。

## 权限请求框架

**桃夭**是鸿蒙系统上的一款权限请求框架，封装了权限请求逻辑，采用**链式调用**的方式请求权限，极大的简化了权限请求的代码，同时支持在`UI`、`UIAbility`、`UIExtensionAbility`里面申请权限。需要注意的是，应用在`UIExtensionAbility`申请授权时，需要在`onWindowStageCreate`函数执行结束后或在`onWindowStageCreate`函数回调中申请权限。
本项目基于开源鸿蒙4.1开发，最低兼容到API 11，请将DevEco Studio升级到最新版，DevEco Studio版本低于5.0.3.403可能无法编译。

![效果图](./taoyao/screenshots/taoyao.gif)

## 桃夭名称来源
桃夭一词出自古代第一部诗歌总集《诗经》中《诗经·桃夭》，“桃之夭夭，灼灼其华。”桃花怒放千万朵，色彩鲜艳红似火。

## 下载安装
```
ohpm install @shijing/taoyao
```
## 申请运行时权限
```
TaoYao.with(this)
      .runtime()
      // 要申请的权限
      .permission(permissions)
      .onGranted(() => {
        // 权限申请成功
      })
      .onDenied(() => {
        // 权限申请失败
      })
      .request()
```
## 申请通知权限
```
TaoYao.with(this.context)
      .notification()
      .permission()
      .onGranted(() => {
        // 通知权限申请成功
        this.toast()
      })
      .onDenied(() => {
        // 权限申请失败，弹窗跳转到系统设置页面
        this.dialogController = new CustomDialogController({
          builder: PermissionDialog({message: reason}),
        })
        this.dialogController.open()
      })
      .request()
```
**申请权限变得如此之简单。**

## 其它功能
判断是否有通知权限，如果没有通知权限，不会申请通知权限
```
 /**
 * 判断是否有通知权限，如果没有通知权限，不会申请通知权限
 *
 * @returns true支持，false不支持
 */
 static isNotificationEnabled(): Promise<boolean> {
 return NotificationPermissionChecker.isNotificationEnabled()
 }
```
判断是否支持分布式通知
```
 /**
 * 判断是否支持分布式通知
 *
 * @returns true支持，false不支持
 */
 static isDistributedEnabled(): Promise<boolean> {
 return NotificationPermissionChecker.isDistributedEnabled()
 }
```
提供跳转到系统设置的方法
```
 /**
 * 跳转到系统设置页面
 *
 * @param context
 */
 static goToSettingPage(context: common.UIAbilityContext) {
 TaoYao.with(context).setting().goToSettingPage()
 }
```
有的时候仅仅只需判断是否有运行时权限，并不申请权限。
```
 /**
 * 仅仅检测是否有权限，如果没有权限，不会申请权限
 *
 * @param permissions
 * @returns true 有权限
 */
 static hasPermission(permissions: Array<Permissions>): boolean {
 const generalChecker = new GeneralChecker()
 return generalChecker.hasPermission(permissions)
 }
```
系统选择器 
系统选择器已经获取了对应权限的预授权，开发者使用系统选择器时，无需再次申请权限也可临时受限访问对应的资源。例如，当应用需要读取用户图片时，可通过使用照片选择器，在用户选择所需要的图片资源后，直接返回该图片资源，而不需要授予应用读取图片文件的权限。

联系人选择器，通过联系人选择器获取联系人，不需要申请通讯录权限。
```
TaoYao.with(this.context)
 .contact()
 .onSuccess((data) => {
 // 联系人列表
 if (data.length > 0) {
 // 联系人名称
 console.log("yunfei", data[0].name?.fullName)
 // 联系人号码
 console.log("yunfei", data[0]?.phoneNumbers?.[0]?.phoneNumber)
 }
 })
 .onError((err) => {
 console.log(err.message)
 })
 .selectContacts(new ContactBuilder()
 // 可以选择多个联系人
 .setMultiSelect(true))
```
相机选择器，拉起系统相机不需要申请相机权限。
```
TaoYao.with(this.context)
 .camera()
 .onSuccess((uri) => {
 // 拍照或者录像的文件沙箱路径
 console.log(uri)
 })
 .onError((err) => {
 console.log(err.stack)
 })
 .openSystemCamera(new CameraBuilder()
 // 后置相机，默认使用后摄
 .setCameraSelector(CameraSelector.CAMERA_POSITION_BACK)
 // 可以只要拍照，只要录像，默认拍照和录像都有
 .setUseCase([UseCase.PHOTO, UseCase.VIDEO])
 // 文件保存路径，可以不设置
 //.setSaveUri("")
 // 录制视频最大时长，可以不设置
 //.setVideoMaxDuration()
 )
```
图片、视频选择器，拉起系统图库不需要申请存储权限，只能获取选中的图片、视频
```
TaoYao.with(this.context)
 .media()
 .onSuccess((uris) => {
 uris.forEach((uri) => {
 console.log("yunfei", uri)
 })
 })
 .onError((err) => {
 console.log(err.stack)
 })
 .select(new MediaBuilder()
 // 选择媒体文件的最大数目
 .setMaxSelectNumber(10)
 // 可选择的媒体文件类型，图片类型、视频类型、图片和视频类型、动态照片类型
 .setMediaMineType(MediaMimeType.IMAGE_VIDEO_TYPE)
 )
```
文档选择器，拉起文档选择器不需要申请权限，只能获取选中的文档
```
TaoYao.with(this.context)
 .document()
 .onSuccess((uris) => {
 uris.forEach((uri) => {
 console.log("yunfei", uri)
 })
 })
 .onError((err) => {
 console.log(err.stack)
 })
 .select(new DocumentBuilder()
 // 选择媒体文件的最大数目
 .setMaxSelectNumber(10)
 // 指定选择的文件或者目录路径（可选）
 //.setDefaultFilePathUri("")
 // 选择是否对指定文件或目录授权，true为授权，当为true时，defaultFilePathUri为必选参数，拉起文管授权界面；false为非授权，拉起常规文管界面（可选）
 //.setAuthMode(false)
 // 选择文件的后缀类型['后缀类型描述|后缀类型']（可选） 若选择项存在多个后缀名，则每一个后缀名之间用英文逗号进行分隔（可选），后缀类型名不能超过100,选择所有文件：'所有文件(*.*)|.*';
 // 例如：['图片(.png, .jpg)|.png,.jpg', '文档|.txt', '视频|.mp4', '.pdf']
 .setFileSuffixFilters(['文档|.docx'])
 )
```
音频选择器，拉起音频选择器不需要申请权限，只能获取选中的音频
```
TaoYao.with(this.context)
 .audio()
 .onSuccess((uris) => {
 uris.forEach((uri) => {
 console.log("yunfei", uri)
 })
 })
 .onError((err) => {
 console.log(err.stack)
 })
 // 目前音频选择器不支持参数配置，默认可以选择所有类型的用户文件。
 .select(new AudioBuilder())
```
## 实现原理
实现原理请查看[实战鸿蒙，实现一款权限请求框架](https://www.jianshu.com/p/e03fd389ba9c?v=1715482521724)。 
本项目在开发过程中，借鉴了开源项目[AndPermission](https://github.com/yanzhenjie/AndPermission)，感谢该作者。

裴云飞/桃夭

简介

发行版

贡献者

近期动态

裴云飞/桃夭 .gitee-modal { width: 500px !important; }

简介

发行版

开源评估指数源自 OSS-Compass 评估体系，评估体系围绕以下三个维度对项目展开评估：

贡献者

近期动态

搜索帮助

裴云飞/桃夭