設定リファレンス:音楽プレーヤー
有効化、プレイリスト、音声 URL、UI 文面を設定します。
目次
最初の曲は音楽設定ガイド、設定ファイルはインストール、他モジュールは総合案内を参照してください。
src/site.config.ts の theme.music に指定します。既定では無効、プレイリストは空、曲は付属しません。以下はデモ個人設定ではなくパッケージ既定値です。
theme.music.enabled:プレーヤーのスイッチ
- 型 / 既定値: boolean / false。
- 状態と役割: 有効。true かつ有効な曲が1件以上なら標準の共通枠に描画します。
- 制約: true だけで曲なしなら表示しません。無効時は有効な実行リストへ入れず曲別検証もスキップしますが、設定・public の音声を削除したり直接アクセスを制限したりしません。
- 例:
theme: { music: { enabled: false } }。
全体共通設定で、ホーム・言語別スイッチではありません。共通枠を使う標準ページは同じリストを共有し、ホーム専用ではありません。独自ページへの接続はそのページ次第です。
theme.music.tracks:曲一覧
- 型 / 既定値: MusicTrack[] / []。各曲の3項目は下表です。
- 状態と役割: 音楽有効時に配列順で表示・切替します。公開の件数上限はありません。
- 制約: 有効時は配列必須。空配列も有効ですが実プレーヤーは無効になります。配列は既定・旧リストに追加でなく全置換し、追加時は残す曲も含めます。
- 値の例: [{ title: ‘我的一首歌’, artist: ‘作者’, src: ‘
/music/my-song.mp3’ }]。
曲名・作者・URL はこの全体配列で、i18n 文面ではありません。言語切替で曲は変わりません。他サービスのプレイリストオブジェクトや共有 URL をそのまま指定しないでください。
各曲の項目
接頭辞は 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 接頭辞は大小文字を区別し、例は小文字です。
- URL に空白を直接使わず必要ならエンコードします。正しい符号化はファイル存在を保証しません。前後にも空白を加えません。
- ルートパスには描画時 BASE_URL を加え、同じサブパスを自分で重ねないでください。HTTPS は維持します。
- 形式通過でもブラウザー対応・アクセスが必要です。共有ページは音声直リンクではありません。外部は fetch で取得するため CORS が必要で、新窓で再生可能でも CORS 許可とは限りません。
保存曲の復元には src を使うため、各曲に別 URL を推奨します。重複は検証禁止ではありませんが最初の一致に戻り、タイトルは識別子ではありません。
統合用プレイリスト例
public/music/my-song.mp3 を自分で用意します。テーマは音声を生成しません。既存 defineThemeConfig({…}) に統合し、import・export・他設定を残して theme を重複させないでください。
theme: {
music: {
enabled: true,
tracks: [
{
title: '私の一曲',
artist: '著者',
src: '/music/my-song.mp3',
},
],
},
},
停止だけなら enabled: false でリストの消去は不要です。開発は設定の再読込、本番は再ビルド・再配備が必要です。音声のアップロードだけでは tracks に自動追加しません。
messages.music:19項目の UI とアクセシブル文面
接頭辞は 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 | 音量0時の復元名。表示 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。標準 audio 代替 UI は提供しない。 | "JavaScript を有効にするとプレーヤーを利用できます。" |
全ターミナル UI の置換表ではありません。PLAY / PAUSE、PREV / NEXT、OPEN / MIN、MUTE / UNMUTE、QUEUE、SHOW / HIDE、TRACKS、LVL、AUDIO CHANNEL、STATE、SIGNAL、STANDBY は固定です。設定はアクセシブル名や SIGNAL の状態文面なので、英語が残っても無効とは限りません。
日本語のロード・エラーだけを上書きする例です。
i18n: {
locales: {
ja: {
messages: {
music: {
loading: '曲を読み込み中',
error: '曲を読み込めませんでした。再試行してください。',
},
},
},
},
},
言語スイッチと補完は多言語ガイドへ。文面は言語別、曲は全サイト共通です。
音声をいつ取得し、なぜ待つのか
初回で保存した再開状態がなければ、UI 初期化では取得しません。再生、前・次、曲選択で対象を要求し、パネルや一覧を開くだけでは全曲を取得しません。同じタブの再開復元では自動要求する場合があります。
まず曲全体を取得して Blob にし、Audio で再生します。ストリーミングではありません。Range を無視するサーバーでも取得済み内容の位置を変えられます。大容量は初回待ちとメモリーを増やします。自動変換・圧縮・別ビットレート生成はしません。
停止後の再生は音声と Blob を再利用します。別曲では未完取得を中断して旧資源を解放し、戻ると再取得する場合があります。HTTP キャッシュは別層で、全曲の永続キャッシュではありません。不良曲を自動スキップせず再生で再試行できます。再生権限が拒否されると blocked で操作が必要です。
外部は CORS と成功レスポンスが必要です。プロキシ、認証ヘッダー、独自資格情報の設定はありません。同一サイト public は追加 CORS 不要です。文面変更ではパス・権限・形式を直せません。
再生、復元、外観の固定動作と範囲
| 項目 | 現在の動作 | site.config 項目か |
|---|---|---|
| 既定曲 | 保存 src が一致しなければ最初の曲。解決済み src で照合。 | いいえ。defaultTrack なし。 |
| 既定音量 | 初回0.5、その後は同タブの保存値を復元可能。 | いいえ。defaultVolume なし。 |
| ミュート | 音量0、解除は記憶した非ゼロ値。取得停止・一時停止ではない。 | いいえ。独立 mute なし。 |
| 次の曲 | 終了で次、最後の次は最初。ランダムでない。 | いいえ。shuffle / repeat / loop なし。 |
| 再開 | sessionStorage に src・位置・音量・折畳み・再開意図を保存し、同タブ移動・復元で試行。ブラウザー権限に従う。 | いいえ。autoplay / resume なし。 |
| 初期パネル | 標準は閉じ、初期引数が保存表示設定より優先。BFCache は別の復元あり。 | いいえ。theme.music.collapsed なし。 |
| 展開・一覧 | UI だけを変え、停止しない。Escape でパネルを閉じる。 | いいえ。キー変更項目なし。 |
| ページ外観 | 現在ページの Matrix / Cyber / Hacker / AI / 基本で、曲の種類ではない。 | いいえ。theme.music.scene なし。 |
| アニメーション | Matrix 固有效果を再生・可視性・折畳みに合わせ、動き軽減設定にも従う。効果失敗は音声を妨げるべきでない。 | いいえ。音楽固有スイッチなし。 |
sessionStorage はセッションで、永続クラウドやタブ間同期ではありません。保存不可でも使えますが復元を保証せず、ページ間の無中断再生も保証しません。JavaScript なしでは noScript を出し、操作できません。
initiallyCollapsed、musicInitiallyCollapsed、scene などのコンポーネント・独自レイアウト引数は公開設定ではなく、theme.music に加えても反映しません。標準は初め閉じ、UI で開けます。曲名もテーマを切り替えません。
設定2項目、曲3項目、文面19項目には使用箇所があり、追加の互換・無効項目は不要です。アクセシブル用途、固定英語、セッションは区別しています。総合案内へ。