Audio

带封面与律动可视化条的音频播放器。

最后更新 2026-10-25 19:27:08

说明

以卡片形式呈现封面、标题、艺人与波形可视化条。Src 指定音频源，Title / Artist / Cover 填充信息，Visualize 控制律动条动画，Loop / Muted / Volume 控制播放。封面缺失或加载失败自动回落音乐图标；播放/暂停、拖动进度与纵向音量弹层均由内置控制条提供。

常见能力：

封面 + 标题 + 艺人信息卡
播放律动可视化条
拖动进度与纵向音量弹层
循环 / 静音切换
Play / Pause / Seek / ToggleMute 等公开方法与事件回调
封面失败回落音乐图标

用法

<Audio Src="/media/song.mp3" Title="示例曲目" Artist="Known"
       Cover="/media/cover.jpg" Loop="true"
       OnPlay="OnPlay" OnEnded="OnEnded" OnError="OnError" />

API 参数

参数	类型	默认值	说明
`Artist`	`string`	`null`	艺术家 / 副标题。
`AutoPlay`	`bool`	`false`	自动播放（多数浏览器需用户手势或 Muted 才允许）。
`Caption`	`string`	`null`	底部说明文字。
`Cover`	`string`	`null`	封面图地址；为空或加载失败时显示音符图标。
`FallbackText`	`string`	`"音频加载失败"`	加载失败占位文案。
`Loop`	`bool`	`false`	是否循环播放（可在控制条上运行时切换）。
`Muted`	`bool`	`false`	初始静音。
`OnEnded`	`EventCallback`	—	事件播放结束回调。
`OnError`	`EventCallback<int>`	—	事件出错回调，参数为 HTMLMediaElement error.code。
`OnPause`	`EventCallback`	—	事件暂停回调。
`OnPlay`	`EventCallback`	—	事件开始播放回调。
`Preload`	`string`	`"metadata"`	预加载策略：none / metadata（默认）/ auto。
`Src`	`string`	`null`	音频地址（mp3 / ogg 等）。
`Title`	`string`	`null`	标题（缺省显示占位文案）。
`Visible`	`bool`	`true`	取得或设置组件是否可见，默认为false。
`VisibleChanged`	`EventCallback<bool>`	—	事件取得或设置组件可见性变化时的回调事件。
`Visualize`	`bool`	`true`	是否显示播放态可视化条（纯 CSS 动画，随播放状态律动）。
`Volume`	`double`	`1`	初始音量 0~1。
`Class`	`string`	`null`	取得或设置组件的CSS类名，用于自定义样式。
`Disabled`	`bool`	`false`	取得或设置组件是否禁用，默认为false。
`Style`	`string`	`null`	取得或设置组件的内联样式，用于自定义样式。

所有组件均继承 BaseComponent，除上表参数外还支持 Class、Style、Disabled、Visible。