组件：音频播放器

音频播放器组件用于播放音频文件，支持多种音频格式（如 MP3、WAV、AAC、OGG 等），提供了丰富的控制属性和事件回调，包括播放/暂停、音量调节、播放速度、循环播放、静音等。它适用于背景音乐、音效播放、播客、音频教学等场景。该组件基于 HTML5 <audio> 元素封装，与视频播放器功能类似但专用于音频播放。

典型使用场景：

  • 背景音乐（游戏、网站、应用）
  • 音效播放（点击反馈、通知提示）
  • 播客/有声读物（音频节目、故事讲述）
  • 语言学习（音频课程、听力练习）
  • 音乐播放器（在线音乐、本地音乐）

📌 继承自视图的成员速查

本组件继承自 视图 类，可直接使用以下属性和方法：

属性： ID、左边、顶边、右边、底边、宽度、高度、背景、背景颜色、背景图像、文本、文本颜色、字体、字体大小、字体粗细、行高、边框、边框圆角、边框宽度、光标样式、显示模式、透明度、外边距、外边距底、外边距左、外边距右、外边距顶、最大高度、最大宽度、最小高度、最小宽度、内边距、内边距底、内边距左、内边距右、内边距顶、定位、CLASS、InnerHTML、OuterHTML、内容水平对齐方式、首行缩进、可视、显示层级、内联样式、禁用

方法： 追加内联样式(样式文本)、置内联样式(名称,值)、取内联样式值(名称)、取Style对象()、添加事件(事件名称, 回调函数)、删除事件(事件名称, 回调函数)、获取焦点()、清除焦点()、添加样式类(类名称)、移除样式类(类名称)、取样式类列表()、取样式类()、执行单击()、取属性值(属性名)、取属性节点(属性名)、取布局参数()、取渲染宽度()、取渲染高度()、取渲染顶边()、取渲染左边()、左侧对齐到(目标组件,偏移量)、右侧对齐到(目标组件,偏移量)、顶边对齐到(目标组件,偏移量)、底边对齐到(目标组件,偏移量)、右侧对齐到左(目标组件, 偏移量)、左侧对齐到右(目标组件, 偏移量)、底边对齐到顶(目标组件, 偏移量)、顶边对齐到底(目标组件, 偏移量)、有指定属性(属性名)、有属性()、内容可编辑()、包含CSS类(类名)、取命名空间()、取下个节点()、取下个元素()、取节点名称()、取节点类型()、取父节点()、取父元素()、取上个节点()、取上个元素()、销毁()、删除属性(属性名)、删除属性节点(属性名)、置属性值(属性名, 属性值)、置属性节点(属性节点)、取标签名()、移动(左边 顶边, 宽度, 高度)、取原生对象()、置被单击回调(回调函数)、置被双击回调(回调函数)、置鼠标被进入回调(回调函数)、置鼠标被移出回调(回调函数)、置鼠标被移动回调(回调函数)、置鼠标被按下回调(回调函数)、置鼠标被抬起回调(回调函数)、置鼠标滚轮被滚动回调(回调函数)、置键盘被按下回调(回调函数)、置按键被抬起回调(回调函数)、置按键被压下回调(回调函数)、置被失去焦点回调(回调函数)、置被获得焦点回调(回调函数)

事件： 被单击(源对象,事件源)、被双击(源对象,事件源)、鼠标被进入(源对象,事件源)、鼠标被移出(源对象,事件源)、鼠标被移动(源对象,事件源)、鼠标被按下(源对象,事件源)、鼠标被抬起(源对象,事件源)、鼠标滚轮被滚动(源对象,事件源)、键盘被按下(源对象,事件源)、按键被抬起(源对象,事件源)、按键被压下(源对象,事件源)、被失去焦点(源对象,事件源)、被获得焦点(源对象,事件源)

💡 完整成员列表及详细说明请参考：视图 类

常用操作速查

操作属性/方法示例
设置音频源地址音频地址音频播放器1.音频地址 = "static/bgm.mp3"
设置自动播放自动播放音频播放器1.自动播放 = 真
设置循环播放循环播放音频播放器1.循环播放 = 真
设置静音静音音频播放器1.静音 = 真
设置音量（0~1）音量音频播放器1.音量 = 0.8
设置播放速度（0.5~2）播放速度音频播放器1.播放速度 = 1.5
跳转到指定播放位置（秒）播放位置音频播放器1.播放位置 = 30
开始播放开始播放()音频播放器1.开始播放()
暂停播放暂停()音频播放器1.暂停()
停止播放并重置停止播放()音频播放器1.停止播放()
监听播放完毕置音频播放完毕回调(回调)音频播放器1.置音频播放完毕回调((事件) => { ... })
监听播放错误置音频播放出错回调(回调)音频播放器1.置音频播放出错回调((事件) => { ... })
监听播放进度置音频播放进度被改变回调(回调)音频播放器1.置音频播放进度被改变回调((事件) => { ... })

样式美化参考

音频播放器的外观主要通过继承的视图属性进行调整：

  • 整体容器：通过 宽度、高度 设置播放器尺寸；背景颜色、边框（如 "1px solid #d9d9d9"）、边框圆角（建议 "8px"）美化播放器边框。
  • 控制栏：默认由浏览器提供原生控制栏，可通过 CSS 类或 禁用 属性控制是否显示。与视频播放器不同，音频播放器通常显示为较小的控制条。
  • 暗色背景：建议将播放器背景颜色设置为深色（如 "#2d2d2d"），以突出控制按钮。
  • 宽度自适应：音频播放器通常不需要很高的高度，建议高度设置为 48px ~ 56px。

CSS 美化示例（在项目 CSS 文件中定义）：

.my-audio-player {
    border-radius: 8px;
    background-color: #2d2d2d;
    padding: 4px 8px;
}
.my-audio-player::-webkit-media-controls {
    filter: brightness(0.9);
}

在代码中应用样式类：音频播放器1.添加样式类("my-audio-player")

基础示例

创建一个带有基本属性的音频播放器，加载本地音频文件，并设置事件监听。

变量 音频播放器1 = 创建 音频播放器()
音频播放器1.左边 = 50
音频播放器1.顶边 = 50
音频播放器1.宽度 = 400
音频播放器1.高度 = 48
音频播放器1.音频地址 = "static/demo.mp3"
音频播放器1.自动播放 = 假
音频播放器1.循环播放 = 假
音频播放器1.静音 = 假
音频播放器1.音量 = 0.8
音频播放器1.边框 = "1px solid #d9d9d9"
音频播放器1.边框圆角 = "8px"
音频播放器1.背景颜色 = "#2d2d2d"

' 设置事件回调
音频播放器1.置音频播放完毕回调((事件对象) => {
    弹出提示("音频播放完毕")
})

音频播放器1.置音频播放出错回调((事件对象) => {
    弹出提示("音频播放出错，请检查文件路径")
})

' 开始播放
音频播放器1.开始播放()

添加组件(音频播放器1)

综合示例：自定义音频播放器（音乐播放器）

本示例构建一个自定义音乐播放器，包含播放/暂停、进度条、音量控制、播放速度切换、循环模式切换等功能，并展示各种事件回调的使用。

' ========== 创建音频播放器 ==========
变量 音频播放器1 = 创建 音频播放器()
音频播放器1.左边 = 30
音频播放器1.顶边 = 30
音频播放器1.宽度 = 480
音频播放器1.高度 = 48
音频播放器1.音频地址 = "https://www.soundhelix.com/examples/mp3/SoundHelix-Song-1.mp3"
音频播放器1.自动播放 = 假
音频播放器1.循环播放 = 假
音频播放器1.静音 = 假
音频播放器1.音量 = 0.8
音频播放器1.播放速度 = 1
音频播放器1.边框 = "1px solid #d9d9d9"
音频播放器1.边框圆角 = "8px"
音频播放器1.背景颜色 = "#2d2d2d"
添加组件(音频播放器1)

' ========== 创建自定义控制栏 ==========
变量 控制栏 = 创建 弹性布局()
控制栏.方向 = "row"
控制栏.侧轴对齐 = "center"
控制栏.左边 = 30
控制栏.顶边 = 90
控制栏.宽度 = 480
控制栏.高度 = 36
控制栏.背景颜色 = "rgba(0,0,0,0.7)"
控制栏.边框圆角 = "0px 0px 8px 8px"
控制栏.内边距 = "0 12px"
控制栏.间距 = 6
添加组件(控制栏)

' 播放/暂停按钮
变量 播放按钮 = 创建 按钮()
播放按钮.文本 = "▶"
播放按钮.宽度 = 32
播放按钮.高度 = 28
播放按钮.背景颜色 = "transparent"
播放按钮.文本颜色 = "#ffffff"
播放按钮.字体大小 = "14px"
播放按钮.边框 = "none"
播放按钮.光标样式 = "pointer"
控制栏.添加组件(播放按钮)

' 当前时间标签
变量 当前时间标签 = 创建 标签()
当前时间标签.文本 = "00:00"
当前时间标签.字体大小 = "12px"
当前时间标签.文本颜色 = "#ffffff"
当前时间标签.宽度 = 40
控制栏.添加组件(当前时间标签)

' 进度条（使用滑块条模拟）
变量 进度条 = 创建 滑块条()
进度条.宽度 = 220
进度条.高度 = 4
进度条.最小值 = 0
进度条.最大值 = 100
进度条.步长 = 1
进度条.进度值 = 0
进度条.背景颜色 = "#555"
进度条.颜色 = "#1890ff"
控制栏.添加组件(进度条)

' 总时间标签
变量 总时间标签 = 创建 标签()
总时间标签.文本 = "00:00"
总时间标签.字体大小 = "12px"
总时间标签.文本颜色 = "#ffffff"
总时间标签.宽度 = 40
控制栏.添加组件(总时间标签)

' 音量控制
变量 音量按钮 = 创建 按钮()
音量按钮.文本 = "🔊"
音量按钮.宽度 = 26
音量按钮.高度 = 28
音量按钮.背景颜色 = "transparent"
音量按钮.文本颜色 = "#ffffff"
音量按钮.字体大小 = "12px"
音量按钮.边框 = "none"
音量按钮.光标样式 = "pointer"
控制栏.添加组件(音量按钮)

变量 音量滑块 = 创建 滑块条()
音量滑块.宽度 = 50
音量滑块.高度 = 4
音量滑块.最小值 = 0
音量滑块.最大值 = 100
音量滑块.步长 = 1
音量滑块.进度值 = 80
音量滑块.背景颜色 = "#555"
音量滑块.颜色 = "#1890ff"
控制栏.添加组件(音量滑块)

' 速度切换按钮
变量 速度按钮 = 创建 按钮()
速度按钮.文本 = "1.0x"
速度按钮.宽度 = 36
速度按钮.高度 = 28
速度按钮.背景颜色 = "transparent"
速度按钮.文本颜色 = "#ffffff"
速度按钮.字体大小 = "11px"
速度按钮.边框 = "none"
速度按钮.光标样式 = "pointer"
控制栏.添加组件(速度按钮)

' 循环模式按钮
变量 循环按钮 = 创建 按钮()
循环按钮.文本 = "🔁"
循环按钮.宽度 = 28
循环按钮.高度 = 28
循环按钮.背景颜色 = "transparent"
循环按钮.文本颜色 = "#888"
循环按钮.字体大小 = "14px"
循环按钮.边框 = "none"
循环按钮.光标样式 = "pointer"
控制栏.添加组件(循环按钮)

' ========== 歌曲标题标签 ==========
变量 标题标签 = 创建 标签()
标题标签.左边 = 30
标题标签.顶边 = 65
标题标签.文本 = "🎵 当前播放：SoundHelix 示例歌曲"
标题标签.字体大小 = "14px"
标题标签.文本颜色 = "#333"
添加组件(标题标签)

' ========== 辅助函数：时间格式化 ==========
函数 格式化时间(秒数)
    变量 分钟 = 向下取整(秒数 / 60)
    变量 秒 = 向下取整(秒数 - 分钟 * 60)
    变量 分钟文本 = 分钟 < 10 ? "0" + 分钟 : "" + 分钟
    变量 秒文本 = 秒 < 10 ? "0" + 秒 : "" + 秒
    返回 分钟文本 + ":" + 秒文本
结束 函数

' ========== 事件绑定 ==========
' 1. 音频加载完成后获取总时长
音频播放器1.置音频被加载回调((事件对象) => {
    总时间标签.文本 = 格式化时间(音频播放器1.取属性值("duration"))
    调试输出("音频加载完成，总时长：" + 总时间标签.文本)
})

' 2. 播放进度更新
音频播放器1.置音频播放进度被改变回调((事件对象) => {
    变量 当前时间 = 音频播放器1.播放位置
    变量 总时长 = 到数值(音频播放器1.取属性值("duration"))
    当前时间标签.文本 = 格式化时间(当前时间)
    如果(总时长 > 0)
        进度条.进度值 = (当前时间 / 总时长) * 100
    结束 如果
})

' 3. 播放完毕
音频播放器1.置音频播放完毕回调((事件对象) => {
    播放按钮.文本 = "▶"
    ' 如果循环模式开启，自动重新播放
    如果(循环按钮.文本 == "🔁" 且 循环按钮.文本颜色 == "#1890ff")
        音频播放器1.开始播放()
        播放按钮.文本 = "⏸"
    否则
        弹出提示("音频播放完毕")
    结束 如果
})

' 4. 播放错误
音频播放器1.置音频播放出错回调((事件对象) => {
    弹出提示("音频播放出错，请检查音频文件")
})

' ========== 控制栏事件 ==========
' 播放/暂停
播放按钮.置被单击回调((源对象, 事件对象) => {
    如果(播放按钮.文本 == "▶")
        音频播放器1.开始播放()
        播放按钮.文本 = "⏸"
    否则
        音频播放器1.暂停()
        播放按钮.文本 = "▶"
    结束 如果
})

' 进度条拖动（用户手动跳转）
进度条.置滑块位置被改变回调((源对象, 当前值) => {
    变量 总时长 = 到数值(音频播放器1.取属性值("duration"))
    如果(总时长 > 0)
        音频播放器1.播放位置 = (当前值 / 100) * 总时长
    结束 如果
})

' 音量控制
音量滑块.置滑块位置被改变回调((源对象, 当前值) => {
    音频播放器1.音量 = 当前值 / 100
    如果(当前值 == 0)
        音量按钮.文本 = "🔇"
    否则 如果(当前值 < 50)
        音量按钮.文本 = "🔉"
    否则
        音量按钮.文本 = "🔊"
    结束 如果
})

' 音量按钮静音切换
音量按钮.置被单击回调((源对象, 事件对象) => {
    变量 当前音量 = 音频播放器1.音量
    如果(当前音量 > 0)
        音频播放器1.静音 = 真
        音量滑块.进度值 = 0
        音量按钮.文本 = "🔇"
    否则
        音频播放器1.静音 = 假
        音频播放器1.音量 = 0.8
        音量滑块.进度值 = 80
        音量按钮.文本 = "🔊"
    结束 如果
})

' 速度切换（循环切换）
变量 速度列表 = [0.5, 0.75, 1.0, 1.25, 1.5, 2.0]
变量 速度索引 = 2  ' 默认1.0x
速度按钮.置被单击回调((源对象, 事件对象) => {
    速度索引 = (速度索引 + 1) % 取数组成员数(速度列表)
    变量 新速度 = 速度列表[速度索引]
    音频播放器1.播放速度 = 新速度
    速度按钮.文本 = 新速度 + "x"
})

' 循环模式切换
循环按钮.置被单击回调((源对象, 事件对象) => {
    如果(循环按钮.文本颜色 == "#888")
        循环按钮.文本颜色 = "#1890ff"
        音频播放器1.循环播放 = 真
        弹出提示("循环模式已开启")
    否则
        循环按钮.文本颜色 = "#888"
        音频播放器1.循环播放 = 假
        弹出提示("循环模式已关闭")
    结束 如果
})

属性详解

音频地址

  • 类型： 文本型
  • 说明： 设置或获取音频文件的 URL 地址。支持相对路径、绝对路径和网络 URL。设置后会自动加载音频元数据（但不一定会开始播放）。

自动播放

  • 类型： 逻辑型
  • 说明： 设置或获取是否在加载完成后自动开始播放。默认为 假。注意： 部分浏览器（尤其是移动端）可能会限制自动播放策略，需要用户交互后才能播放。

循环播放

  • 类型： 逻辑型
  • 说明： 设置或获取是否在音频播放完毕后自动重新开始播放。默认为 假。

静音

  • 类型： 逻辑型
  • 说明： 设置或获取是否将音频静音。默认为 假。在自动播放受限时，设置静音可以绕过部分浏览器的自动播放限制。

播放位置

  • 类型： 数值型
  • 说明： 设置或获取当前音频的播放位置（秒）。可用于跳转或获取当前进度。设置此属性会跳转到指定时间点。

音量

  • 类型： 数值型
  • 说明： 设置或获取当前音量，取值范围 0（静音）到 1（最大音量），默认 1。

播放速度

  • 类型： 数值型
  • 说明： 设置或获取播放速度倍率，常用取值范围 0.5 到 2.0，默认 1.0。支持的值范围由浏览器决定。

函数详解

开始播放()

  • 功能： 开始或恢复音频播放。如果音频已处于播放状态，则无效果。
  • 返回值： 无。
  • 示例： 音频播放器1.开始播放()

暂停()

  • 功能： 暂停音频播放。如果音频已暂停，则无效果。
  • 返回值： 无。
  • 示例： 音频播放器1.暂停()

停止播放()

  • 功能： 停止音频播放，并将播放位置重置到开头。
  • 返回值： 无。
  • 示例： 音频播放器1.停止播放()

置音频被加载回调(回调函数)

  • 功能： 设置音频元数据加载完成时的回调函数。
  • 参数： 回调函数，格式为 (事件对象) => { ... }。
  • 返回值： 无。

置音频播放完毕回调(回调函数)

  • 功能： 设置音频播放完毕时的回调函数。
  • 参数： 回调函数，格式为 (事件对象) => { ... }。
  • 返回值： 无。

置音频播放出错回调(回调函数)

  • 功能： 设置音频播放出错时的回调函数。
  • 参数： 回调函数，格式为 (事件对象) => { ... }。
  • 返回值： 无。

置音频被暂停回调(回调函数)

  • 功能： 设置音频暂停时的回调函数。
  • 参数： 回调函数，格式为 (事件对象) => { ... }。
  • 返回值： 无。

置音频开始被播放回调(回调函数)

  • 功能： 设置音频开始播放时的回调函数。
  • 参数： 回调函数，格式为 (事件对象) => { ... }。
  • 返回值： 无。

置音频播放进度被改变回调(回调函数)

  • 功能： 设置音频播放进度改变时的回调函数（在播放过程中持续触发）。
  • 参数： 回调函数，格式为 (事件对象) => { ... }。
  • 返回值： 无。

置音频音量被改变回调(回调函数)

  • 功能： 设置音量改变时的回调函数。
  • 参数： 回调函数，格式为 (事件对象) => { ... }。
  • 返回值： 无。

置音频播放速度被改变回调(回调函数)

  • 功能： 设置播放速度改变时的回调函数。
  • 参数： 回调函数，格式为 (事件对象) => { ... }。
  • 返回值： 无。

事件说明

以下事件与对应的回调函数等效，适用于设计文件（.spldg）中定义的组件：

事件对应回调函数触发时机
音频被加载(事件对象)置音频被加载回调音频元数据加载完成
音频播放完毕(事件对象)置音频播放完毕回调音频播放到结尾
音频播放出错(事件对象)置音频播放出错回调播放过程中发生错误
音频被暂停(事件对象)置音频被暂停回调音频被暂停
音频开始被播放(事件对象)置音频开始被播放回调音频开始播放
音频播放进度被改变(事件对象)置音频播放进度被改变回调播放进度变化
音频音量被改变(事件对象)置音频音量被改变回调音量变化
音频播放速度被改变(事件对象)置音频播放速度被改变回调播放速度变化

⚠️ 注意事项

  1. 音频格式兼容性：不同浏览器支持的音频格式不同，建议使用 MP3 格式以获得最佳兼容性。
  2. 自动播放策略：大多数现代浏览器（尤其是移动端）要求用户在点击播放前不能自动播放有声音的音频。若需自动播放，建议设置 静音 = 真。
  3. 跨域资源：如果音频地址是跨域的，服务器需要配置 CORS 头，否则可能无法正常播放。
  4. 播放位置精度：播放位置 属性可设置任意数值，但实际跳转精度取决于音频编码和浏览器实现。
  5. 事件回调参数：所有音频事件回调都返回一个 事件对象 参数，其中包含事件的详细信息（如时间戳、错误代码等），可通过 取属性值 获取具体字段。
  6. 原生控制栏：默认音频播放器会显示浏览器原生控制栏，如需隐藏可设置 禁用 = 真，但会同时禁用交互。
  7. 音频与视频的区别：音频播放器没有画面，适合背景播放；视频播放器有画面，适合展示视频内容。两者属性和方法基本相同，但音频播放器的高度通常较小。
  8. 资源释放：在页面关闭或组件销毁时，音频播放器会自动释放资源，无需手动处理。
  9. 静音与音量：设置 静音 = 真 会将音量强制设为 0，且 音量 属性会被覆盖。取消静音时，音量恢复之前的值。
  10. 取属性值("duration")：音频总时长可通过 取属性值("duration") 获取，但需要在 音频被加载 事件触发后才能获取到有效值。

相关文档

  • 文档框架基础类_视图 —— 视图类提供的所有通用属性和方法
  • 文档媒体类组件_视频播放器 —— 视频播放组件
  • 文档媒体类组件_录音机 —— 音频录制组件
  • 文档轻语言网站：轻语言语法速查 —— 拉姆达表达式、条件判断等
  • 文档综合演示：自定义音乐播放器 —— 实际应用示例