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

説明

基本構文

class My_Widget extends WP_Widget

引数

• widget( $args, $instance )：画面への出力
• form( $instance )：管理画面の設定フォーム
• update( $new, $old )：保存時の処理

戻り値

register_widget() で登録して使います。

使い方（サンプル）

class My_Widget extends WP_Widget {
	public function __construct() {
		parent::__construct( 'my_widget', 'マイウィジェット' );
	}
	public function widget( $args, $instance ) {
		echo $args['before_widget'] . 'Hello' . $args['after_widget'];
	}
}
add_action( 'widgets_init', function() {
	register_widget( 'My_Widget' );
} );

注意点

• 出力値は必ずエスケープします。
• update() では、受け取った値をサニタイズして返します。
• ブロックウィジェット画面では、旧ウィジェットが「レガシーウィジェット」ブロックとして扱われます。

実務での使いどころ

• 独自のウィジェットを、作るとき（WP_Widget を継承して、widget()・form()・update() を実装する）。

よくあるミスと対処

• クラスを作っただけで、register_widget() で、登録していない。
• widget() の中で、$args['before_widget'] と $args['after_widget'] を、出力していない。サイドバーの設定した、HTMLが、反映されない。
• update() の中で、入力値を、サニタイズしていない。
• widget() の中で、値を、エスケープせずに、出力している。

NG例

public function widget( $args, $instance ) {
	echo $instance['title']; // エスケープがなく、前後の HTML もない
}

OK例

public function widget( $args, $instance ) {
	echo $args['before_widget'];
	echo esc_html( $instance['title'] );
	echo $args['after_widget'];
}
public function update( $new, $old ) {
	return array( 'title' => sanitize_text_field( $new['title'] ) );
}

使い分け早見表

関連項目

register_widget()、register_sidebar()

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