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

説明

基本構文

shortcode_atts( array $pairs, array $atts, string $shortcode = '' ): array

引数

• $pairs：既定値の配列
• $atts：ユーザーが指定した属性
• $shortcode：ショートコード名（フィルター用）

戻り値

マージ後の配列。定義されていない属性は取り除かれます。

使い方（サンプル）

$a = shortcode_atts( array( 'color' => 'red' ), $atts );

注意点

• $pairs に定義していない属性は無視されます。
• 属性名は小文字に変換されて渡されます。

実務での使いどころ

• ショートコードの属性に、既定値を設定するとき。
• 許可する属性だけに、絞るとき。

よくあるミスと対処

• 指定した $pairs にない属性は、取り除かれる。使いたい属性は、$pairs に書いておく。
• 属性名は、小文字になる。Name="x" は、name として扱われる。
• $shortcode を指定していない。shortcode_atts_{shortcode} フィルターが、使えない。
• 属性の値は、文字列。数値や真偽値に、変換してから使う。

NG例

$atts = shortcode_atts( array( 'name' => 'ゲスト' ), $atts );
echo $atts['color']; // $pairs に無い属性は、取り除かれる

OK例

$atts = shortcode_atts( array(
	'name'  => 'ゲスト',
	'color' => 'blue',
), $atts, 'hello' );

使い分け早見表

関連項目

add_shortcode()、wp_parse_args()

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