系统能力:媒体、权限与后台任务
本篇要点:把“拍照换头像”和“后台听播客”两个需求做到审核能过、被拒也不崩,并说清权限、媒体、后台任务三者的联动关系。 前置文章:《网络与数据:HTTP、数据持久化与首选项》把数据通路搭好了,这一章要让数据从系统硬件那头进来,也从通知栏那头出去。
为什么需要它
一个真实的功能单:用户点头像,弹相册选图,选完裁一刀传上去;同时应用里加了播客模块,锁屏后要能继续听。
开发阶段两个功能都跑通了。上线前一周出问题。
头像这边,测试同事在设置里把相册权限关掉,再点头像,应用直接白屏。日志里只有一行 Permission denied。代码里没有任何分支处理“用户不给”这件事。
播客这边更隐蔽。开发机上一直插着充电线、亮着屏,播放正常。真机揣兜里走了两站地,音频在第 20 秒停了,通知栏什么都没有。
第三件事来自审核。首次提交被驳回,理由是权限申请超出功能所需——module.json5 里躺着六个权限,包括相册读写和通讯录,后两个是早期做分享功能时留下的,功能早删了,配置没删。
三个问题看着分属三个模块,实际是同一个认知缺口:系统能力不是一次 API 调用,是你、用户、系统三方的一次协商。 用户有权说不,系统有权在你不符合条件时收回资源,审核方有权问你为什么需要。
版本基线:HarmonyOS 6.0.0(API 20,2025 年 9 月 25 日 Release),DevEco Studio 6.0.0,截至 2026 年 11 月为多数在售机型的稳定线。abilityAccessCtrl 从 API 8 起可用,requestPermissionOnSetting(二次授权引导)从 API 12 起提供,backgroundTaskManager.startBackgroundRunning 的签名在 API 12 之后未再变动。权限清单以官方文档中心的应用权限管理分区为准。
核心概念
1. 能用系统控件,就不要申请权限
鸿蒙把一部分敏感操作做成了系统控件(System Picker):选照片、选文件、扫码,界面由系统绘制,应用拿到的是用户亲手选中的那一个结果,拿不到整个相册。
类比借书:申请权限是办一张能进书库的证,从此整个书库对你开放;系统控件是你报书名,管理员进去把那一本递给你。后者更容易被批准,因为它不给你翻其他书的可能。
反例:为了选一张头像去申请 ohos.permission.READ_IMAGEVIDEO。这个权限在审核侧属于高敏感项,理由必须写清“为什么不能只用系统选择器”。写不出来,就会被驳回,而功能本身一行代码都不用改。
结论很直接:PhotoViewPicker、DocumentViewPicker、扫码控件能覆盖的场景,一律不申请权限。这条判断比任何优化都省事。
2. 授权的三种状态,而不是两种
授权状态(Authorization State)不是“给”和“不给”两档,是三档:已授权、拒绝但可以再问、拒绝且不再询问。第三种状态下 requestPermissionsFromUser 不会再弹窗,直接返回拒绝。
图 6-1 相机权限的两次申请路径
如图 6-1 所示,区分第二档和第三档靠的是 dialogShownResults:false 说明这次压根没弹窗,用户之前已经选了不再询问,此时唯一的出路是 requestPermissionOnSetting 拉起设置引导。这个字段从 API 12 起才有,早期版本只能靠“连续两次返回拒绝”猜。
反例:把所有拒绝都当成同一种,每次都调 requestPermissionsFromUser。用户体验是点了没反应,第二次点还是没反应,第三次他卸载了。
3. 后台任务分三类,别用错
| 类型 | 能活多久 | 适用场景 | 前置条件 | 用户可见性 |
|---|---|---|---|---|
| 短时任务(Transient Task) | 约 3 分钟 | 退到后台后收尾:保存草稿、上传最后一张图 | 无需权限,运行时申请配额 | 不可见 |
| 长时任务(Continuous Task) | 持续,直到主动停止 | 音频播放、定位导航、大文件传输 | 声明 backgroundModes + KEEP_BACKGROUND_RUNNING,挂常驻通知 | 通知栏常驻,可被一键停止 |
| 延迟任务(Work Scheduler) | 满足条件时被拉起 | 充电时同步、闲时清理缓存 | WorkScheduler 配置触发条件 | 不可见 |
长时任务有一个容易被忽略的联动:它必须挂一条常驻通知。系统不让你在用户完全不知情的状态下长期占用 CPU 和网络,通知就是那个“知情”。反过来,通知被用户划掉,长时任务随之结束。
反例:为了让轮询接口在后台继续跑,套一个 AUDIO_PLAYBACK 的长时任务。运行是能跑,审核侧一旦发现“音频模式的应用没有音频输出”,驳回理由会写得很详细。
4. 通知不是装饰,是权限结果的一部分
通知(Notification)在这套模型里承担两件事:告诉用户“你的应用正在做什么”,以及给长时任务提供合法性凭据。发布通知本身不需要权限,但需要用户允许该应用发通知——首次要用 requestEnableNotification 申请,用户拒绝之后 publish 静默失败,不报错。
这一点和《网络与数据:HTTP、数据持久化与首选项》的 flush() 很像:调用了,返回成功,但什么也没发生。
动手实践
目标:把头像选图和播客后台播放做完,权限被拒时给出可操作的提示。
步骤 1:封装一个三态权限函数
// 前提:API 20;@kit.AbilityKit
import { abilityAccessCtrl, common, Permissions } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
export enum AuthState {
GRANTED,
DENIED, // 还能再弹一次
DENIED_FOREVER // 只能走设置引导
}
const atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager();
export async function ensurePermission(
ctx: common.UIAbilityContext, perm: Permissions): Promise<AuthState> {
const tokenId: number = ctx.applicationInfo.accessTokenId;
if (atManager.checkAccessTokenSync(tokenId, perm)
=== abilityAccessCtrl.GrantStatus.PERMISSION_GRANTED) {
return AuthState.GRANTED;
}
const res = await atManager.requestPermissionsFromUser(ctx, [perm]);
if (res.authResults[0] === 0) {
return AuthState.GRANTED;
}
const shown: boolean[] | undefined = res.dialogShownResults;
if (shown !== undefined && shown.length > 0 && shown[0] === false) {
return AuthState.DENIED_FOREVER;
}
return AuthState.DENIED;
}
export async function openSetting(ctx: common.UIAbilityContext,
perm: Permissions): Promise<boolean> {
try {
const states: Array<abilityAccessCtrl.GrantStatus> =
await atManager.requestPermissionOnSetting(ctx, [perm]);
return states[0] === abilityAccessCtrl.GrantStatus.PERMISSION_GRANTED;
} catch (e) {
console.error(`[perm] setting fail ${(e as BusinessError).code}`);
return false;
}
}运行结果:
[perm] CAMERA checkAccessTokenSync -> -1
[perm] requestPermissionsFromUser -> authResults: [-1], dialogShownResults: [true]
[perm] 用户再次点击 -> [-1], [false] → AuthState.DENIED_FOREVER
[perm] requestPermissionOnSetting -> 拉起"去设置"弹窗,返回 [0]checkAccessTokenSync 放在最前面,是为了避开没必要的弹窗:已经授权还去调申请接口,部分机型会再弹一次,用户会疑惑“我不是刚点过允许吗”。
步骤 2:用系统选择器选图,不要权限
// 前提:API 20;@kit.MediaLibraryKit + @kit.ImageKit + @kit.CoreFileKit
import { photoAccessHelper } from '@kit.MediaLibraryKit';
import { image } from '@kit.ImageKit';
import { fileIo as fs } from '@kit.CoreFileKit';
export class PickedImage {
uri: string;
width: number;
height: number;
constructor(uri: string, width: number, height: number) {
this.uri = uri;
this.width = width;
this.height = height;
}
}
export async function pickAvatar(): Promise<PickedImage | null> {
const picker = new photoAccessHelper.PhotoViewPicker();
const res = await picker.select({
MIMEType: photoAccessHelper.PhotoViewMIMETypes.IMAGE_TYPE,
maxSelectNumber: 1
});
if (res.photoUris.length === 0) {
return null; // 用户取消,不是错误
}
const uri: string = res.photoUris[0];
const file = fs.openSync(uri, fs.OpenMode.READ_ONLY);
try {
const source = image.createImageSource(file.fd);
const info = await source.getImageInfo();
source.release(); // 必须显式释放
return new PickedImage(uri, info.size.width, info.size.height);
} finally {
fs.closeSync(file);
}
}运行结果:
[picker] select -> 1 张,uri: file://media/Photo/12/IMG_1763/IMG_20261116_101500.jpg
[picker] getImageInfo -> 3024 x 4032, 4.2 MB
[picker] 用户点取消 -> photoUris.length = 0,返回 null,界面保持原头像拿到尺寸的意义在于:3024 × 4032 的图直接塞进 96vp 的头像框,内存里要占 48 MB。上传前按目标尺寸做一次压缩,是《性能优化:布局、长列表与帧率分析》性能那部分的伏笔。另外,这个 URI 是临时授权,进程重启后可能失效,要长期用必须复制进应用沙箱。
步骤 3:音频播放 + 长时任务 + 常驻通知
// 前提:API 20;@kit.MediaKit + @kit.BackgroundTasksKit + @kit.NotificationKit
import { media } from '@kit.MediaKit';
import { backgroundTaskManager } from '@kit.BackgroundTasksKit';
import { common, wantAgent, WantAgent } from '@kit.AbilityKit';
import { notificationManager } from '@kit.NotificationKit';
import { BusinessError } from '@kit.BasicServicesKit';
export class PodcastPlayer {
private player: media.AVPlayer | undefined;
private running: boolean = false;
async start(ctx: common.UIAbilityContext, url: string): Promise<void> {
this.player = await media.createAVPlayer();
this.player.on('stateChange', (state: string) => {
if (state === 'initialized') { this.player?.prepare(); }
if (state === 'prepared') { this.player?.play(); }
});
this.player.on('error', (err: BusinessError) => {
console.error(`[audio] ${err.code} ${err.message}`);
});
this.player.url = url; // 赋值即触发 initialized
await this.keepAlive(ctx);
}
private async keepAlive(ctx: common.UIAbilityContext): Promise<void> {
if (this.running) { return; }
const info: wantAgent.WantAgentInfo = {
wants: [{ bundleName: ctx.abilityInfo.bundleName, abilityName: 'EntryAbility' }],
actionType: wantAgent.OperationType.START_ABILITY,
requestCode: 0,
actionFlags: [wantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG]
};
const agent: WantAgent = await wantAgent.getWantAgent(info);
await backgroundTaskManager.startBackgroundRunning(
ctx, backgroundTaskManager.BackgroundMode.AUDIO_PLAYBACK, agent);
this.running = true;
await this.notify(ctx, '正在播放', '回到应用可继续收听');
}
private async notify(ctx: common.UIAbilityContext,
title: string, text: string): Promise<void> {
await notificationManager.requestEnableNotification(ctx);
const req: notificationManager.NotificationRequest = {
id: 1001,
content: {
notificationContentType: notificationManager.ContentType.NOTIFICATION_CONTENT_BASIC_TEXT,
normal: { title: title, text: text, additionalText: '轻点返回播放页' }
}
};
await notificationManager.publish(req);
}
}运行结果:
[audio] stateChange idle -> initialized
[audio] stateChange initialized -> prepared
[audio] stateChange prepared -> playing
[bg] startBackgroundRunning ok(通知栏出现常驻通知)
[bg] 锁屏 12 分钟后再解锁,进度从 03:12 走到 15:20,未中断如果 startBackgroundRunning 抛 9800005(长时任务数量超限)或 201(权限未声明),先回去看 module.json5,再看这台设备上有没有别的应用同时占着长时任务配额——配额按应用计,一个应用同时只能有一个同类型长时任务。
播放器销毁时还要配对调用 backgroundTaskManager.stopBackgroundRunning(ctx)。不调的表现不是崩溃,而是通知栏一直挂着“正在播放”,用户点回来发现没有声音,再点一次播放按钮,两个 AVPlayer 同时出声。长时任务在进程还活着的时候不会自己回收,这一条只能靠代码守。
步骤 4:配置写对,比代码写对更早挡住问题
// entry/src/main/module.json5 —— 节选
{
"module": {
"requestPermissions": [
{
"name": "ohos.permission.CAMERA",
"reason": "$string:reason_camera",
"usedScene": { "abilities": ["EntryAbility"], "when": "inuse" }
},
{
"name": "ohos.permission.KEEP_BACKGROUND_RUNNING"
}
],
"backgroundModes": ["audioPlayback"]
}
}运行结果:
# hvigor 构建通过;安装后首次点"拍照"
[perm] 系统弹窗文案:允许"示例笔记"使用相机?— 用于拍摄头像
# 注释掉 requestPermissions 中的 CAMERA 再运行
[perm] requestPermissionsFromUser -> err 12100001(参数错误:权限未在 module.json5 中声明)reason 会原样显示在系统弹窗里,写成“需要相机权限”和写成“用于拍摄头像”,用户点允许的比例差得很远。usedScene.when 填 inuse 表示仅前台使用,比 always 更容易通过审核。
常见误解
误解一:以为在 module.json5 里声明了就自动拥有权限。 权限分两种授予方式:system_grant 声明即生效,user_grant 必须运行时申请,用户点了允许才算。相机、麦克风、位置、通讯录都是后者。声明只解决“允许不允许你问”,不解决“用户答不答应”。
误解二:以为长时任务能让应用整体保活。 它保的是声明过的那一类能力。audioPlayback 只保证音频通路和它的回调活着,你的定时器、轮询、WebSocket 心跳照样在几分钟后被挂起。有人在长时任务里跑网络轮询,开发机上一切正常,因为连着调试器;真机上第二天就收到“数据不同步”的反馈。
误解三:以为选择器给的 URI 可以长期保存。 系统选择器授予的是临时读权限,重启应用后读取可能失败,报 13900002(文件不存在)或权限错误。要长期引用,得在拿到 URI 之后立刻用 fs.copyFile 复制进 context.filesDir,库里存沙箱路径,不存 file://media/...。
小结
- 系统能力是三方的协商:用户能否决,系统能收回,审核方能追问用途。代码里没有“用户拒绝”这条分支,功能就只完成了一半。
- 能用系统选择器(Picker)的场景一律不申请权限。少一个权限,审核少一轮,代码少一堆分支。
- 授权有三态。
dialogShownResults为false说明用户选了不再询问,此时只有requestPermissionOnSetting能救。 - 后台任务三类各有前置条件。长时任务必须声明
backgroundModes并挂常驻通知,通知被划掉任务就结束。 module.json5里的reason是给用户看的,不是给编译器看的。写成功能描述,通过率会不一样。
相关主题
到这里,一个应用该有的零件都齐了:界面、状态、路由、数据、系统能力。但能跑和跑得顺是两回事。《性能优化:布局、长列表与帧率分析》处理性能——列表滑到第 200 项开始掉帧、图片解码占满内存、冷启动三秒白屏。这一章里那张 3024 × 4032 的头像,会在《性能优化:布局、长列表与帧率分析》变成一个具体的内存数字。