音频播放组件

audio 组件是 Uniapp 中用于播放音频文件的基础组件，支持多种平台。该组件可以实现音频的播放、暂停、循环、进度更新等操作，并提供了一些事件用于音频状态的监听。audio 组件主要用于简单的音频播放场景，如背景音乐、音效播放等。

1. 什么是 audio 组件？

audio 组件用于在页面中嵌入音频播放器，支持播放本地或网络音频文件。它可以展示音频封面、音频名称、作者等信息，并且提供了默认的控件用于控制播放行为。此外，开发者可以通过监听音频的播放、暂停、结束等事件，实现自定义交互。

使用场景

• 背景音乐播放：在页面中播放背景音乐。
• 音频教程播放：嵌入音频播放组件，用于播放学习教程。
• 播客或有声书播放：提供音频内容，如播客、有声书等。
• 音效播放：用于播放短时音效，如按钮点击、提醒声音等。

2. audio 组件的常用属性

audio 组件提供了多个属性，用于控制音频的播放、循环、控件展示等。以下是常用属性的详细说明及使用示例。

属性名	类型	默认值	说明
src	String	无	要播放的音频资源地址，可以是本地路径或网络路径
loop	Boolean	false	是否循环播放
controls	Boolean	false	是否显示默认控件
poster	String	无	音频封面图片地址，需 controls 为 true 时才有效
name	String	未知音频	音频名称，需 controls 为 true 时才有效
author	String	未知作者	音频作者，需 controls 为 true 时才有效
@error	EventHandle	无	当发生错误时触发该事件
@play	EventHandle	无	音频开始或继续播放时触发
@pause	EventHandle	无	音频暂停播放时触发
@timeupdate	EventHandle	无	播放进度变化时触发该事件，返回当前时间和总时长
@ended	EventHandle	无	音频播放结束时触发

2.1 音频资源地址 src

• 说明：指定要播放的音频文件地址，可以是本地文件或网络音频资源。
• 类型：String
• 默认值：无

<template>
  <view>
    <audio :src="audioSrc" controls />
  </view>
</template>

<script setup>
const audioSrc = 'https://web-ext-storage.dcloud.net.cn/uni-app/ForElise.mp3';
</script>

2.2 循环播放 loop

• 说明：该属性控制音频是否循环播放。
• 类型：Boolean
• 默认值：false

<template>
  <view>
    <audio :src="audioSrc" :loop="true" controls />
  </view>
</template>

<script setup>
const audioSrc = 'https://web-ext-storage.dcloud.net.cn/uni-app/ForElise.mp3';
</script>

2.3 显示控件 controls

• 说明：该属性控制是否显示默认音频播放器控件，包括播放、暂停按钮以及进度条等。
• 类型：Boolean
• 默认值：false

<template>
  <view>
    <audio :src="audioSrc" :controls="true" />
  </view>
</template>

<script setup>
const audioSrc = 'https://web-ext-storage.dcloud.net.cn/uni-app/ForElise.mp3';
</script>

2.4 音频封面 poster

• 说明：指定音频控件上展示的封面图片地址，只有当 controls 属性为 true 时才生效。
• 类型：String
• 默认值：无

<template>
  <view>
    <audio :src="audioSrc" :controls="true" :poster="posterSrc" />
  </view>
</template>

<script setup>
const audioSrc = 'https://web-ext-storage.dcloud.net.cn/uni-app/ForElise.mp3';
const posterSrc = 'https://qiniu-web-assets.dcloud.net.cn/unidoc/zh/music-a.png';
</script>

2.5 音频播放事件 @play

• 说明：当音频开始或继续播放时触发该事件，可以用于监听音频播放状态。
• 类型：EventHandle

<template>
  <view>
    <audio :src="audioSrc" :controls="true" @play="onPlay" />
  </view>
</template>

<script setup>
const audioSrc = 'https://web-ext-storage.dcloud.net.cn/uni-app/ForElise.mp3';

const onPlay = () => {
  console.log('音频开始播放');
};
</script>

3. 音频播放控件与事件监听

以下案例展示了如何使用 audio 组件，结合播放控件、音频封面、播放状态监听等功能，实现基础的音频播放效果。

<template>
  <view>
    <audio
      :src="currentAudio.src"
      :controls="true"
      :poster="currentAudio.poster"
      :name="currentAudio.name"
      :author="currentAudio.author"
      @play="handlePlay"
      @pause="handlePause"
      @timeupdate="handleTimeUpdate"
      @ended="handleEnded"
    />
  </view>
</template>

<script setup>
import { ref } from 'vue';

const currentAudio = ref({
  src: 'https://web-ext-storage.dcloud.net.cn/uni-app/ForElise.mp3',
  poster: 'https://qiniu-web-assets.dcloud.net.cn/unidoc/zh/music-a.png',
  name: '致爱丽丝',
  author: '贝多芬',
});

const handlePlay = () => {
  console.log('音频开始播放');
};

const handlePause = () => {
  console.log('音频暂停播放');
};

const handleTimeUpdate = (event) => {
  const { currentTime, duration } = event.detail;
  console.log(`当前时间: ${currentTime} / 总时长: ${duration}`);
};

const handleEnded = () => {
  console.log('音频播放结束');
};
</script>

<style scoped>
/* 添加一些基础样式 */
audio {
  width: 100%;
  height: 50px;
}
</style>