【WordPress】ショートコードの作り方と活用の全体像｜囲み型・returnの鉄則・エスケープまで

2023.08.18

ショートコードは、[hello] のような短いタグを本文に書くだけで、PHPで定義した処理の結果を挿入できるWordPressの仕組みです。この記事では、基本形・属性付き・囲み型の3パターンと、実装時に必ず守る3つの鉄則（return・エスケープ・命名）を整理します。

この記事でわかること

  • ショートコードの3パターン（基本／属性付き／囲み型）
  • echoせずreturnするなどの3つの鉄則
  • よく使う活用パターンと実装記事へのリンク
スポンサーリンク

パターン1：基本形（タグを置き換える）

functions.php で関数を定義し、add_shortcode() で登録します。結果は echo ではなく return で返すのが鉄則です（理由は後述）。

functions.php：最小のショートコード
function hello_shortcode() {
  return 'こんにちは、世界！';
}
add_shortcode('hello', 'hello_shortcode');
本文での書き方
[hello]

登録手順のより詳しい解説（編集場所・動作確認の流れ）はオリジナルのカスタムショートコードを作成する方法を参照してください。

パターン2：属性付き（値を渡して出力を変える）

[greet name="John"] のように属性で値を渡せます。shortcode_atts() でデフォルト値を定義し、出力時は esc_html() でエスケープします。

functions.php：属性付きショートコード
function greet_shortcode($atts) {
  $atts = shortcode_atts(array(
    'name' => '世界', // デフォルト値
  ), $atts, 'greet');

  return 'こんにちは、' . esc_html($atts['name']) . '！';
}
add_shortcode('greet', 'greet_shortcode');
本文での書き方
[greet name="John"]  → こんにちは、John！

複数属性の設計や投稿IDを渡す応用など、属性の詳しい使い方はショートコードにパラメータを渡して動的な出力を実現する方法で解説しています。

パターン3：囲み型（[tag]内容[/tag] で中身を加工する）

開始タグと終了タグで本文の一部を囲み、その中身を加工して出力できます。中身は第2引数 $content で受け取ります。中にさらにショートコードを書けるよう do_shortcode($content) を通すのが定番です。

functions.php：囲み型ショートコード（注意ボックス）
function notice_shortcode($atts, $content = null) {
  return '<div class="notice-box">' . do_shortcode($content) . '</div>';
}
add_shortcode('notice', 'notice_shortcode');
本文での書き方
[notice]この部分がボックスで囲まれます。[/notice]

実装の3つの鉄則

鉄則1：echoせず、必ずreturnする
ショートコードの関数内で echo すると、本文中のタグの位置ではなく、コンテンツより前に出力されてしまいます（抜粋やRSSでも崩れます）。結果の文字列は必ず return で返してください。
鉄則2：出力は必ずエスケープする
$atts（属性）や $content は投稿者の入力です。URLは esc_url()・HTML属性は esc_attr()・テキストは esc_html() でエスケープしてから出力します。許可したHTMLだけ通したい場合は wp_kses_post() が使えます。
鉄則3：名前の衝突を避ける
ショートコード名（hello など汎用的な名前）はテーマやプラグインと衝突することがあります。my_ などの接頭辞を付けた固有の名前にしておくと安全です。既存の同名ショートコードは後から登録したものに上書きされます。

活用パターン（実装例へのリンク）

ショートコードの実務での使いどころは「同じパーツ・同じ条件分岐を色々な記事で使い回す」ことです。当サイトの実装例から選んでください。

よくある質問（FAQ）

Qショートコードが実行されず [hello] と文字のまま表示されます。
Aadd_shortcode() が実行されているか（functions.php の記述ミス・テーマの切り替えで消えていないか）を確認してください。また、ウィジェットやテンプレート内では自動処理されないことがあり、PHP側では echo do_shortcode('[hello]'); のように明示的に処理します。
Q属性のデフォルト値はどう設定しますか？
Ashortcode_atts() の第1引数にデフォルト配列を渡します。$atts = shortcode_atts(array('size' => 'medium'), $atts, 'my_shortcode');。ユーザー指定が上書きし、未知の属性は無視されます。詳しくはパラメータを渡す方法を参照してください。
QXSS対策はどうすればよいですか？
A$atts・$content は入力値として扱い、URLは esc_url()・属性は esc_attr()・テキストは esc_html() でエスケープしてから出力します。一部のHTMLを許可したい場合は wp_kses_post() で投稿相当のタグに制限できます。

まとめ

  • 3パターン：基本形／属性付き（shortcode_atts）／囲み型（$content＋do_shortcode）
  • 鉄則：echoせずreturn・出力はエスケープ・名前は接頭辞付き
  • 深掘り：作成手順は1458、属性は4949、PHPから呼ぶなら6044

3パターンと3つの鉄則を押さえれば、安全で使い回しやすいショートコードが作れます。