add_shortcode() の使い方｜説明・引数・注意点

説明

基本構文

add_shortcode( string $tag, callable $callback ): void

引数

• $tag：ショートコードの名前
• $callback：出力する文字列を返す関数

戻り値

戻り値はありません。

使い方（サンプル）

add_shortcode( 'hello', function( $atts ) {
	$a = shortcode_atts( array( 'name' => 'World' ), $atts );
	return 'Hello, ' . esc_html( $a['name'] ) . '!';
} );

注意点

• コールバックは出力（echo）ではなく、文字列を return します。echo すると、表示位置がずれます。
• 属性は shortcode_atts() で既定値を設定し、出力前にエスケープします。
• init フックなどで登録します。

実務での使いどころ

• 記事の中に、[contact] のような、短いタグを書くだけで、フォームや、ボタンなどを、表示できるようにするとき。
• 引数（属性）を、指定して、表示を、切り替えられるようにするとき。

よくあるミスと対処

• コールバックで、echo している。ショートコードは、値を、return で返す。echo すると、出力が、ページの先頭に出る。
• $atts を、配列だと、決めつけている。属性がないときは、空文字になる。shortcode_atts() で、整える。
• 属性の値を、エスケープせずに、出力している。
• タグの名前に、使えない文字や、大文字を使っている。小文字の英数字・アンダースコアが、安全。

NG例

add_shortcode( 'hello', function ( $atts ) {
	echo 'こんにちは'; // 出力が、ページの先頭に出る
} );

OK例

add_shortcode( 'hello', function ( $atts ) {
	$atts = shortcode_atts( array( 'name' => 'ゲスト' ), $atts, 'hello' );
	return '<p>こんにちは、' . esc_html( $atts['name'] ) . 'さん</p>';
} );

使い分け早見表

関連項目

do_shortcode()、shortcode_atts()、remove_shortcode()

公式リファレンス：add_shortcode() | Function | WordPress Developer Resources