# PermissionHelper

**Repository Path**: binai/permission-helper

## Basic Information

- **Project Name**: PermissionHelper
- **Description**: PermissionHelper提供了一个简单的基于注释的API来处理HarmonyOS Java应用软件运行时所需要的权限。

PermissionHelper框架库减轻了开发者编写一堆检查语句的负担，不管您是否授予了权限，以保持代码的干净整洁。
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 5
- **Forks**: 0
- **Created**: 2021-03-05
- **Last Updated**: 2021-07-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: harmony, HarmonyOS, OpenHarmony, 鸿蒙, 权限

## README

# PermissionHelper

#### 介绍
PermissionHelper提供了一个简单的基于注释的API来处理HarmonyOS Java应用软件运行时所需要的权限。

PermissionHelper框架库减轻了开发者编写一堆检查语句的负担，不管您是否授予了权限，以保持代码的干净整洁。

#### 安装教程

要将PermissionsDispatcher添加到项目中，在需要权限的module的build.gradle文件中的dependencies中添加如下代码即可使用

```groovy
dependencies {
    ......

    implementation project(':permission')
    implementation project(':permission_annotation')
    annotationProcessor project(':permission_compiler')
}
```

#### 使用说明

下面以一个简单的`ohos.permission.CAMERA`相机权限例子简单介绍PermissionHelper框架的使用

1、在config.json文件中添加如下权限代码

```json
   "reqPermissions": [
      {"name": "ohos.permission.CAMERA"}
    ]
```

2、添加annontations注解

[^注意]: Java方法必须是public修饰，否则无法使用

Annotation使用说明如下表所示：

|         注解/Annotation         | 必须请求/Required | 描述/Description                                             |
| :-----------------------------: | :---------------: | :----------------------------------------------------------- |
|      `@CompilePermissions`      |         √         | 注解在Ability或者Slice上，标记此类有权限请求操作。           |
|     `@NeedsSelfPermission`      |         √         | 注解在一个需要请求权限（支持添加多个权限）的Java方法上，此方法通过`verifySelfPermission(String permission)`方法进行检测，确认方式权限授权情况。 |
|    `@NeedsCallingPermission`    |                   | 注解在一个需要请求权限（支持添加多个权限）的Java方法上，此方法通过`verifyCallingPermission(String permission)`方法进行检测，确认方式权限授权情况。 |
| `@NeedsCallingOrSelfPermission` |                   | 注解在一个需要请求权限（支持添加多个权限）的Java方法上，此方法通过`verifyCallingOrSelfPermission(String permission)`方法进行检测，确认方式权限授权情况。 |
|     `@OnPermissionBlocked`      |                   | 注解在一个方法上，在权限请求失败，或者权限被拒绝授权时回调此方法 |

```java
@CompilePermissions
public class MainAbilitySlice extends AbilitySlice {

    @NeedsSelfPermission("ohos.permission.CAMERA")
    public void selfCameraPermission() {
        new ToastDialog(getAbility()).setText("self permission success.").show();
    }

    @NeedsCallingPermission("ohos.permission.CAMERA")
    public void callingCameraPermission() {
        new ToastDialog(getAbility()).setText("calling permission success.").show();
    }

    @NeedsCallingOrSelfPermission("ohos.permission.CAMERA")
    public void callingOrSelfCameraPermission() {
        new ToastDialog(getAbility()).setText("calling or self permission success.").show();
    }

    @OnPermissionBlocked("ohos.permission.CAMERA")
    public void onNeverAskAgain() {
        new ToastDialog(getAbility()).setText("request permission fail.").show();
    }

}
```

3、调用委托类的方法

[^注意]:编译后，PermissionHelper会在`@CompilePermissions`注解的类的包名下自动生成一个委托类（Ability Name/Slice Name + PermissionHelper），类名为`MainAbilitySlicePermissionHelper`。

在`@CompilePermissions`注解的类中通过委托类启动权限请求

```java
@CompilePermissions
public class MainAbilitySlice extends AbilitySlice {

    @Override
    public void onStart(Intent intent) {
        super.onStart(intent);
        super.setUIContent(ResourceTable.Layout_ability_main);

        findComponentById(ResourceTable.Id_text_helloworld).setClickedListener((Component component) -> {
            MainAbilitySlicePermissionHelper.selfCameraPermission(this);
        });

    }

    @NeedsSelfPermission("ohos.permission.CAMERA")
    public void selfCameraPermission() {
        new ToastDialog(getAbility()).setText("self permission success.").show();
    }
    
    ......
    
}
```

在Slice吸附的Ability中的`onRequestPermissionsFromUserResult(int requestCode, String[] permissions, int[] grantResults)`权限回调方法中调用委托类的相应`onRequestPermissionsFromUserResult(int requestCode, String[] permissions, int[] grantResults)`方法处理权限回调请求

```java
public class MainAbility extends Ability {

    @Override
    public void onStart(Intent intent) {
        super.onStart(intent);
        super.setMainRoute(MainAbilitySlice.class.getName());
    }

    @Override
    public void onRequestPermissionsFromUserResult(int requestCode, String[] permissions, int[] grantResults) {
        super.onRequestPermissionsFromUserResult(requestCode, permissions, grantResults);
        MainAbilitySlicePermissionHelper.onRequestPermissionsFromUserResult(requestCode, permissions, grantResults);
    }
}
```

#### FQA

如果在使用PermissionHelper时，发现DevEco Studio无法识别/找不到委托类（Ability Name/Slice Name + PermissionHelper），可以先执行Build--->Build APP(s)/Hap(s)--->Build Debug Hap(s)；

如果Build构建之后还是无法识别/找不到委托类（Ability Name/Slice Name + PermissionHelper），可以选中module下的build目录下面build/generated/source/annotation/debug/目录，鼠标右击执行Mark Directory as --->Generated Sources Root修复问题。

####  Licence

```tex
Copyright 2021 aibin

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
```