在 HarmonyOS（鸿蒙）应用开发中，“语音朗读” 是高频交互需求 —— 比如背单词应用的单词发音、工具类应用的文本转语音、翻译类应用的译文朗读等。鸿蒙官方提供的AVPlayer（媒体播放管理类）是处理音频 / 视频播放的核心 API，支持网络音频、本地音频等多种资源类型，无需第三方播放器即可快速实现音频播放能力。本文将以 “有道词典网络语音朗读” 为例，详解如何使用AVPlayer实现网络音频的加载、播放与资源管理。

一、核心概念与播放流程

1. 什么是 AVPlayer？

AVPlayer是鸿蒙@ohos.multimedia.media模块下的媒体播放管理类，专为音频 / 视频播放设计，提供了从 “资源加载→参数配置→播放控制→资源销毁” 的全流程能力：

• 支持网络音频（HTTP/HTTPS）、本地文件、Asset 资源等多种播放源；
• 提供播放状态监听、音量调节、倍速播放、循环播放等核心功能；
• 遵循 “创建→初始化→准备→播放→销毁” 的生命周期，资源管理更规范。

2. AVPlayer 播放全流程（必掌握）

阶段	核心操作
创建实例	通过createAVPlayer()创建 AVPlayer 实例
设置播放资源	通过avPlayer.url指定音频资源地址（网络 URL / 本地路径）
状态监听	监听stateChange事件，处理 “initialized（初始化）”“prepared（准备就绪）” 等状态
准备播放	初始化完成后调用prepare()，加载并解析音频资源
播放控制	准备就绪后调用play()播放，支持pause()（暂停）、stop()（停止）等操作
资源销毁	页面 / 组件销毁时调用release()释放资源，避免内存泄露

二、实战：实现有道词典单词朗读功能

本文以 “英文单词朗读” 为例，使用有道词典开放的网络语音接口（https://dict.youdao.com/dictvoice?type=1&audio=单词），通过AVPlayer实现音频播放，完整代码 + 解析如下。

第一步：前置准备（导入依赖）

首先在页面 / 组件文件中导入AVPlayer相关模块和上下文工具：

typescript

运行

// 导入媒体播放核心模块
import media from '@ohos.multimedia.media';
// 导入上下文获取工具（若需本地音频，上下文是必要参数）
import { getContext } from '@kit.ArkUI';

第二步：完整代码实现

typescript

运行

@Entry
@Component
struct WordPronunciationPage {
  // 要朗读的英文单词（示例：hello）
  @State en: string = 'hello';
  // 声明AVPlayer实例，可选类型避免初始化前报错
  avPlayer?: media.AVPlayer;

  // 页面即将显示时初始化AVPlayer并加载音频
  async aboutToAppear() {
    try {
      // 1. 创建AVPlayer实例（异步方法，必须await）
      const avPlayer = await media.createAVPlayer();
      this.avPlayer = avPlayer;

      // 2. 监听播放状态变化（核心：驱动播放流程）
      avPlayer.on('stateChange', (state: string) => {
        console.log('AVPlayer状态变化：', state);
        switch (state) {
          // 状态1：initialized（初始化完成）- 音频资源已设置，可准备播放
          case media.AVPlayerState.INITIALIZED:
            avPlayer.prepare(); // 准备音频资源（解析、加载）
            break;
          // 状态2：prepared（准备就绪）- 音频资源加载完成，可播放
          case media.AVPlayerState.PREPARED:
            avPlayer.loop = true; // 设置循环播放（可选，根据需求关闭）
            avPlayer.play(); // 开始播放音频
            break;
          // 可选：处理其他状态（如播放完成、出错）
          case media.AVPlayerState.COMPLETED:
            console.log('音频播放完成');
            break;
          case media.AVPlayerState.ERROR:
            console.error('音频播放出错');
            break;
        }
      });

      // 3. 设置网络音频资源（有道词典语音接口）
      // 注意：需对单词进行URL编码，避免特殊字符（如空格、撇号）导致地址无效
      const encodedWord = encodeURIComponent(this.en);
      avPlayer.url = `https://dict.youdao.com/dictvoice?type=1&audio=${encodedWord}`;

    } catch (error) {
      console.error('AVPlayer初始化失败：', error);
    }
  }

  // 页面即将销毁时释放资源（关键：避免内存泄露）
  aboutToDisappear(): void {
    if (this.avPlayer) {
      this.avPlayer.stop(); // 停止播放
      this.avPlayer.release(); // 释放AVPlayer所有资源
      this.avPlayer = undefined; // 清空实例，避免野指针
    }
  }

  build() {
    Column({ space: 20 }) {
      Text(`当前朗读单词：${this.en}`)
        .fontSize(20)
        .fontWeight(600);
      
      // 可选：手动控制播放/暂停按钮
      Button('重新朗读')
        .onClick(() => {
          if (this.avPlayer) {
            // 暂停后重新播放（若已播放完成/暂停）
            this.avPlayer.stop(); // 先停止
            this.avPlayer.prepare(); // 重新准备
          }
        });
    }
    .padding(40)
    .height('100%')
    .width('100%')
    .justifyContent(FlexAlign.Center);
  }
}

核心代码解析

1. 创建 AVPlayer 实例

typescript

运行

const avPlayer = await media.createAVPlayer();

• createAVPlayer()是异步方法，必须使用await等待实例创建完成，否则后续操作会报错；
• 建议包裹try/catch捕获初始化异常（如设备不支持音频播放、媒体服务异常）。

2. 监听播放状态（核心驱动）

typescript

运行

avPlayer.on('stateChange', (state: string) => { ... });

• stateChange是 AVPlayer 的核心事件，所有播放流程都依赖状态变化驱动：
  • INITIALIZED：设置url后触发，代表音频资源地址已配置，可调用prepare()加载资源；
  • PREPARED：prepare()执行完成后触发，代表音频资源解析、加载完成，可调用play()播放；
• 推荐使用media.AVPlayerState枚举值（如media.AVPlayerState.INITIALIZED）而非硬编码字符串，提升代码健壮性。

3. 设置网络音频 URL

typescript

运行

const encodedWord = encodeURIComponent(this.en);
avPlayer.url = `https://dict.youdao.com/dictvoice?type=1&audio=${encodedWord}`;

• 关键细节：使用encodeURIComponent()对单词进行 URL 编码，处理包含空格、撇号的单词（如don't、go away），避免 URL 无效；
• 有道词典语音接口说明：type=1代表美式发音，type=2代表英式发音，可根据需求调整。

4. 资源销毁（避免内存泄露）

typescript

运行

aboutToDisappear(): void {
  if (this.avPlayer) {
    this.avPlayer.stop();
    this.avPlayer.release();
    this.avPlayer = undefined;
  }
}

• aboutToDisappear是组件销毁的生命周期钩子，必须在此释放 AVPlayer 资源；
• release()会释放音频解码器、网络连接等所有资源，是避免内存泄露的关键；
• 先stop()再release()，确保播放停止后再释放资源，避免异常。

三、关键避坑指南

1. 网络音频播放失败：URL 编码问题

未编码的特殊字符（如空格、中文、撇号）会导致 URL 无效，播放状态直接进入ERROR。解决：

typescript

运行

// 错误示例：单词含撇号，URL无效
avPlayer.url = `https://dict.youdao.com/dictvoice?type=1&audio=don't`;

// 正确示例：编码后URL有效
const encodedWord = encodeURIComponent("don't");
avPlayer.url = `https://dict.youdao.com/dictvoice?type=1&audio=${encodedWord}`;

2. 状态监听缺失：播放流程中断

若未监听stateChange或未在INITIALIZED状态调用prepare()，音频会一直处于初始化状态，无法播放。解决：

• 必须监听stateChange事件；
• 严格遵循 “INITIALIZED→prepare ()→PREPARED→play ()” 的流程。

3. 资源未释放：内存泄露 / 音频卡顿

页面销毁后未调用release()，会导致 AVPlayer 实例常驻内存，多次进入页面后出现音频卡顿、应用崩溃。解决：

• 务必在aboutToDisappear中释放资源；
• 释放后清空实例（this.avPlayer = undefined），避免后续误操作。

4. 异步操作未 await：实例未创建完成

typescript

运行

// 错误示例：未await，avPlayer为Promise对象
const avPlayer = media.createAVPlayer(); 
avPlayer.url = 'xxx'; // 报错：Promise没有url属性

// 正确示例：await等待实例创建
const avPlayer = await media.createAVPlayer();

5. 网络权限问题：无法访问网络音频

若应用未配置网络权限，会导致网络音频加载失败。需在module.json5中添加网络权限：

json

{
  "module": {
    "requestPermissions": [
      {
        "name": "ohos.permission.INTERNET",
        "reason": "需要网络权限播放在线音频",
        "usedScene": {
          "abilities": [".MainAbility"],
          "when": "always"
        }
      }
    ]
  }
}

四、扩展优化建议

1. 手动控制播放 / 暂停

添加播放 / 暂停按钮，增强交互性：

typescript

运行

Button(this.isPlaying ? '暂停' : '播放')
  .onClick(() => {
    if (this.avPlayer) {
      if (this.isPlaying) {
        this.avPlayer.pause();
      } else {
        this.avPlayer.play();
      }
      this.isPlaying = !this.isPlaying;
    }
  });

2. 音量调节

通过volume属性调整播放音量（范围 0.0~1.0）：

typescript

运行

// 设置音量为50%
this.avPlayer.volume = 0.5;

3. 倍速播放

通过speed属性设置播放倍速（支持 0.5~2.0 倍）：

typescript

运行

// 1.5倍速播放
this.avPlayer.speed = 1.5;

4. 错误监听与用户提示

添加错误监听，给出友好的用户提示：

typescript

运行

avPlayer.on('error', (error: media.AVPlayerError) => {
  console.error('音频播放错误：', error);
  promptAction.showToast({ message: '朗读失败，请检查网络或单词拼写' });
});

5. 本地音频播放

若需播放本地音频（如 Asset 目录下的音频文件），只需修改url：

typescript

运行

// 播放Asset目录下的audio/hello.mp3
avPlayer.url = 'internal://app/assets/audio/hello.mp3';

五、总结

本文基于鸿蒙AVPlayer实现了网络音频（有道词典语音）的朗读功能，核心要点可总结为：

1. 流程规范：严格遵循 “创建实例→设置 URL→监听状态→prepare→play→释放资源” 的播放流程，状态监听是核心；
2. 细节处理：网络音频 URL 需编码，特殊字符会导致播放失败；
3. 资源管理：组件销毁时必须调用release()释放资源，避免内存泄露；
4. 权限配置：播放网络音频需配置INTERNET权限，否则无法访问网络资源。

AVPlayer不仅能实现音频朗读，还能支持视频播放、本地媒体文件播放等场景，掌握其核心流程和避坑要点，能高效解决鸿蒙应用中的媒体播放需求。