PermissionsDispatcher 使用指南

PermissionsDispatcher 使用指南

PermissionsDispatcher A declarative API to handle Android runtime permissions. 项目地址: https://gitcode.com/gh_mirrors/per/PermissionsDispatcher

PermissionsDispatcher 是一个针对 Android 平台的权限管理库，它通过简单的注解方式来处理运行时权限请求，让应用开发者能够从复杂的权限检查逻辑中解放出来，保持代码的清晰和安全。以下是详细的使用教程，包括安装步骤、基本用法、API示例以及集成方法。

安装指南

确保您的项目已迁移到 MavenCentral，因为PermissionsDispatcher已不再支持jCenter。要将PermissionsDispatcher添加到您的项目中，请在应用模块的build.gradle文件中加入以下依赖（替换${latest.version}为最新的版本号）：

对于传统的Java项目：

dependencies {
    implementation "com.github.permissions-dispatcher:permissionsdispatcher:${latest.version}"
    annotationProcessor "com.github.permissions-dispatcher:permissionsdispatcher-processor:${latest.version}"
}

如果您使用的是Kotlin，则需要启用kotlin-kapt插件并进行相应的配置：

plugins {
    id 'kotlin-kapt'
}

dependencies {
    implementation "com.github.permissions-dispatcher:permissionsdispatcher:$latest.version"
    kapt "com.github.permissions-dispatcher:permissionsdispatcher-processor:$latest.version"
}

查阅迁移指南，如果您仍依赖于较旧的appcompat版本，可能需要使用3.x版本。

项目的使用说明

准备工作：AndroidManifest.xml

首先，在您的AndroidManifest.xml文件中添加所需权限的声明。例如，为相机权限添加如下行：

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

应用注解

接下来，在处理权限的Activity或Fragment上使用@RuntimePermissions注解，并且对那些需要权限的方法使用@NeedsPermission注解。您还可以定义处理特定场景的回调，如被拒绝时的处理逻辑(@OnPermissionDenied)，以及当用户选择“不再提醒”时的响应(@OnNeverAskAgain)。

以Kotlin为例：

@RuntimePermissions
class MainActivity : AppCompatActivity(), View.OnClickListener {

    @NeedsPermission(Manifest.permission.CAMERA)
    fun showCamera() {
        // 实现展示相机的功能
    }

    @OnShowRationale(Manifest.permission.CAMERA)
    fun explainCameraPermission(request: PermissionRequest) {
        // 展示理由对话框给用户解释为什么需要权限
        // request对象用于继续或取消请求
    }

    @OnPermissionDenied(Manifest.permission.CAMERA)
    fun cameraPermissionDenied() {
        Toast.makeText(this, "相机访问权限被拒绝", Toast.LENGTH_SHORT).show()
    }

    @OnNeverAskAgain(Manifest.permission.CAMERA)
    fun cameraPermissionNeverAskAgain() {
        Toast.makeText(this, "相机权限请求永久关闭", Toast.LENGTH_SHORT).show()
    }
    
    // 在适当的生命周期内调用生成的函数来处理权限请求和结果
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        findViewById(R.id.button_camera).setOnClickListener { showCameraWithPermissionCheck() }
    }

    override fun onRequestPermissionsResult(requestCode: Int, permissions: Array<out String>, grantResults: IntArray) {
        super.onRequestPermissionsResult(requestCode, grantResults)
        onRequestPermissionsResult(requestCode, grantResults)
    }
}

委托权限处理

在Kotlin中，框架会自动生成必要的委托函数来简化权限处理流程，如showCameraWithPermissionCheck()和自动处理onRequestPermissionsResult。

API使用文档

PermissionsDispatcher主要提供了几个核心注解来简化权限管理：

• @RuntimePermissions: 标记在类上，表明该类使用了运行时权限管理。
• @NeedsPermission: 标记在需要权限才能执行的方法上。
• @OnShowRationale: 当请求权限前允许向用户解释为何需要该权限。
• @OnPermissionDenied: 权限被用户拒绝时触发。
• @OnNeverAskAgain: 用户选择了不希望再次被询问此权限时触发。

特殊权限处理

查看特殊权限支持，了解如何处理一些特殊的权限请求场景。

总结

PermissionsDispatcher通过其强大的注解驱动机制极大简化了Android运行时权限的处理过程。遵循上述步骤，您可以有效地集成这个库到项目中，从而避免手动处理复杂的权限请求逻辑。记得适时查阅官方文档和示例项目，以便获取最新信息和最佳实践。

PermissionsDispatcher A declarative API to handle Android runtime permissions. 项目地址: https://gitcode.com/gh_mirrors/per/PermissionsDispatcher