設定字典:音樂播放器

$ 發布 2026-11-13 | | 更新 2026-11-14
上下文: 以實際程式碼查閱音樂播放器開關、曲目欄位、預設值、音頻載入方式及多語言文字,說明驗證規則和續播限制。

啟停播放器、填寫歌單、設定音頻路徑和介面文字。


輸出
字數 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.<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 期待生效。標準頁面目前預設收起;用戶可在介面展開。曲目和標題文字也不會觸發主題氣氛自動切換。

目前音樂模組的兩個設定欄位、三個曲目欄位和十九項文字都有消費位置,沒有額外的相容或停用欄位需要填寫。文字的無障礙用途、固定英文顯示和會話狀態已在上文區分。返回設定字典總入口查其他模組。