設定字典:音樂播放器
啟停播放器、填寫歌單、設定音頻路徑和介面文字。
本頁目錄
想先放一首自己的歌,讀音樂設定教學。設定檔案位置見安裝與網站資訊,其他模組從設定字典總入口進入。
播放器設定寫在 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.<locale>.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-hant': {
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 期待生效。標準頁面目前預設收起;用戶可在介面展開。曲目和標題文字也不會觸發主題氣氛自動切換。
目前音樂模組的兩個設定欄位、三個曲目欄位和十九項文字都有消費位置,沒有額外的相容或停用欄位需要填寫。文字的無障礙用途、固定英文顯示和會話狀態已在上文區分。返回設定字典總入口查其他模組。