Kashiwazaki SEO TubeList Shortcode

YouTube のチャンネルID / プレイリストID / @ハンドルを指定して、固定ページや投稿内にレスポンシブな動画一覧をショートコード [ks_tubelist] で表示する WordPress プラグインです。YouTube Data API v3 を利用し、取得結果は WordPress の transient でキャッシュします。表示モード 4 種、JSON-LD 構造化データ、アクセシビリティ、ダークモード自動対応まで標準装備しています。

主な機能

• ショートコード [ks_tubelist] による動画一覧の埋め込み
• 取得元: チャンネルID (UC...) / プレイリストID (PL/UU/FL/RD/OL/LL...) / @ハンドル (@MyChannel) / 単発動画 (video 属性に動画ID・URL をカンマ区切りで複数指定可) に対応
• 表示モード: グリッド / ページネーション（数字ボタン）/ もっと見る / カルーセル（横スクロール）
• 並び順: 新しい順 / 古い順 / 人気順（視聴回数）/ ランダム / 取得元の並び順を維持（manual）
• 表示項目: タイトル / 公開日 / 再生時間 / 視聴回数 / 概要（説明文）
• 概要文の <details> ベースのアコーディオン展開（JS不要、:has() 非対応ブラウザは JS フォールバック）
• 見出しレベル制御（heading_level 属性で h2-h6 を選択、目次プラグイン対策）
• タイトルの行数クランプ（title_lines 属性）
• 日付フォーマット個別指定（date_format 属性）
• JSON-LD ItemList + VideoObject 構造化データ出力（SEO 用、jsonld="yes"）
• 管理画面でデフォルト表示モード／ページサイズを保存
• API キーは password 型入力 + 「表示」「テスト」ボタン
• API キー変更時に transient キャッシュを自動破棄
• 管理画面からのキャッシュ手動クリア + admin_notice 通知
• アクセシビリティ: ARIA region / aria-label / aria-live / aria-controls / aria-current
• prefers-reduced-motion で smooth scroll / transition を自動無効化
• prefers-color-scheme: dark でダークモード自動対応（kstls-no-dark クラスで opt-out 可）
• カルーセルのキーボード操作（ArrowLeft / ArrowRight / Home / End）
• レスポンシブ対応（900px / 640px / 420px ブレークポイントで自動列調整）
• 21 個の CSS カスタムプロパティで配色・余白・行数を上書き可能
• 初回バッチ画像の loading="eager" + fetchpriority="high" で LCP 改善
• アセットの filemtime() ベース cache busting（CDN キャッシュ自動切替）
• 本文にショートコード検出時に wp_head で先行 enqueue（FOUC 防止）
• transient による API レスポンスキャッシュ（秒数指定可）
• プラグイン一覧からワンクリックで設定画面へ
• アンインストール時にオプション・transient を完全削除（マルチサイト対応）

インストール

1. wp-plugin-kashiwazaki-seo-tubelist-shortcode ディレクトリを wp-content/plugins/ にアップロード
2. WordPress 管理画面の「プラグイン」画面で「Kashiwazaki SEO TubeList Shortcode」を有効化
3. 管理画面メニュー「Kashiwazaki SEO TubeList Shortcode」から YouTube Data API キーを設定

YouTube Data API キーの取得

1. Google Cloud Console でプロジェクトを作成
2. 「APIとサービス」→「ライブラリ」から YouTube Data API v3 を有効化
3. 「APIとサービス」→「認証情報」から API キーを発行
4. 取得した API キーを本プラグインの設定画面に貼り付け

使い方

プレイリストから取得

[ks_tubelist playlist="PLxxxx" count="12" cols="3" order="newest" show="title,date"]

チャンネルから取得

[ks_tubelist channel="UCxxxx" count="8" cols="4" order="popular" show="title,date,duration"]

@ハンドルから取得

[ks_tubelist handle="@MyChannel" count="6" cols="3" mode="loadmore" per_page="6"]

単発動画・動画URLから取得

動画ID または動画URL（watch?v= / youtu.be / shorts / embed / live 形式）をカンマ区切りで指定できます。count 未指定なら指定した動画を全件表示、order 未指定なら記述順のまま表示します。

[ks_tubelist video="dQw4w9WgXcQ" cols="1"]
[ks_tubelist video="dQw4w9WgXcQ, https://youtu.be/xxxxxxxxxxx, https://www.youtube.com/watch?v=yyyyyyyyyyy" cols="3"]

もっと見る + 説明文 + JSON-LD 出力

[ks_tubelist channel="UCxxxx" count="60" cols="3" mode="loadmore" per_page="6"
             show="title,date,description" excerpt_length="160" jsonld="yes"]

属性一覧

取得元（channel / playlist / handle / video）は通常いずれか 1 つを指定します。複数同時指定した場合は video > playlist > handle > channel の優先順で 1 つだけが採用されます。 | count | 12 | 取得する動画件数（1〜200）。video 指定時に未指定なら指定した動画を全件表示 | | mode | 管理画面の既定値 | 表示モード。grid / paginate / loadmore / carousel | | per_page | 管理画面の既定値 | 1ページ（1スクリーン）に表示する件数 | | cols | 3 | グリッドの列数（1〜8）。画面幅に応じて自動で減少 | | order | newest | 並び順。newest / oldest / popular / random / manual（取得元の並びを維持。video 指定時に未指定なら記述順 = manual 扱い） | | show | title,date | 表示項目をカンマ区切りで指定。title / date / duration / views / description | | excerpt_length | 120 | description を表示する際の最大文字数。0 で全文表示 | | cache | 3600 | 取得結果のキャッシュ秒数。0 で無効化 | | heading_level | 3 | タイトルの見出しレベル（2〜6） | | title_lines | 2 | タイトルの行数クランプ（1〜6） | | date_format | WP 設定値 | PHP 日付フォーマット文字列（例: Y/m/d） | | jsonld | no | yes で ItemList + VideoObject の JSON-LD を出力（SEO 用） |

CSS カスタマイズ

主要な見た目は 21 個の CSS カスタムプロパティで上書きできます。

.kstls-tubelist {
    --kstls-gap: 24px;
    --kstls-radius: 10px;
    --kstls-title-color: #111;
    --kstls-title-lines: 3;
    --kstls-sub-color: #888;
    --kstls-link-color: inherit;
    --kstls-control-bg: #ffffff;
    --kstls-control-active-bg: #1d2327;
    --kstls-duration-bg: rgba(0, 0, 0, 0.8);
    --kstls-scroll-offset: 80px;
}

ダークモードは @media (prefers-color-scheme: dark) で自動的に色変数を切り替えます。無効化したい場合はショートコードを囲む要素に kstls-no-dark クラスを付与してください。

ドキュメント

利用者向けの完全マニュアルは docs/ に同梱しています。GitHub Pages で公開する場合は Settings → Pages → Source: Deploy from a branch → main / docs を選択してください。

動作環境

• WordPress 5.0 以上 (Tested up to 6.7)
• PHP 7.2 以上
• YouTube Data API v3 のキー
• mbstring 拡張（推奨。description の文字数カウントに使用）

ライセンス

GPL v2 or later