音频播放器组件示例

本文演示两个职责不同的音频组件。AudioPlayer 面向正文里的讲解、播客、有声书；MusicPlayer 面向带封面的完整曲目展示。验证完成后可删除本文，或将 frontmatter 中的 draft 改为 true。

一、AudioPlayer

无封面，控件集中在播放条：可拖动进度、切换倍速、调节音量。适合嵌入段落之间，不抢视觉焦点。

基础用法

只传 src 即可，地址支持 public/ 相对路径（如 /audio/demo.mp3）或完整外链 URL：

0:00 / 0:00 1x

带标题与副标题

第三章 · 迷雾中的灯塔 朗读：HoliznaCC0

0:00 / 0:00 1x

import AudioPlayer from "../../components/AudioPlayer.astro";

<AudioPlayer
  src="/audio/demo.mp3"
  title="章节标题"
  artist="作者 / 说明"
/>

属性	必填	说明
src	是	音频地址
title	否	标题
artist	否	副标题 / 作者 / 说明
loop	否	是否循环，默认 false

控件：播放/暂停、可拖动进度条、时间、倍速（1x → 1.25x → 1.5x → 2x → 0.75x）、音量与静音。

二、MusicPlayer

带封面卡片，进度由底部分隔条展示，可拖动调节；外框为固定长度的装饰槽线，不随播放变化。无倍速、无时间、无音量条。

单曲 · 默认封面

未指定 cover 时使用内置默认封面；右侧有播放模式按钮，可在「顺序播放」与「列表循环」间切换（顺序白底、列表灰底）：

Come Again

HoliznaCC0

单曲 · 自定义封面

Come Again

HoliznaCC0

长标题滚动

移动端标题或作者超出宽度时会自动横向滚动，也可手动滑动；桌面端截断显示：

Come Again — Extended Edition with a Very Long Title That Keeps Going

HoliznaCC0 · Busted Guitar (LOFI EDIT) · Bonus Tracks Collection

播放列表

传入 tracks 且多于一首时，额外显示歌单开合按钮。播放模式在顺序 → 列表 → 单曲 → 随机间循环；切歌靠点击歌单项或模式自动流转，无上一首/下一首按钮：

Come Again — Extended Edition with a Very Long Title That Keeps Going

HoliznaCC0 · Busted Guitar (LOFI EDIT) · Bonus Tracks Collection

1. 1
   Come Again — Extended Edition with a Very Long Title That Keeps Going
   HoliznaCC0 · Busted Guitar (LOFI EDIT) · Bonus Tracks Collection
2. 2
   Busted Guitar
   HoliznaCC0
3. 3
   Lofi Interlude
   HoliznaCC0
4. 4
   Midnight Drive
   HoliznaCC0 · Night Sessions
5. 5
   Rain on the Window
   HoliznaCC0
6. 6
   Slow Sunday
   HoliznaCC0 · Weekend Vibes
7. 7
   Echoes in the Hallway — Ambient Mix with Extra Long Subtitle for Scrolling Test
   HoliznaCC0 · Deep Focus

import MusicPlayer from "../../components/MusicPlayer.astro";

<!-- 单曲 -->
<MusicPlayer
  src="/audio/song.mp3"
  title="曲目标题"
  artist="歌手 / 专辑"
  cover="/images/covers/cover-blue.svg"
/>

<!-- 播放列表 -->
<MusicPlayer
  tracks={[
    { src: "/audio/a.mp3", title: "曲目一", artist: "歌手 A" },
    { src: "/audio/b.mp3", title: "曲目二", artist: "歌手 B" },
  ]}
/>

属性	必填	说明
src	与 tracks 二选一	单曲音频地址
title / artist / cover	否	单曲标题 / 副标题 / 封面
tracks	与 src 二选一	{ src, title?, artist?, cover? }[]；多于一项时显示歌单

控件：封面中央悬停播放/暂停；底部分隔条进度（可拖动）；播放模式按钮（单曲两种模式，多曲四种）；多曲时有可折叠歌单（展开可见 5 首，超出可滚动），当前曲目高亮。

共同点

两者均适配暗色模式与移动端。同一页面可混用多个实例，播放其中一个会自动暂停其它。

音频文件可放在 public/audio/ 随站点部署；体积较大或数量较多时，建议用 R2 等对象存储并以完整 URL 引用。