更新记录

1.0.0（2026-10-19） 下载此版本

• 首次发布
• Android：基于 uni.createRequestPermissionListener 实现全局权限申请监听
• 用户触发系统权限弹窗时，在屏幕上方同步展示权限名称与用途说明
• 用户点击允许或拒绝后，系统弹窗与说明浮层同时自动移除
• 说明内容在 App.vue 中通过 initPermissionTips 配置一次即可，业务代码无需改动
• 权限名支持 CAMERA / permission.CAMERA / android.permission.CAMERA 三种写法
• 未配置的权限使用内置权限名与默认说明兜底
• 权限被永久拒绝时不再出现「闪一下」的说明浮层
• 一次申请多个权限时，说明会保持到最后一个系统弹窗关闭；同组权限只展示一次，配置一条即可复用（如 READ_CONTACTS / WRITE_CONTACTS、精确 / 粗略定位）
• 说明浮层顶部自动避让状态栏、刘海与安全区域
• 提供 stopPermissionTips，需要时可停止监听
• 支持标准基座直接测试，无需自定义基座

平台兼容性

uni-app(5.0)

uni-app x(5.0)

其他

hy-permission-tips 权限申请用途说明

用户触发系统权限弹窗时，在屏幕上方同步展示该权限的名称与用途说明；用户点击允许或拒绝后，说明自动消失。

用于满足华为、小米等应用商店对「权限申请目的告知」的审核要求。

仅 Android App 生效；iOS 上可以正常编译与调用，但不会展示说明（iOS 的权限说明由 info.plist 配置）。

为什么需要

Android 系统权限弹窗只显示权限本身，不显示业务用途。应用商店审核通常要求：在申请敏感权限时，同步向用户说明该权限用于什么功能。

本插件监听 uni 权限通道，在系统弹窗出现的同时展示用途说明，不改变业务调用方式。

特点

• 零侵入：业务代码保持原样，只需在 App.vue 的 onLaunch 中配置一次。
• 无需自定义基座：不包含 AndroidManifest.xml，可直接用 HBuilderX 标准基座调试。
• 配置简单：纯 JS 数组，短权限名即可，name 可省略。
• 权限组文案复用：READ_CONTACTS / WRITE_CONTACTS 等只需配置一条。
• 自动避让状态栏、刘海与安全区域；权限被永久拒绝时不会闪烁。

使用方式

1. 在 App.vue 中初始化一次

tips 只需要包含实际会申请的权限；name 可省略，插件内置了常见权限的中文名。

<script>
    // #ifdef APP-PLUS
    import { initPermissionTips } from '@/uni_modules/hy-permission-tips'
    // #endif

    export default {
        onLaunch() {
            // #ifdef APP-PLUS
            initPermissionTips({
                tips: [{
                        permission: 'CAMERA',
                        content: '用于拍摄头像、扫描二维码，仅在您主动操作时调用相机，不会在后台使用'
                    },
                    {
                        permission: 'RECORD_AUDIO',
                        content: '用于录制语音消息，仅在您主动录音时使用麦克风，不会在后台录音'
                    },
                    {
                        permission: 'ACCESS_FINE_LOCATION',
                        content: '用于展示附近门店、计算距离，不会在后台持续获取位置'
                    }
                ]
            })
            // #endif
        }
    }
</script>

2. 业务代码保持原样

uni.chooseImage({
    count: 1,
    sourceType: ['camera']
})

系统弹窗出现时，顶部会同步显示「相机权限 / 用于拍摄头像、扫描二维码…」；用户点击允许或拒绝后，说明自动移除。

API

initPermissionTips(options)

初始化权限用途说明。重复调用只会更新说明内容，不会重复注册监听。

PermissionTip：

stopPermissionTips()

停止监听并移除当前说明浮层。一般无需调用。

常用权限

说明与限制

• 只有通过 uni 权限通道发起的申请才会触发说明浮层，例如 uni.getLocation、uni.chooseImage、uni.scanCode、uni.addPhoneContact。
• 系统或三方 SDK 在原生层直接调用 requestPermissions 时，Android 不提供「申请前/弹窗时」回调，JavaScript 侧无法拦截，插件不会展示说明。
• 调试基座首启动时出现的「访问电话」弹窗来自基座自身（uni统计采集设备信息），不属于业务代码，也不经过 uni 权限通道。
• 未在 tips 中配置的权限会使用内置权限名与默认说明「用于实现相关业务功能」，建议为实际使用的敏感权限显式配置用途。
• 同一权限组只需配置一条，且同一次申请中同组权限只展示一条说明。例如 uni.addPhoneContact 会先申请「读取联系人」再申请「写入联系人」，系统连续弹出两次授权框；只配置 READ_CONTACTS（或 WRITE_CONTACTS）中的一条，另一个会自动复用同一条文案。精确定位与粗略定位同理。
• 一次申请多个不同权限时，说明会保持到最后一个系统弹窗关闭。
• 说明浮层仅覆盖屏幕上方区域，不会遮挡系统权限弹窗的允许/拒绝按钮；顶部会自动避让状态栏、刘海与安全区域。

常见问题

点击后没有出现说明浮层？

分三种情况：

• 权限已授权：系统不会再弹窗，自然也不会显示说明。可到系统设置中撤销权限后再试。
• 权限被「永久拒绝」（用户曾选择拒绝且系统不再询问）：系统不会再次弹窗，申请立即返回失败。插件已做延迟展示与取消处理，此时不会出现「闪一下」的浮层。
• 该 API 本身不申请权限：例如 Android 13+ 的相册选择器使用系统 Photo Picker，不需要存储权限；uni.getRecorderManager().start() 录音前需要业务侧自行申请 RECORD_AUDIO。

恢复权限的方法：设置 → 应用 → 当前应用 → 权限中重新开启；或卸载重装调试基座。

使用 adb 调试时可执行以下命令重置（部分 ROM 上 pm reset-permissions 无法清除「不再询问」标记，此时用 pm clear）：

adb shell pm clear <包名>

关于标准基座

插件不包含 AndroidManifest.xml，可直接使用 HBuilderX 标准基座运行。首次运行需要联网下载 UTS 运行扩展。

如果修改插件后编译被跳过（提示「文件未发生变化」），删除以下缓存目录后重新编译：

unpackage/cache/uts_standard_android/app-android/uts/uni_modules/hy-permission-tips