配置字典:音乐播放器

$ 发布 2026-11-13 | | 更新 2026-11-13
语境: 以实际代码查阅音乐播放器开关、曲目字段、默认值、音频加载方式及多语言文案,说明验证规则和续播限制。

启停播放器、填写歌单、配置音频路径和界面文案。


输出
词 3.5k 令牌 4.5k

想先放一首自己的歌,读音乐设置教程。配置文件位置见安装与站点信息,其他模块从配置字典总入口进入。

播放器设置写在 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 期待生效。标准页面当前默认收起;用户可在界面展开。曲目和标题文字也不会触发主题气氛自动切换。

当前音乐模块的两个配置字段、三个曲目字段和十九项文案都有消费位置,没有额外的兼容或停用字段需要填写。文案的无障碍用途、固定英文显示和会话状态已在上文区分。返回配置字典总入口查其他模块。