wp-plugin-kashiwazaki-seo-tubelist-shortcode

WordPress shortcode plugin that embeds responsive YouTube channel, playlist, or @handle video lists with [ks_tubelist]. Four display modes (grid, paginate, load-more, carousel), YouTube Data API v3 with transient caching, JSON-LD VideoObject schema for SEO, full ARIA/keyboard a11y, auto dark mode, and 21 CSS variables for theming.

PHP ★ 0 🕔 0 GNU General Public License v2.0
Source ZIP Download Docs

Kashiwazaki SEO TubeList Shortcode

Version
WordPress
PHP
License

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 ― YouTube チャンネルID（UC で始まる識別子）
playlist ― プレイリストID（PL / UU / FL / RD / OL / LL 始まり）
handle ― @ハンドル（例: @MyChannel）。内部で API がチャンネルIDに解決
video ― 動画ID（11文字）または動画URL。カンマ区切りで複数指定可（最大200件）

取得元（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