ワードプレスのshortcode_atts関数の使用方法・解説

概要

shortcode_atts 関数は、WordPress のショートコードで使われる属性値を処理し、無効な属性値を除外するために使用されます。この関数を使用することで、デフォルトの属性設定を持ちながら、ユーザーが提供した属性を簡単に扱うことができます。主に、以下のような機能実装時に用いられます。

1. ショートコードのデフォルト設定を簡単に作成する
2. 属性が正しく設定されているかのバリデーション
3. ショートコードを柔軟にカスタマイズできる
4. 属性の型や値の検証（必要に応じて）
5. ユーザーが指定した属性のみを取得する
6. ショートコードの引数に対してデフォルト値を適用する
7. コードの保守性を向上させる
8. 他の開発者とのコラボレーションを容易にする

構文

shortcode_atts( $pairs, $atts, $shortcode );

パラメータ

• $pairs (array): デフォルト属性とその値の配列。
• $atts (array): ユーザーが提供した属性の配列。
• $shortcode (string|false): ショートコード名（省略可能）。

戻り値

• (array): デフォルト属性とユーザー提供の属性がマージされた配列。

関連する関数

• shortcode_parse_atts
• add_shortcode

使用可能なバージョン

• WordPress 2.5 以降

コアファイルのパス

• wp-includes/shortcodes.php

この関数のアクションでの使用可能性

アクション名	使用例
mu_plugin_loaded
registered_post_type
plugins_loaded
wp_roles_init
setup_theme
after_setup_theme
set_current_user
init
register_sidebar
wp_loaded
send_headers
parse_query
pre_get_posts
wp
template_redirect
get_header
wp_head

サンプルコード

サンプルコード 1: ショートコードのデフォルト設定を作成

function my_shortcode( $atts ) {
    $atts = shortcode_atts(
        array(
            'color' => 'red',
            'size'  => 'medium'
        ), 
        $atts
    );
    return "Color: {$atts['color']}, Size: {$atts['size']}";
}
add_shortcode( 'my_shortcode', 'my_shortcode' );

このサンプルコードでは、my_shortcode というショートコードを定義し、デフォルト属性として color と size を設定しています。ユーザーが属性を提供しなかった場合、デフォルト値が使用されます。

サンプルコード 2: 属性のバリデーション

function custom_button_shortcode( $atts ) {
    $atts = shortcode_atts(
        array(
            'url'  => '#',
            'text' => 'Click Here'
        ), 
        $atts
    );

    if ( ! filter_var( $atts['url'], FILTER_VALIDATE_URL ) ) {
        return 'Invalid URL';
    }

    return '<a href="' . esc_url( $atts['url'] ) . '">' . esc_html( $atts['text'] ) . '</a>';
}
add_shortcode( 'custom_button', 'custom_button_shortcode' );

このサンプルでは、custom_button ショートコードを定義し、URL のバリデーションを行っています。無効な URL が提供された場合はエラーメッセージを返します。

サンプルコード 3: ユーザー提供の属性のみを取得

function my_alert_shortcode( $atts ) {
    $atts = shortcode_atts(
        array(
            'message' => 'Default Alert'
        ),
        $atts
    );

    return '<script>alert("' . esc_js( $atts['message'] ) . '");</script>';
}
add_shortcode( 'my_alert', 'my_alert_shortcode' );

この例では、my_alert ショートコードを作成し、ユーザーが指定したメッセージをアラートとして表示しています。

サンプルコード 4: 複数の属性を扱う

function styled_div_shortcode( $atts ) {
    $atts = shortcode_atts(
        array(
            'class' => 'default-class',
            'content' => 'Hello World'
        ),
        $atts
    );

    return '<div class="' . esc_attr( $atts['class'] ) . '">' . esc_html( $atts['content'] ) . '</div>';
}
add_shortcode( 'styled_div', 'styled_div_shortcode' );

このサンプルでは、styled_div ショートコードを定義し、複数の属性を扱っています。class と content の属性を使って、スタイル付きの DIV を生成します。

サンプルコード 5: デフォルト値の動的設定

function dynamic_shortcode( $atts ) {
    $atts = shortcode_atts(
        array(
            'value' => get_option('default_value', 'Default Value')
        ),
        $atts
    );

    return 'The value is: ' . esc_html( $atts['value'] );
}
add_shortcode( 'dynamic', 'dynamic_shortcode' );

このコードでは、dynamic ショートコードを作成し、get_option を使って WordPress のオプションからデフォルト値を取得しています。これにより、デフォルト値を動的に設定できます。