PermissionsDispatcher 使用说明

PermissionsDispatcher注解类的一些说明以及容易用混的地方

PermissionsDispatcher 使用说明

PermissionsDispatcher

PermissionsDispatcher是一套基于注解的API函数，用于针对Android6.0以上的运行时权限申请操作，开源，使用简单，减少重复性代码的编写

[项目地址]:https://github.com/permissions-dispatcher/PermissionsDispatcher

（地址上有较为详细的文档，可参阅上手）

使用方法

• 添加引用

直接在app/build.gradle中添加响应的引用

    dependencies {
      compile("com.github.hotchemi:permissionsdispatcher:${latest.version}") {
          // 如果没有使用android.app.Fragment，可以排除相应支持模块
          exclude module: "support-v13"
      }
      annotationProcessor "com.github.hotchemi:permissionsdispatcher-processor:${latest.version}"
    }

• 申请权限

第一步：在AndroidMinifest.xml中预定义权限

<uses-permission android:name="android.permission.CAMERA"/>

第二部：在使用相应权限的Activity或Fragment中，添加运行时注解

@RuntimePermissions
class MainActivity  extends AppCompatActivity {
        @NeedsPermission(Manifest.permission.CAMERA)
        public void showCamera() {
                supportFragmentManager.beginTransaction()
                        .replace(R.id.sample_content_fragment, CameraPreviewFragment.newInstance())
                        .addToBackStack("camera")
                        .commitAllowingStateLoss()
                }
        @OnShowRationale(Manifest.permission.CAMERA)
        public void showRationaleForCamera(PermissionRequest request) {
                showRationaleDialog(R.string.permission_camera_rationale, request);
                }
        @OnPermissionDenied(Manifest.permission.CAMERA)
        public void onCameraDenied() {
                Toast.makeText(this, "相机权限被拒绝", Toast.LENGTH_SHORT).show()
                }
        @OnNeverAskAgain(Manifest.permission.CAMERA)
        public void onCameraNeverAskAgain() {
                Toast.makeText(this, "相机权限被拒绝切不再提示", Toast.LENGTH_SHORT)
                .show()
                }
        @Override
        public void onRequestPermissionsResult(int requestCode, @NonNull String[] permissions, @NonNull int[] grantResults) {
                super.onRequestPermissionsResult(requestCode, permissions, grantResults);
                MainActivityPermissionsDispatcher.onRequestPermissionsResult(this, requestCode, grantResults);
        }
}

其中用到的注解类型解释如下

注解，其实就是一种API的实现/调用方式，可以当成普通函数理解对待

注解名称	用法用途
@RuntimePermissions	支持Activity和Fragment，添加在需要使用运行时权限管理的类声明之前，用于表示此类需要使用PermissionsDispatcher框架，PermissionsDispatcher框架发现该注解后，即对当前类生成注解代码
@NeedsPermission	应用在需要申请权限的成员函数之前，对应的函数不能声明为private，针对该注解，PermissionsDispatcher会在注解类中生成{函数名}WithCheck的静态成员函数，参数为被注解类
@OnShowRationale	用于声明提示函数，用于向用户申请权限，函数参数比如为PermissionRequest的对象，通过对此对象调用来向用户弹出权限申请界面（PermissionRequest.proceed() or PermissionRequest.cancel()）
@OnPermissionDenied	当权限被拒绝时，回调成员函数的注解
@OnNeverAskAgain	当用户拒绝权限，并选中不再提示时，回调成员函数的注解

其中，@RuntimePermissions和@NeedsPermission注解为必要注解，其它根据需求为可选

第三步：make project。参考以上代码示例，make project时会生成注解类，类名为原类名+PermissionsDispatcher后缀，里面包含三部分内容：
权限请求函数映射：对于@NeedsPremission注解的函数进行映射，添加权限检查和申请的模块，并在通过权限检查或权限申请被同意后，回调原始函数。函数名为被注解函数名+WithCheck，参数为被注解类的this对象。在使用的时候，用户可以直接替换原函数调用。上面的示例代码，在注解类中的相应函数为showCameraWithCheck，用户只需要在以前调用showCamera函数的地方改为调用MainActivityPermissionsDispatcher.showCameraWithCheck(this)即可

权限请求结果回调：函数名为onRequestPermissionsResult的静态public成员函数，如果用户想在@OnPermissionDenied或@OnNeverAskAgain注解函数中添加处理逻辑的话，则必须实现ActivityCompat或者FragmentCompat类中的ActivityCompat.OnRequestPermissionsResultCallback接口（或继承AppCompatActivity），并在回调函数onRequestPermissionsResult中，调用注解类的onRequestPermissionsResult函数。在示例代码中，调用MainActivityPermissionsDispatcher.onRequestPermissionsResult(this, requestCode, grantResults)

权限请求控制器：注解代码的最后一部分，用于控制权限请求是否继续进行。对象在@OnShowRationale注解函数中被返回，用户可以根据需要调用request.proceed()继续请求或者request.cancel()取消请求，取消后会回调@OnPermissionDenied注解