2026年5月20日

WordPressプラグインでショートコードを作成する方法

プラグイン関連

はじめに

ショートコードはWordPressの投稿・固定ページに [my_shortcode] 形式で機能を埋め込む仕組みです。add_shortcode() でカスタムショートコードを作成し、エディターから簡単に呼び出せます。

症状・原因

投稿・固定ページに繰り返し使うコンポーネントをショートコード化したい
ショートコードに属性（パラメーター）を渡して表示を変えたい
コンテンツを囲むエンクロージング型ショートコードを作りたい
ショートコードをネストして使いたい

解決手順

ステップ1：基本的なショートコードを作成する

// プラグインファイル または functions.php

// 基本形: [my_button]
add_shortcode('my_button', function(array $atts, ?string $content = null): string {
    // shortcode_atts でデフォルト値とマージ
    $atts = shortcode_atts([
        'text'   => 'クリック',
        'url'    => '#',
        'color'  => 'blue',
        'target' => '_self',
    ], $atts, 'my_button');

    $allowed_colors = ['blue', 'red', 'green', 'gray'];
    $color = in_array($atts['color'], $allowed_colors, true) ? $atts['color'] : 'blue';

    return sprintf(
        '<a href="%s" class="my-btn my-btn--%s" target="%s">%s</a>',
        esc_url($atts['url']),
        esc_attr($color),
        esc_attr($atts['target']),
        esc_html($atts['text'])
    );
});

使用例：

[my_button text="詳細を見る" url="https://example.com" color="red" target="_blank"]

ステップ2：エンクロージング型ショートコード（コンテンツを囲む）

// [my_box]内容[/my_box] 形式
add_shortcode('my_box', function(array $atts, ?string $content = null): string {
    $atts = shortcode_atts([
        'type'  => 'info',   // info / warning / success / error
        'title' => '',
    ], $atts, 'my_box');

    $type  = sanitize_html_class($atts['type']);
    $title = $atts['title'] !== '' ? '<strong>' . esc_html($atts['title']) . '</strong><br>' : '';

    // do_shortcode でネストしたショートコードを処理
    $inner = do_shortcode($content ?? '');

    return sprintf(
        '<div class="my-box my-box--%s">%s%s</div>',
        $type,
        $title,
        wp_kses_post($inner)
    );
});

使用例：

[my_box type="warning" title="注意事項"]
バックアップを取ってから作業してください。
[my_button text="バックアップ方法" url="/backup-guide/"]
[/my_box]

ステップ3：複数のショートコードを組み合わせる（タブUI）

// [tabs] と [tab] の組み合わせ
add_shortcode('tabs', function(array $atts, ?string $content = null): string {
    // グローバルでタブデータを収集
    global $myplugin_tabs;
    $myplugin_tabs = [];

    do_shortcode($content ?? ''); // [tab]ショートコードを実行してデータ収集

    $nav   = '';
    $panes = '';
    foreach ($myplugin_tabs as $i => $tab) {
        $active = $i === 0 ? ' active' : '';
        $nav   .= sprintf('<li class="tab-nav%s"><a href="#tab-%d">%s</a></li>',
            $active, $i, esc_html($tab['label']));
        $panes .= sprintf('<div id="tab-%d" class="tab-pane%s">%s</div>',
            $i, $active, wp_kses_post($tab['content']));
    }

    return '<div class="my-tabs"><ul class="tab-nav-list">' . $nav . '</ul>'
         . '<div class="tab-panes">' . $panes . '</div></div>';
});

add_shortcode('tab', function(array $atts, ?string $content = null): string {
    global $myplugin_tabs;
    $atts = shortcode_atts(['label' => 'タブ'], $atts, 'tab');
    $myplugin_tabs[] = ['label' => $atts['label'], 'content' => $content ?? ''];
    return ''; // 出力なし（tabsが処理）
});

ステップ4：ショートコードをGutenbergブロックとして登録する

// Gutenbergの「ショートコード」ブロック以外に、専用ブロックとして登録
add_action('init', function(): void {
    // server-side-render でPHPのショートコードを呼び出す
    register_block_type('myplugin/button', [
        'attributes'      => [
            'text'  => ['type' => 'string', 'default' => 'クリック'],
            'url'   => ['type' => 'string', 'default' => '#'],
            'color' => ['type' => 'string', 'default' => 'blue'],
        ],
        'render_callback' => function(array $attrs): string {
            return do_shortcode(
                sprintf('[my_button text="%s" url="%s" color="%s"]',
                    esc_attr($attrs['text']),
                    esc_url($attrs['url']),
                    esc_attr($attrs['color'])
                )
            );
        },
    ]);
});

ステップ5：WP-CLIでショートコードをテストする

# 登録済みショートコードの一覧（グローバル変数を確認）
wp eval "global \$shortcode_tags; print_r(array_keys(\$shortcode_tags));"

# ショートコードを直接実行してHTMLを確認
wp eval "echo do_shortcode('[my_button text=\"テスト\" url=\"#\"]');"

# プラグインを有効化してショートコードを確認
wp plugin activate my-plugin
wp eval "echo do_shortcode('[my_box type=\"info\"]テスト内容[/my_box]');"

注意事項

ショートコード名はすべて小文字・アンダースコアのみ使用してください（my_button ✓ / MyButton ✗）
出力は必ず esc_html() / esc_url() / wp_kses_post() でエスケープしてください
ショートコードのコールバックは必ず文字列を return してください（echo は使わない）

まとめ

add_shortcode() と shortcode_atts() でデフォルト値付きのショートコードを作成します。エンクロージング型では do_shortcode($content) でネストを処理し、出力は必ずエスケープします。WP-CLIの wp eval "echo do_shortcode(...)" で動作確認できます。

Post Views: 8