設定リファレンス:音楽プレーヤー

$ 公開 2026-11-13 | | 更新 2026-11-14
コンテキスト: 音楽のスイッチ、曲項目、既定値、ロード、多言語文面、検証と再開の制約を実装に基づいて説明します。

有効化、プレイリスト、音声 URL、UI 文面を設定します。


出力
語 3.3k トークン 4.3k

最初の曲は音楽設定ガイド、設定ファイルはインストール、他モジュールは総合案内を参照してください。

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項目には使用箇所があり、追加の互換・無効項目は不要です。アクセシブル用途、固定英語、セッションは区別しています。総合案内へ。