WP_Customize_Manager クラスの使い方｜説明・引数・注意点

説明

基本構文

add_action( 'customize_register', function( WP_Customize_Manager $wp_customize ) { ... } )

引数

• add_section()：セクションを追加
• add_setting()：設定を追加
• add_control()：コントロールを追加

戻り値

customize_register フックで受け取ります。

使い方（サンプル）

add_action( 'customize_register', function( $wp_customize ) {
	$wp_customize->add_section( 'my_section', array( 'title' => 'マイ設定' ) );
	$wp_customize->add_setting( 'footer_text', array( 'default' => '' ) );
	$wp_customize->add_control( 'footer_text', array(
		'section' => 'my_section',
		'label'   => 'フッター文言',
		'type'    => 'text',
	) );
} );

注意点

• 保存された値は get_theme_mod() で取得します。
• sanitize_callback を設定に指定して、保存値を検証します。

実務での使いどころ

• テーマのカスタマイザーに、独自の設定（色、ロゴ、テキスト）を、追加するとき。
• customize_register フックの中で、設定・セクション・コントロールを、登録するとき。

よくあるミスと対処

• customize_register フックの外で、操作している。
• sanitize_callback を、指定していない。保存される値が、検証されない。
• transport を postMessage にしたのに、JavaScriptで、プレビューを更新する処理がない。
• 設定のIDと、get_theme_mod() で取得するキーが、違う。

NG例

$wp_customize->add_setting( 'main_color' ); // sanitize_callback がない

OK例

add_action( 'customize_register', function ( $wp_customize ) {
	$wp_customize->add_setting( 'main_color', array(
		'default'           => '#3b82f6',
		'sanitize_callback' => 'sanitize_hex_color',
	) );
	$wp_customize->add_control( new WP_Customize_Color_Control( $wp_customize, 'main_color', array(
		'label'   => 'メインカラー',
		'section' => 'colors',
	) ) );
} );

使い分け早見表

関連項目

get_theme_mod()、set_theme_mod()、sanitize_hex_color()

公式リファレンス：WP_Customize_Manager | WordPress Developer Resources