【鸿蒙（openHarmony）自定义音频播放器的开发使用说明】

对鸿蒙（openHarmony）自定义音频播放器的开发进行一份详细、深入的说明。

这份说明将围绕您强调的状态机、错误处理、资源释放等核心要点展开，并提供代码示例和最佳实践。

鸿蒙 (ArkUI) 自定义音频播放器详细开发指南

在鸿蒙应用开发中，AVPlayer 是音视频播放的核心组件。其强大但稍显复杂，不遵循其状态机规则是导致各种错误（如常见的 5400102）的主要原因。

状态机管理：核心中的核心

AVPlayer 的状态机是其生命周期的精确描述。任何操作都必须在正确的状态下进行。

完整且正确的状态转换流程：

· idle (空闲态): 通过 createAVPlayer() 刚创建后的状态。此时播放器内部没有资源。

· initialized (初始化态): 在 idle 状态下，通过 url 属性设置音频源（fd://, http:// 等）后进入此状态。此时资源已识别，但未加载。

· prepared (准备态): 在 initialized 状态下，调用 prepare() 方法并成功后进入此状态。此时播放器已完成资源的解析、解码器初始化、音频轨道选择等准备工作，获取到了时长、轨道等信息。在此状态下可以开始播放。

· playing (播放态): 在 prepared 或 paused 状态下，调用 play() 方法后进入此状态。

· paused (暂停态): 在 playing 状态下，调用 pause() 方法后进入此状态。

· completed (完成态): 当音频自然播放到结尾时进入此状态。

· stopped (停止态): 在 prepared, playing, paused, completed 状态下，调用 stop() 方法后进入此状态。停止后可以重新调用 prepare() 来再次准备播放。

· released (释放态): 调用 release() 方法后进入此状态。此时所有占用的资源都已释放，AVPlayer 实例不可再使用。

· error (错误态): 在任何状态下发生错误都会进入此状态。需要调用 reset() 或 release() 来跳出。

关键代码示例：

typescript 复制代码

import media from '@ohos.multimedia.media';

// 1. 创建实例
let avPlayer: media.AVPlayer | null = null;
media.createAVPlayer().then((player: media.AVPlayer) => {
  avPlayer = player;
}).catch((err: BusinessError) => {
  console.error(`创建AVPlayer失败，错误码: ${err.code}, 错误信息: ${err.message}`);
});

// 2. 设置监听器，至关重要！
avPlayer.on('stateChange', (state: media.AVPlayerState) => {
  console.log(`当前状态: ${state}`);
  switch (state) {
    case 'idle':
      break;
    case 'initialized':
      // 状态变为initialized后，才能调用prepare
      avPlayer.prepare().then(() => {
        console.log('prepare成功');
      }).catch((err: BusinessError) => {
        // 错误处理
      });
      break;
    case 'prepared':
      let duration = avPlayer.duration; // 此时可以安全获取时长等信息
      break;
    case 'playing':
      break;
    case 'paused':
      break;
    case 'completed':
      // 处理播放完成
      break;
    case 'error':
      console.error(`进入错误态，需要处理`);
      break;
  }
});

// 3. 设置url，触发从idle -> initialized
avPlayer.url = 'https://example.com/your-audio-file.mp3'; // 或 'fd://...'

播放完成处理

当 stateChange 事件报告 completed 状态时，播放器已经停止。此时直接设置新的 url 是错误的。

正确做法：必须先用reset() 方法将播放器回退到 idle 状态，然后才能设置新的资源。

typescript 复制代码

// 在stateChange监听器中
case 'completed':
  console.log('播放完成');
  // 1. 重置到idle状态
  avPlayer.reset().then(() => {
    console.log('reset成功，回到idle状态');
    // 2. 设置新的URL，进入initialized状态
    avPlayer.url = 'https://example.com/another-audio.mp3';
    // 3. 再次prepare()，可以在这里调用，也可以在initialized状态的监听里自动调用
    avPlayer.prepare();
  }).catch((err: BusinessError) => {
    console.error(`reset失败: ${err.message}`);
  });
  break;

错误处理

全面的错误处理是保证应用健壮性的关键。

· 异步操作捕获：对所有返回 Promise 的方法使用 .catch()。

· 监听错误事件：除了 stateChange -> error，最好也监听专门的 error 事件。

typescript 复制代码

// 方式一：捕获异步Promise错误
avPlayer.prepare().then(() => {
  // ...
}).catch((err: BusinessError) => {
  console.error(`prepare异步操作失败: ${err.code}, ${err.message}`);
});

// 方式二：监听error事件
avPlayer.on('error', (err: BusinessError) => {
  console.error(`AVPlayer发生错误: ${err.code}, ${err.message}`);
  // 5400102错误通常在这里或stateChange->error时捕获
  // 可以根据错误码进行不同的UI提示或恢复逻辑
  if (err.code == 5400102) {
    promptAction.showToast({ message: '操作不当，请重启播放' });
    avPlayer.reset(); // 尝试重置恢复
  }
});

资源释放

在页面销毁（例如 aboutToAppear）或播放器不再使用时，必须释放资源，否则会导致内存泄漏。

typescript 复制代码

// 在Page的aboutToDisappear或自定义的销毁函数中
function cleanupAVPlayer() {
  if (avPlayer) {
    // 1. 取消所有监听器，防止内存泄漏
    avPlayer.off('stateChange');
    avPlayer.off('error');
    // ... 取消其他所有监听器

    // 2. 调用release()释放底层资源
    avPlayer.release().then(() => {
      console.log('AVPlayer释放成功');
      avPlayer = null; // 将引用置空
    }).catch((err: BusinessError) => {
      console.error(`release失败: ${err.message}`);
    });
  }
}

状态检查

在执行敏感操作（如 play, pause, seek）前，检查当前状态是否允许该操作，可以极大减少错误的发生。

typescript 复制代码

// 一个安全的播放/暂停切换函数
function togglePlayPause() {
  if (!avPlayer) {
    return;
  }

  // 获取当前状态
  let currentState = avPlayer.currentState;

  switch (currentState) {
    case 'prepared':
    case 'paused':
    case 'completed':
      // 这些状态下可以安全调用play
      avPlayer.play().catch((err) => {
        console.error(`play调用失败: ${err}`);
      });
      break;
    case 'playing':
      avPlayer.pause().catch((err) => {
        console.error(`pause调用失败: ${err}`);
      });
      break;
    case 'idle':
    case 'initialized':
      console.warn(`当前状态${currentState}下无法播放，请等待准备完成`);
      break;
    case 'error':
      console.warn('播放器处于错误状态，请先处理错误');
      break;
    default:
      console.warn(`未处理的状态: ${currentState}`);
  }
}

实现效果：

总结与最佳实践清单

监听状态机：始终注册 stateChange 事件监听器，并根据状态变化驱动你的UI和逻辑。
顺序操作：严格遵守 create -> set url -> prepare -> play 的顺序。不要在 idle 状态下调用 play。
完成重置：播放完成后（completed），必须先 reset() 才能设置新的资源。
全面捕错：对所有异步方法和 error 事件监听器进行错误捕获和处理。
释放资源：在组件生命周期结束时，调用 release() 并置空引用。
先问后做：在执行操作前，使用 currentState 检查当前状态是否允许该操作。
单一职责：尽量保证一个 AVPlayer 实例只处理一个媒体资源，避免复杂的资源切换逻辑。

通过严格遵循以上指南，你可以构建一个稳定、可靠且高效的鸿蒙自定义音频播放器，从而有效避免 5400102 等常见错误。

你的鼓励是我创作的动力，想了解更多内容请关注下方公共号！