配置字典:音乐播放器
启停播放器、填写歌单、配置音频路径和界面文案。
文章目录
想先放一首自己的歌,读音乐设置教程。配置文件位置见安装与站点信息,其他模块从配置字典总入口进入。
播放器设置写在 src/site.config.ts 的 theme.music 下。主题默认关闭播放器,歌单为空,不附带默认歌曲。下面说明主题包的默认值,不以 demo 的个人歌单为准。
theme.music.enabled:播放器开关
- 类型 / 默认值: boolean / false。
- 状态与作用: 生效。为 true 且歌单至少有一首有效歌曲时,标准页面公共框架才渲染播放器。
- 限制: 只写 true 而不填曲目不会显示播放器。关闭时曲目不会进入有效运行歌单,且跳过曲目逐项校验;不会删除配置或 public 中的音频文件,也不限制用户直接访问已公开文件。
- 示例:
theme: { music: { enabled: false } }。
开关是全站公共设置,不是为首页或每种语言分别启停的开关。使用公共框架的标准页面共用同一份歌单;不是只能在首页播放。自定义页面是否接入公共框架则由页面自身决定。
theme.music.tracks:曲目列表
- 类型 / 默认值: MusicTrack[] / []。每一项的三个字段见下表。
- 状态与作用: 条件生效,音乐开启后使用。按数组顺序展示歌单并切换曲目;没有公开的条数上限。
- 限制: 开启时必须为数组;空数组有效,但有效播放器状态会变为关闭。覆盖数组时整体替换,不与默认值或旧歌单拼接。增加歌曲时保留仍要使用的条目。
- 示例值: [{ title: ‘我的一首歌’, artist: ‘作者’, src: ‘
/music/my-song.mp3’ }]。
歌曲标题、作者和地址都在这个全站数组里,不在 i18n 文案里;切换页面语言不会自动换歌单。不要把第三方平台的歌单对象或分享链接直接当成此数组。
每首歌曲的字段
完整前缀是 theme.music.tracks[]。下表中的“无”表示自定义条目没有自动补值。
| 字段 | 类型 / 默认值 | 状态、作用与限制 | 示例值 |
|---|---|---|---|
| title | string,必填 / 无 | 条件生效:主显示区、折叠标题及歌单中的歌曲名称。必须是非空字符串;首尾空白会被移除。空白标题报错,不从文件名或音频标签生成 | ‘我的一首歌’ |
| artist | string,可省略 / 未设置,归一化为 ‘’ | 条件生效:主显示区和歌单中的作者文字。填写时必须为 string,首尾空白会移除;空值不自动补站点作者,也不读取音频元数据 | ‘作者’ |
| src | string,必填 / 无 | 条件生效:音频源地址;必须以单个 / 或小写 https:// 开头,不能含空白或反斜杠。HTTPS 地址还需能通过 URL 解析;不检查文件是否存在或内容是否为音频 | ‘/music/my-song.mp3’ |
title 和 artist 按文本显示,不解析 Markdown 或 HTML。没有公开的封面、歌词、时长、专辑、独立 ID 或按曲目设置音量的字段。
src 的限制需要分清:
- 本地文件建议放
public/music/,配置使用 /music/文件名,不写 public 前缀,不写 Windows 磁盘路径或 src/assets 源码路径。实现接受符合规则的其他根路径,并不强制位于 /music/,也不按扩展名确认音频格式。 - 不接受 http://、//example.com/file.mp3、data:、blob: 或普通相对路径。HTTPS 前缀校验区分大小写;示例统一使用小写 https://。
- 地址不能直接带空格;需要时对路径做 URL 编码,但编码正确不代表服务器上一定有对应文件。不要在地址首尾添加空格。
- 根路径在渲染时自动加上 Astro 的 BASE_URL;使用子路径部署时不要自行重复添加同一前缀。HTTPS 地址保持原值。
- 格式正确只表示配置通过。文件仍需由浏览器支持并可访问;平台分享页面不等于音频直链。外链以 fetch 下载,服务器必须允许当前站点跨域读取;仅能在新标签页播放,不代表允许 CORS。
播放器用 src 恢复已保存的曲目,建议每首使用不同地址。重复 src 没有被配置校验禁止,但恢复时会匹配第一个相同地址;标题不是恢复标识。
可合并的歌单示例
先自行准备 public/music/my-song.mp3。下面的路径是示例,主题不会替你生成音频文件。将片段合并到 src/site.config.ts 现有的 defineThemeConfig({...}),保留 import、export 和其他个人配置,不要重复创建 theme。
theme: {
music: {
enabled: true,
tracks: [
{
title: '我的一首歌',
artist: '作者',
src: '/music/my-song.mp3',
},
],
},
},
只关闭播放器时设置 enabled: false;不必清空歌单。修改配置后开发服务需要重新读取配置,线上网站则需重新构建部署;仅上传音频但未登记 tracks 不会自动加入歌单。
messages.music:十九项界面与无障碍文案
完整前缀是 i18n.locales.<语言>.messages.music.。每项均为可省略的 string,默认来自内置当前语言文案和语言回退链。下表只列中文 / 英文默认值,示例列是字段值;生效条件是播放器已渲染且对应控件或状态出现。空字符串会覆盖文案,不是隐藏功能的开关,也可能使控件失去清楚的无障碍名称。
| 字段 | 中文 / 英文默认值 | 作用与限制 | 示例值 |
|---|---|---|---|
label |
音乐播放器 / Music player | 播放器 aside 区域的无障碍名称,不是顶部 AUDIO CHANNEL 文案 | "音乐播放器" |
play |
播放 / Play | 播放按钮的无障碍名称;可见按钮仍为 PLAY | "播放" |
pause |
暂停 / Pause | 播放中或加载中按钮的无障碍名称;可见按钮为 PAUSE | "暂停" |
prev |
上一首 / Previous | 上一首按钮的无障碍名称;可见文字为 PREV | "上一首" |
next |
下一首 / Next | 下一首按钮的无障碍名称;可见文字为 NEXT | "下一首" |
open |
展开播放器 / Open player | 折叠状态下展开按钮的无障碍名称;可见文字为 OPEN | "展开播放器" |
close |
收起播放器 / Collapse player | 展开状态下收起按钮的无障碍名称;可见文字为 MIN。收起不暂停播放 | "收起播放器" |
progress |
播放进度 / Progress | 进度滑块的无障碍名称,不改变进度或可跳转范围 | "播放进度" |
volume |
音量 / Volume | 音量滑块的无障碍名称,不设置默认音量;可见标签仍为 LVL | "音量" |
queue |
歌单 / Playlist | 歌单展开按钮的无障碍名称;可见 QUEUE、SHOW / HIDE 等文字固定 | "展开或收起歌单" |
mute |
静音 / Mute | 非静音时静音按钮的无障碍名称;可见文字为 MUTE | "静音" |
unmute |
取消静音 / Unmute | 音量为零时恢复音量按钮的无障碍名称;可见文字为 UNMUTE | "恢复音量" |
idle |
就绪 / Ready | 初始或切换歌曲后的 SIGNAL 状态文字 | "等待播放" |
loading |
加载中 / Loading | 歌曲下载或等待播放时的 SIGNAL 状态文字 | "正在加载歌曲" |
playing |
播放中 / Playing | 正在播放时的 SIGNAL 状态文字 | "正在播放" |
paused |
已暂停 / Paused | 暂停时的 SIGNAL 状态文字 | "已暂停" |
blocked |
浏览器阻止了自动播放,请点击 PLAY 继续播放。 / Click Play to continue. Your browser blocked automatic playback. | 浏览器拒绝播放权限时的提示;不能通过改文字解除限制 | "请点击播放以继续。" |
error |
播放失败,请重试或切换歌曲。 / Unable to play. Try again or select another track. | 音频请求、播放失败的状态,以及播放器挂载模块失败时的提示 | "歌曲未能加载,请重试。" |
noScript |
请启用 JavaScript 使用播放器。 / Enable JavaScript to use the player. | 浏览器禁用 JavaScript 时的 noscript 提示,不会提供原生音频替代控件 | "启用 JavaScript 后可以使用播放器。" |
这些文案不是整套终端 UI 的可见文字替换表。PLAY / PAUSE、PREV / NEXT、OPEN / MIN、MUTE / UNMUTE、QUEUE、SHOW / HIDE、TRACKS、LVL、AUDIO CHANNEL、STATE、SIGNAL 和 STANDBY 等状态代号由实现固定;对应可配置字段用于无障碍名称或 SIGNAL 行的可见状态,不能因为按钮仍显示英文就把字段判断为未生效。
例如只覆盖中文加载和错误提示:
i18n: {
locales: {
zh: {
messages: {
music: {
loading: '正在加载歌曲',
error: '歌曲未能加载,请重试。',
},
},
},
},
},
语言启用和回退见多语言教程。音乐文案遵循语言,曲目数组仍是全站共享。
音频何时下载,为什么有时需要等待?
首次使用且没有已保存续播状态时,初始化界面不创建音频下载;点击播放、上一首、下一首或歌单曲目才请求所选音频。单纯展开面板或歌单不会下载整份歌单。恢复同一标签页的续播状态时,也可能自动发起所选歌曲请求。
当前播放器先完整下载所选音频,转成 Blob,再交给 Audio 播放;不是下载一点就开始的流式播放。这样即使服务器忽略 Range 请求,已下载内容仍可跳转进度。大文件会增加首次等待与内存占用;音频源不会由主题自动转码、压缩或生成不同码率。
暂停后再次播放会复用当前音频和已下载的 Blob。切换到另一首会中止未完成的下载并释放旧资源,切回可能重新请求;服务器和浏览器 HTTP 缓存是否命中是另一层行为,不代表播放器永久缓存了全部歌曲。失败不会自动跳过坏歌;可再次点击播放重试。播放权限被浏览器拒绝时显示 blocked 提示,仍需用户操作。
外链必须允许 CORS,且下载应返回成功状态;主题没有配置代理、授权请求头或自定义凭据的入口。同站点 public 音频无需额外跨域配置。修改提示文字不会修复音频路径、权限或格式问题。
播放、续播、外观:固定行为与配置边界
| 项目 | 当前实际行为 | 是否是 site.config 字段 |
|---|---|---|
| 默认选曲 | 没有可匹配的已保存歌曲时选第一首;匹配依据是解析后的 src | 否,没有 defaultTrack |
| 默认音量 | 首次为 0.5,之后可以恢复同标签页保存的音量 | 否,没有 defaultVolume |
| 静音 | 将音量设为零;恢复时使用记住的非零音量,不停止下载或暂停播放 | 否,没有独立 mute 配置 |
| 自动下一首 | 播放结束后切到下一项,最后一项后回到第一项;不是随机播放 | 否,没有 shuffle / repeat / loop 配置 |
| 续播 | sessionStorage 保存歌曲地址、进度、音量、收起状态与续播意图;可用时在同标签页导航或恢复页面后尝试续播,受浏览器权限影响 | 否,没有 autoplay / resume 配置 |
| 面板初始状态 | 标准播放器组件默认收起;初始组件参数优先于保存的展示偏好,BFCache 恢复另有状态恢复逻辑 | 否,没有 theme.music.collapsed |
| 收起、展开与歌单 | 只改变界面,不暂停播放;Escape 可收起展开的面板 | 否,没有通过 site.config 修改快捷键的字段 |
| 页面风格 | 公共框架按当前页面选择 Matrix / Cyber / Hacker / AI 或基础外观;不是按歌曲类型选择 | 否,没有 theme.music.scene |
| 动画 | Matrix 使用自己的视觉效果,结合播放状态、页面可见性与收起状态运行;同时遵循系统减少动态效果偏好;效果失败不应阻止音频 | 否,没有音乐专属效果开关 |
sessionStorage 是会话状态,不是永久云端记录,也不是跨标签页同步协议。保存受限时播放器仍可工作,但不能保证恢复状态;不保证跨页面无缝、无中断播放。浏览器不支持 JavaScript 时,显示 noScript 提示,播放器交互不可用。
组件或自定义布局的 initiallyCollapsed、musicInitiallyCollapsed、scene 等参数不是公开的 site.config 字段,不要直接添加到 theme.music 期待生效。标准页面当前默认收起;用户可在界面展开。曲目和标题文字也不会触发主题气氛自动切换。
当前音乐模块的两个配置字段、三个曲目字段和十九项文案都有消费位置,没有额外的兼容或停用字段需要填写。文案的无障碍用途、固定英文显示和会话状态已在上文区分。返回配置字典总入口查其他模块。