HarmonyOS 6.1+ 新特性实战（12）：AVPlayer播放状态机与资源释放方案

cslgtdz

298人浏览 · 2026-08-30 22:16:20

cslgtdz · 2026-08-30 22:16:20 发布

播放器页面能播出第一帧并不代表生命周期正确。快速切换资源、拖动进度条后返回、错误状态继续调用play，都可能把AVPlayer推入不允许的状态。工程上应先约束命令，再把播放器事件归一化为页面快照。

方案面向HarmonyOS 6.1.1 Release SDK（API 24），系统Kit调用进入适配层，命令约束、状态归并和恢复策略进入可测试的业务层。范围包含状态与资源生命周期设计、失败恢复和验收合同，不包含业务内容生产、服务端协议改造以及特定厂商网页或媒体源的兼容承诺。

AVPlayer播放状态机与资源释放方案架构方案图

先画出播放器命令边界

AVPlayer的idle、initialized、prepared、playing、paused、completed、stopped、released不是普通枚举，而是API调用前置条件。方案用CommandGuard决定当前状态允许哪些命令：prepared可以play，playing可以pause与seek，error只允许reset或release。UI按钮从允许集合生成，减少无效点击。

状态数量不是越多越好。每个状态必须回答三个问题：当前允许哪些命令、收到迟到事件怎样处理、页面退出后是否还可以更新UI。下面的状态对象携带operationId，新的操作开始后，旧操作回调会被拒绝。

export enum PlayerState {
  IDLE = 'idle',
  INITIALIZED = 'initialized',
  PREPARED = 'prepared',
  PLAYING = 'playing',
  PAUSED = 'paused',
  COMPLETED = 'completed'
}

export interface PlayerSnapshot {
  state: PlayerState;
  progress: number;
  message: string;
  operationId: number;
  updatedAt: number;
}

export type PlayerEvent =
  | { type: 'START'; operationId: number }
  | { type: 'PROGRESS'; operationId: number; progress: number }
  | { type: 'SUCCESS'; operationId: number }
  | { type: 'FAIL'; operationId: number; message: string };

export function acceptEvent(
  snapshot: PlayerSnapshot,
  event: PlayerEvent
): boolean {
  return event.type === 'START' || event.operationId === snapshot.operationId;
}

设计对象	保存内容	不应该保存的内容
页面状态	可展示阶段、进度、错误摘要	系统对象和页面Context
适配器	Kit实例、监听注册、资源句柄	ArkUI组件引用
业务记录	operationId、版本、恢复点	未脱敏的敏感原始数据
诊断信息	阶段耗时、错误码、能力检测	Token、图片原始内容

事件监听必须早于资源设置

进度更新采用双通道：timeUpdate负责被动推进，用户拖动时设置seeking标记，seekDone后再解除。这样播放器回调不会在手指拖动过程中把滑块拉回旧位置。资源切换先reset，再设置新fdSrc；页面退出统一release并注销监听。

这套分层把系统事实和产品行为分开：Kit适配器负责获得事实，领域对象决定是否接受事件，页面只渲染快照。更换API版本或加入真机能力时，只需要替换适配器；状态归并和异常策略仍可在模拟器中重复验证。

进度条如何避免反向跳动

下面是主题专属的接入或核心算法代码。示例刻意保留资源创建、前置条件和清理逻辑，因为高频故障往往出现在成功调用之外。

import { media } from '@kit.MediaKit';

export class PlayerSession {
  private player?: media.AVPlayer;
  private released: boolean = false;

  async create(): Promise<void> {
    this.player = await media.createAVPlayer();
    this.player.on('stateChange', state => {
      AppStorage.setOrCreate('playerState', state);
    });
    this.player.on('timeUpdate', time => {
      AppStorage.setOrCreate('playerTime', time);
    });
    this.player.on('error', error => {
      AppStorage.setOrCreate('playerError', error.message);
    });
  }

  async play(): Promise<void> {
    if (this.released || !this.player) return;
    if (this.player.state === 'prepared' || this.player.state === 'paused') {
      await this.player.play();
    }
  }

  async release(): Promise<void> {
    if (this.released || !this.player) return;
    this.released = true;
    await this.player.release();
    this.player = undefined;
  }
}

代码迁入业务工程时，应把错误码转换为稳定的领域错误，不让页面直接判断系统错误字符串。对于异步回调，还要在写入状态前比较operationId或资源版本；仅检查组件是否存在，无法阻止旧任务污染新页面。

错误状态只允许重置

故障输入	状态变化	恢复动作
prepared前调用play	命令守卫拒绝	按钮保持禁用
seek回调迟到	比对资源版本	忽略旧资源位置
播放源损坏	进入error	仅保留重置和返回
页面销毁	执行release	不再接收进度事件

异常注入按钮用于稳定复现应用侧恢复路径。真实错误发生时，诊断记录同时保存错误码、权限结果、设备能力和用户可见状态；敏感原始数据不进入日志，截图只呈现与问题直接相关的结果。

页面退出时释放哪些对象

页面层不直接调用Kit，而是通过动作按钮驱动同一份状态模型。这样既能在系统能力可用时接真实适配器，也能在模拟器缺少硬件时验证错误页面、幂等逻辑和资源清理。

@Component
struct PlayerPanel {
  @State stateText: string = 'IDLE';
  @State progress: number = 0;
  @State logs: string[] = [];

  private append(message: string): void {
    const time = new Date().toLocaleTimeString();
    this.logs = [`${time}  ${message}`, ...this.logs].slice(0, 8);
  }

  private startDemo(): void {
    this.stateText = 'INITIALIZED';
    this.progress = 20;
    this.append('开始：AVPlayer播放状态机与资源释放');
  }

  private injectFailure(): void {
    this.stateText = 'COMPLETED';
    this.append('已注入可恢复故障');
  }

  build() {
    Column({ space: 12 }) {
      Text('AVPlayer播放状态机与资源释放').fontSize(24).fontWeight(FontWeight.Bold)
      Text(this.stateText).fontSize(18).fontColor('#2563EB')
      Progress({ value: this.progress, total: 100 }).width('100%')
      Row({ space: 12 }) {
        Button('开始实验').onClick(() => this.startDemo())
        Button('注入故障').onClick(() => this.injectFailure())
      }
      ForEach(this.logs, (item: string) => Text(item).fontSize(13))
    }.padding(20).width('100%')
  }
}

实施顺序从监听注册和资源设置开始，再完成播放命令守卫、拖动仲裁、资源版本隔离和统一释放。验收时随包放置十秒测试视频，依次覆盖准备、播放、暂停、拖动、播完和重新播放；随后在播放中返回首页并再次进入，检查旧声音和旧进度是否清除；最后用损坏文件验证可恢复错误态。

播放器还需要处理音频焦点和输出设备变化，但两类事件不应直接修改进度。焦点丢失可以把业务状态记为PAUSED_BY_SYSTEM，耳机断开时依据产品策略暂停；用户主动暂停则是PAUSED_BY_USER。二者分开后，焦点恢复只会恢复系统暂停的会话。资源切换时，旧资源的durationUpdate和seekDone都携带resourceVersion，版本不一致就丢弃。这样可以解释为何界面显示新标题，却突然跳回上一段视频的时间点。倍速、音量和进度命令分别等待对应完成事件，失败时回退到播放器真实值，避免控件展示一个引擎尚未接受的配置。进入后台时还要按业务类型决定暂停或继续，回到前台后先同步真实状态，再恢复按钮可用性。

验收记录至少包括SDK版本、模拟器系统版本、操作顺序、预期状态、实际状态和截图编号。快速点击、返回再进入、故障后重试和页面销毁是必测项；涉及资源的主题还要显示活动对象计数，涉及异步任务的主题要验证迟到结果不会改变当前页面。