ショートコード [ks_tubelist]
本プラグインの中核となるショートコードです。16 種類の属性で取得元・件数・表示モード・並び順・装飾を細かく制御できます。
基本構文
[ks_tubelist 必須属性 (channel | playlist | handle | video) オプション属性]取得元として channel / playlist / handle / video のいずれか 1 つを必ず指定します。複数同時指定時は video > playlist > handle > channel の優先順で解決します。
用途別サンプル
1. プレイリストを新しい順で 12 件表示 (グリッド)
[ks_tubelist playlist="PLxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" count="12" cols="3"
order="newest" show="title,date"]2. チャンネルの人気順上位 8 件をサムネ大きめで
[ks_tubelist channel="UCxxxxxxxxxxxxxxxxxxxx" count="8" cols="4"
order="popular" show="title,date,duration"]3. @ ハンドルで指定 + 説明文を 160 文字表示
[ks_tubelist handle="@MyChannel" count="6" cols="2"
show="title,date,description" excerpt_length="160"]4. 60 件取得して「もっと見る」で 6 件ずつ展開 (推奨)
[ks_tubelist channel="UCxxxx" count="60" cols="3"
mode="loadmore" per_page="6"
show="title,date,description" excerpt_length="160"]5. カルーセル (横スクロール) で最新 30 件
[ks_tubelist channel="UCxxxx" count="30" cols="4"
mode="carousel" per_page="4"]6. ページネーション + 見出しレベル制御 + JSON-LD 出力
[ks_tubelist channel="UCxxxx" count="60" cols="3"
mode="paginate" per_page="12"
heading_level="4" date_format="Y/m/d" jsonld="yes"]7. 単発動画・動画URLを指定して表示
[ks_tubelist video="dQw4w9WgXcQ" cols="1"]
[ks_tubelist video="dQw4w9WgXcQ, https://youtu.be/xxxxxxxxxxx,
https://www.youtube.com/watch?v=yyyyyyyyyyy" cols="3"]動画 ID (11 文字) または動画 URL (watch?v= / youtu.be / shorts / embed / live 形式) をカンマ区切りで複数指定できます。count 未指定なら指定した動画を全件表示し、order 未指定なら記述順のまま表示します。
属性リファレンス (全 16 属性)
取得元 (どれか 1 つ必須)
| 属性 | 初期値 | 形式 / 範囲 | 説明 |
|---|---|---|---|
channel |
― | UC[A-Za-z0-9_-]{20,30} |
YouTube チャンネル ID。UC で始まる 24 文字前後の文字列。 |
playlist |
― | (PL|UU|FL|RD|OL|LL)... |
プレイリスト ID。チャンネルのアップロード一覧 (UU...) も指定可能。 |
handle |
― | @[A-Za-z0-9._-]{3,30} |
@ ハンドル (例: @MyChannel)。内部で API がチャンネル ID に解決します。 |
video |
― | 動画 ID (11 文字) または動画 URL | カンマ区切りで複数指定可 (最大 200 件、重複は自動除去)。URL は watch?v= / youtu.be / shorts / embed / live 形式に対応。count 未指定なら全件表示、order 未指定なら記述順。 |
取得制御
| 属性 | 初期値 | 範囲 | 説明 |
|---|---|---|---|
count |
12 | 1〜200 | 取得する動画の最大件数。 |
order |
newest | newest / oldest / popular / random / manual | 並び順。popular / random は count×3 を取得母数にしてから上位/抽選で count 件にします。manual は取得元の並び (video は記述順、playlist は登録順) を維持します。 |
cache |
3600 | 0 以上 (秒) | 取得結果を transient にキャッシュする秒数。0 で無効化 (毎回 API 取得)。 |
表示制御
| 属性 | 初期値 | 範囲 | 説明 |
|---|---|---|---|
mode |
管理画面の既定値 | grid / paginate / loadmore / carousel | 表示モード。詳細は 表示モード 参照。 |
per_page |
管理画面の既定値 | 1〜count | 1 ページ (または 1 スクリーン) に表示する件数。paginate / loadmore / carousel で使用。 |
cols |
3 | 1〜8 | グリッドの列数。レスポンシブで 900px / 640px / 420px ブレークポイントで自動縮小。 |
show |
title,date | title / date / duration / views / description (カンマ区切り) | 表示する項目を列挙。例: show="title,date,duration,views" |
excerpt_length |
120 | 0 以上 | description を表示する際の最大文字数 (mb_substr ベース)。0 で全文表示。 |
heading_level |
3 | 2〜6 | 動画タイトルの見出しタグ。目次プラグインの拾われ方を調整できます。 |
title_lines |
2 | 1〜6 | タイトルを何行で省略するか (-webkit-line-clamp)。長いタイトルの折返し制御。 |
date_format |
WP の「日付形式」設定 | PHP 日付フォーマット文字列 | 例: Y/m/d / Y年n月j日。未指定で WP 設定値を使用。 |
jsonld |
no | yes / no / 1 / true | yes で ItemList + VideoObject の JSON-LD を <script type="application/ld+json"> として出力。SEO 用。 |
使い方タブで属性早見表を確認
管理画面「使い方」タブでもショートコード例と属性表を確認できます (本マニュアルとほぼ同じ内容)。
動作上の注意点
popular / random は API 取得量が増えます。 並び替えのために count×3 を取得するため、無料枠の消費が大きくなります。cache を長めに設定するか、十分な件数を取得する設計に変えてください。
per_page は count を超えません。 count="6" per_page="12" と指定しても、内部で per_page = min(count, per_page) = 6 として扱われます。
取得元の形式チェック (UC で始まる / PL で始まる / @ で始まる) は描画前に検証されます。形式不正の場合、編集権限者にのみエラーメッセージが表示され、訪問者には何も表示されません。