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

説明

基本構文

add_settings_field( string $id, string $title, callable $callback, string $page, string $section = 'default', array $args = array() ): void

引数

• $id：項目ID
• $title：ラベル
• $callback：入力欄を出力する関数
• $page：設定ページのスラッグ
• $section：セクションID
• $args：コールバックに渡す引数

戻り値

戻り値はありません。

使い方（サンプル）

add_settings_field( 'my_text', 'テキスト', 'my_text_field', 'my-options', 'my_section' );

注意点

• 出力する入力欄では、esc_attr() で値をエスケープします。

実務での使いどころ

• 設定ページに、入力項目（テキスト、チェックボックスなど）を、追加するとき。

よくあるミスと対処

• 入力欄の name 属性が、登録したオプション名と、合っていない。値が保存されない。
• $section が、add_settings_section() で作ったものと、違う。
• 入力欄の値を、エスケープせずに、出力している。esc_attr() を通す。
• $page が、do_settings_sections() に渡すものと、違う。

NG例

echo '<input name="my_input" value="' . get_option( 'my_option' ) . '">'; // name が違い、エスケープもない

OK例

add_settings_field( 'my_option', '設定値', function () {
	printf(
		'<input type="text" name="my_option" value="%s">',
		esc_attr( get_option( 'my_option', '' ) )
	);
}, 'my-settings', 'main' );

使い分け早見表

関連項目

add_settings_section()、register_setting()

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