相机权限一次搞定:Kamera跨平台权限处理实战(Android、iOS与桌面端)
相机权限一次搞定:Kamera跨平台权限处理实战(Android、iOS与桌面端)
Kamera 是一个面向 Compose Multiplatform 的相机库(CameraK),它的最大亮点之一,就是把 相机权限处理 抽象成了一套跨 Android、iOS 与桌面端(macOS / Windows / Linux)的统一 API:一个 rememberCameraKPermissionState 组合函数,就能完成权限状态的读取、系统弹窗的发起,以及"永久拒绝"等复杂场景的兜底,让新手也能一次搞定多端相机权限。
为什么权限是跨平台相机的第一道坎 🚧
用 Compose Multiplatform 写相机应用时,权限是第一个绕不开的难题:
- Android:要走 Activity Result API 运行时申请,还要判断"用户是否点了不再询问"(PermanentlyDenied);
- iOS:弹窗只出现一次,拒绝即永久,还得在
Info.plist里声明用途描述,否则 App 直接崩溃; - macOS:弹窗时机特殊——不是"你申请时"弹,而是"打开相机时"弹;
- Windows / Linux:根本没有相机、麦克风的权限概念。
四套规则,四份代码?Kamera 的答案是:不需要。它在 CameraKPermissionState.kt 中定义了统一的公共接口,各平台只需实现 actual 分支,你的业务代码一行都不用改。
一套 API 全平台通用:rememberCameraKPermissionState
核心用法只有三步(来自官方 快速上手文档):
- 声明你要的权限,拿到状态对象;
- 检查
allGranted,未授权就展示你的说明界面; - 用户点击按钮时调用
launchRequest()发起系统弹窗。
val permissions = rememberCameraKPermissionState(CameraKPermission.CAMERA)
if (permissions.allGranted) {
CameraScreen()
} else {
Button(onClick = permissions::launchRequest) { Text("Allow camera") }
}
三种内置权限类型
Kamera 用 CameraKPermission.kt 中的封闭枚举定义了三类权限,覆盖绝大多数相机场景:
| 权限 | 用途 |
|---|---|
CAMERA |
打开相机、预览与拍照 |
MICROPHONE |
带声音的视频录制(enableAudio = true) |
GALLERY_ADD |
把照片/视频保存到系统相册(MediaSaverPlugin) |
六种状态,覆盖所有边界情况
PermissionStatus.kt 用一个密封接口描述了权限的全部可能状态:
Granted:已授权Limited:iOS 14+ 的"部分照片库"访问Denied(shouldShowRationale):被拒但还能再问,shouldShowRationale提示你是否应先解释原因PermanentlyDenied:只能去系统设置开启Restricted:被设备策略或家长控制锁定NotDetermined:还没问过
这套模型把 iOS 的 Limited、Android 的"不再询问"等差异都收进了同一个类型里,UI 层只需对六种状态做分支。
Android 端:自动识别"永久拒绝" 🤖
Android 实现见 RememberCameraKPermissionState.android.kt,它帮你处理了两个最头疼的细节:
- 走 Activity Result API 申请:
launchRequest()内部通过RequestMultiplePermissions契约发起弹窗,多个权限一次问完; - 自动推断 PermanentlyDenied:用户拒绝后,如果系统不再展示"拒绝理由"(
shouldShowRequestPermissionRationale为 false),Kamera 会把这个事实记录到本地偏好文件,下次直接读出PermanentlyDenied,提示你"只能去系统设置开了"。
另外,状态读取被放在 IO 线程完成、结果发布回主线程,不会阻塞 UI——这些细节都已在库里替你做好。
iOS 端:AVFoundation + Photos 双通道
iOS 实现见 RememberCameraKPermissionState.apple.kt:
- 相机与麦克风:通过 AVFoundation 申请,系统只弹一次窗,所以拒绝即视为永久拒绝,Kamera 会直接给你终态;
- 相册写入(GALLERY_ADD):通过 Photos 框架申请"仅添加"(add-only)访问,用户授权后你既能保存又不需要读权限,隐私友好;
- iOS 14 以下:不会主动问相册权限,状态读作
NotDetermined,真正保存时系统才会弹窗。
⚠️ 注意:iOS 要求 Info.plist 中声明 NSCameraUsageDescription 等用途描述,缺失时系统会直接终止 App。具体清单见 安装文档。
桌面端:Windows/Linux 零权限,macOS 有玄机 🖥️
桌面实现见 RememberCameraKPermissionState.desktop.kt:
- Windows / Linux:没有相机与麦克风权限,状态直接视为已授予,
launchRequest()什么都不做; - macOS:系统弹窗在"打开相机/麦克风时"出现,而不是"发起请求时"。为此 Kamera 做了两件事:
launchRequest()会通过 AVFoundation 为仍处于NotDetermined的权限触发弹窗;- 弹窗出现期间,每 500ms 轮询一次状态(
RefreshWhilePromptPending),确保用户点完"允许"后 UI 立即刷新——因为 macOS 不会把这个回答作为窗口生命周期事件通知你。
打包分发时,Info.plist 的用途描述和 entitlements.plist 中的 com.apple.security.device.camera 等 entitlement 缺一不可,示例配置可直接参考 Sample 工程。
相机与权限如何配合:Holder 从不弹窗
理解这一条,你的权限代码才算真正"一次搞定":
Kamera 的相机 Holder 自己从不弹窗——它只在打开相机前检查权限,缺失时发布
CameraKState.Error(Permission)错误状态;而rememberCameraKPermissionState在页面每次 resume 时自动重查状态。
这意味着一个非常顺畅的闭环:用户在系统设置里手动打开权限 → App 回到前台 → Holder 在下次 resume 时检测到已授权 → 无需任何重试逻辑,相机直接打开(原理见 state-holder API 文档 中的 recheckPermission 与 troubleshooting 中 Error(Permission) 一节)。
官方 Sample 的 PermissionScreen.kt 展示了完整的权限引导界面:解释为什么需要相机、列出还可能申请的权限(麦克风、相册)、"永久拒绝"时额外提供"打开系统设置"按钮——非常值得照抄的交互设计。
上手清单:5 步搞定权限 ✅
| 步骤 | 要点 |
|---|---|
| 1️⃣ | commonMain 中引入 camerak 依赖,版本见 安装文档 |
| 2️⃣ | Android:minSdk 23+;录制带声音再声明 RECORD_AUDIO |
| 3️⃣ | iOS:Info.plist 补齐 NSCameraUsageDescription、NSMicrophoneUsageDescription、NSPhotoLibraryAddUsageDescription |
| 4️⃣ | macOS 打包:补用途描述 + 相机/麦克风 entitlement |
| 5️⃣ | UI 中用 rememberCameraKPermissionState + launchRequest(),对 PermanentlyDenied 提供"去设置"入口 |
相关源码速查
| 文件 | 说明 |
|---|---|
| CameraKPermissionState.kt | 公共权限状态接口与 rememberCameraKPermissionState 声明 |
| CameraKPermission.kt | CAMERA / MICROPHONE / GALLERY_ADD 权限枚举 |
| PermissionStatus.kt | 六种权限状态定义 |
| CameraKPermissionChecker.kt | Holder 内部使用的权限检查器 |
| docs/getting-started/quick-start.md | 权限 + 预览 + 拍照完整示例 |
| docs/troubleshooting.md | Error(Permission) 等问题的排查 |
一句话总结:Android 的复杂推断、iOS 的一次性弹窗、macOS 的延迟授权、Windows/Linux 的"无权限",Kamera 全都在统一的六种状态模型里替你消化了——你只管写 UI 分支,相机权限从此一次搞定。
