Skip to content

系统能力:媒体、权限与后台任务 ​

本篇要点:把“拍照换头像”和“后台听播客”两个需求做到审核能过、被拒也不崩,并说清权限、媒体、后台任务三者的联动关系。 前置文章:《网络与数据: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:封装一个三态权限函数 ​

ts
// 前提: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:用系统选择器选图,不要权限 ​

ts
// 前提: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:音频播放 + 长时任务 + 常驻通知 ​

ts
// 前提: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:配置写对,比代码写对更早挡住问题 ​

json5
// 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 的头像,会在《性能优化:布局、长列表与帧率分析》变成一个具体的内存数字。