【WordPress】オリジナルのカスタムショートコードを作成する方法｜登録・属性・エスケープ

2023.11.03

ショートコードを使うと、[custom_shortcode] のような短いタグを書くだけで、PHPで定義した処理の結果を投稿・固定ページに挿入できます。この記事では、オリジナルのショートコードを作る手順を、登録から属性・エスケープまでステップごとに解説します。

この記事でわかること

  • add_shortcode() でショートコードを登録する
  • shortcode_atts() で属性を受け取る
  • esc_html() で安全に出力する
全体像・囲み型・鉄則はこちら
ショートコードの3パターン（基本／属性／囲み型 [tag]内容[/tag]）や、「echoせずreturnする」などの鉄則はショートコードの作り方と活用の全体像にまとめています。この記事は基本の作成手順に絞って解説します。
スポンサーリンク

手順1：functions.phpで登録する

ショートコードは、テーマ（できれば子テーマ）の functions.php に「処理する関数」と「登録する add_shortcode()」をセットで書きます。結果は echo ではなく return で返すのが鉄則です。

functions.php：ショートコードを登録する
function my_custom_shortcode($atts) {
  return 'これはカスタムショートコードのテキストです。'; // echoではなくreturn
}
add_shortcode('custom_shortcode', 'my_custom_shortcode');

add_shortcode() の第1引数がショートコード名（custom_shortcode）、第2引数が処理する関数名です。

管理画面のテーマエディター編集は避ける
functions.php は、構文エラー1つでサイト全体が表示不能（白画面）になります。管理画面の「テーマファイルエディター」ではなく、子テーマのファイルをローカルのエディタで編集し、FTP等でアップロードするのが安全です。また、ショートコード名は my_ など固有の接頭辞を付けると、他のプラグインとの名前衝突を避けられます。

手順2：投稿・固定ページで使う

登録したら、投稿や固定ページの本文に次のように書くだけで、関数の戻り値が挿入されます。

本文での書き方
[custom_shortcode]

テーマのPHPファイル（テンプレート）内でショートコードを実行したい場合はecho do_shortcode('[custom_shortcode]'); を使います（テーマのPHPからショートコードを呼び出す方法）。

手順3：属性を受け取る（エスケープを忘れない）

ショートコードに属性（オプション）を渡すと、動的な出力ができます。shortcode_atts() でデフォルト値を定義し、出力時は esc_html() でエスケープします。属性は投稿者の入力なので、そのまま出すとレイアウト崩れやXSSの原因になります。

functions.php：属性付きショートコード（esc_html付き）
function my_custom_shortcode($atts) {
  $atts = shortcode_atts(array(
    'text' => 'デフォルトのテキスト', // デフォルト値
  ), $atts, 'custom_shortcode');

  return 'カスタムテキスト: ' . esc_html($atts['text']); // 出力は必ずエスケープ
}
add_shortcode('custom_shortcode', 'my_custom_shortcode');

使うときは属性を指定します。

本文での書き方（属性つき）
[custom_shortcode text="新しいテキスト"]
属性の種類でエスケープ関数を変える
テキストは esc_html()、URLは esc_url()、HTMLの属性値は esc_attr() を使い分けます。複数属性の設計や投稿IDを渡す応用はショートコードにパラメータを渡して動的な出力を実現する方法、ログイン状態で出し分ける実例はログインユーザーにだけ表示するコンテンツをショートコードで実装する方法を参照してください。

よくある質問（FAQ）

Qボタンを表示するショートコードの例を教えてください。
A囲み型（[btn]…[/btn]）にすると中身をボタンにできます。add_shortcode('btn', function ($atts, $content) { $a = shortcode_atts(array('url' => '#', 'color' => 'primary'), $atts); return '<a href="' . esc_url($a['url']) . '" class="btn btn-' . esc_attr($a['color']) . '">' . do_shortcode($content) . '</a>'; });。URLは esc_url、class属性は esc_attr でエスケープします。
Qショートコードの中で別のショートコードを使うには？
A囲んだ中身（第2引数 $content）を do_shortcode($content) に通します。ネストしたショートコードが展開されます。ただし同じショートコードの再帰は無限ループになるため避けてください。
Qショートコードをブロックエディタ（Gutenberg）で使うには？
AGutenbergの「ショートコード」ブロックに [custom_shortcode] をそのまま入力できます。よりネイティブに統合したい場合は、カスタムブロックとして実装する方法もあります。

まとめ

  • 登録：関数＋add_shortcode('名前', '関数')（結果は return）
  • 属性：shortcode_atts() でデフォルト値を定義
  • 出力：esc_html()／esc_url()／esc_attr() でエスケープ
  • 安全：子テーマで編集・名前に接頭辞を付けて衝突回避

登録・属性・エスケープの3ステップを押さえれば、安全に使えるオリジナルのショートコードが作れます。全体像や囲み型はショートコードの全体像をあわせてご覧ください。