ウィジェット - レガシーウィジェットブロックについて（About the Legacy Widget block）

レガシーウィジェットブロックとの互換性
他のブロックエディターでのレガシーウィジェットブロックの使用（高度な）

レガシーウィジェットブロックとの互換性

ウィジェット追加イベント

レガシーウィジェットブロックは、ウィジェットのフォームをカスタマイザーに似た方法で表示し、ほとんどのサードパーティウィジェットと互換性があります。

ウィジェットがそのフォームでJavaScriptを使用している場合、'widget-added' jQueryイベントがdocumentでトリガーされた後にDOMにイベントを追加することが重要です。

例えば、ウィジェットは「パスワード変更」チェックボックスがチェックされているときに「パスワード」フィールドを表示したいかもしれません。

( function ( $ ) {
   $( document ).on( 'widget-added', function ( $event, $control ) {
   $control.find( '.change-password' ).on( 'change', function () {
   var isChecked = $( this ).prop( 'checked' );
   $control.find( '.password' ).toggleClass( 'hidden', ! isChecked );
   } );
   } );
} )( jQuery );

ウィジェットのすべてのイベントハンドラーは、widget-addedコールバック内で追加されることに注意してください。

「プレビューは利用できません。」の表示

レガシーウィジェットブロックは、レガシーウィジェットブロックが選択されていないときにウィジェットのプレビューを表示します。

ウィジェットのwidget()関数が何もレンダリングしないか、空のHTML要素のみをレンダリングする場合、レガシーウィジェットブロックによって「プレビューは利用できません。」というメッセージが自動的に表示されます。

ウィジェットは、プレビューを表示する必要がない場合にwidget()から早期に戻ることでこれを利用できます。

class ExampleWidget extends WP_Widget {
   ...
   public function widget( $instance ) {
   if ( ! isset( $instance['name'] ) ) {
   // Name is required, so display nothing if we don't have it.
   return;
   }
   ?>
   <h3>Name: <?php echo esc_html( $instance['name'] ); ?></h3>
   ...
   <?php
   }
   ...
}

ブロックへの移行を許可する

特定のウィジェットを含むレガシーウィジェットブロックをブロックまたは複数のブロックに簡単に移行できるようにユーザーに許可できます。これにより、プラグインの著者は、より直感的で多くの場所で使用できるブロックにウィジェットを段階的に廃止することができます。

以下の手順でこれを行う方法を示します。

1) ウィジェットのインスタンスをREST APIに表示する

まず、WordPressにウィジェットのインスタンス配列をREST APIに表示することが許可されていることを伝える必要があります。

これは安全に行うことができます:

あなたのウィジェットが$instanceに保存するすべての値がJSONとして表現できることを知っている場合; そして
あなたのウィジェットが$instanceにユーザーから隠すべきプライベートデータを保存していないことを知っている場合。

安全であれば、ウィジェットを登録するときにshow_instance_in_restというウィジェットオプションを含め、その値をtrueに設定します。

class ExampleWidget extends WP_Widget {
   ...
   /**
     * Sets up the widget
   */
   public function __construct() {
   $widget_ops = array(
   // ...other options here
   'show_instance_in_rest' => true,
   // ...other options here
   );
   parent::__construct( 'example_widget', 'ExampleWidget', $widget_ops );
   }
   ...
}

これにより、ブロックエディターや他のREST APIクライアントは、REST APIレスポンス内のinstance.rawにアクセスすることでウィジェットのインスタンス配列を見ることができます。

WordPressのバージョン5.8.0以前では、$show_instance_in_restをtrueに設定することでこの機能を有効にすることができましたWP_Widgetを拡張するクラス内で。

class ExampleWidget extends WP_Widget {
   ...
   public $show_instance_in_rest = true;
   ...
}

これは、ウィジェットオプションメソッドのために非推奨となりました。

2) ブロック変換を追加する

次に、レガシーウィジェットブロックを含むウィジェットを何に置き換えるかをブロックエディターに指示するブロック変換を定義できます。

これは、ウィジェットの定義にJavaScriptコードを追加することで行います。この例では、IDが'example_widget'のウィジェットを'example/block'という名前のブロックに変換する変換を定義します。

transforms: {
   from: [
   {
   type: 'block',
   blocks: [ 'core/legacy-widget' ],
   isMatch: ( { idBase, instance } ) => {
   if ( ! instance?.raw ) {
   // Can't transform if raw instance is not shown in REST API.
   return false;
   }
   return idBase === 'example_widget';
   },
   transform: ( { instance } ) => {
   return createBlock( 'example/block', {
   name: instance.raw.name,
   } );
   },
   },
   ]
},

3) レガシーウィジェットブロックからウィジェットを隠す

最後の仕上げとして、レガシーウィジェットブロックに「ウィジェットを選択」ドロップダウンとブロックインサータからウィジェットを隠すように指示できます。これにより、ユーザーはウィジェットを置き換えるブロックを使用することが奨励されます。

これはwidget_types_to_hide_from_legacy_widget_blockフィルターを使用して行うことができます。

function hide_example_widget( $widget_types ) {
   $widget_types[] = 'example_widget';
   return $widget_types;
}
add_filter( 'widget_types_to_hide_from_legacy_widget_block', 'hide_example_widget' );

他のブロックエディターでのレガシーウィジェットブロックの使用（高度な）

オプションで、WordPressの投稿エディターなどの他のブロックエディターでレガシーウィジェットブロックを許可できます。これはデフォルトでは有効になっていません。

まず、レガシーウィジェットが必要とするスタイルとスクリプトがページに読み込まれていることを確認します。これを行う便利な方法は、ユーザーがウィジェットのWP管理画面に移動するときに通常実行されるすべてのフックを手動で実行することです。

add_action( 'admin_print_styles', function() {
   if ( get_current_screen()->is_block_editor() ) {
   do_action( 'admin_print_styles-widgets.php' );
   }
} );
add_action( 'admin_print_scripts', function() {
   if ( get_current_screen()->is_block_editor() ) {
   do_action( 'load-widgets.php' );
   do_action( 'widgets.php' );
   do_action( 'sidebar_admin_setup' );
   do_action( 'admin_print_scripts-widgets.php' );
   }
} );
add_action( 'admin_print_footer_scripts', function() {
   if ( get_current_screen()->is_block_editor() ) {
   do_action( 'admin_print_footer_scripts-widgets.php' );
   }
} );
add_action( 'admin_footer', function() {
   if ( get_current_screen()->is_block_editor() ) {
   do_action( 'admin_footer-widgets.php' );
   }
} );

次に、registerLegacyWidgetBlockを使用してレガシーウィジェットブロックを登録します。これは@wordpress/widgetsパッケージで定義されています。

add_action( 'enqueue_block_editor_assets', function() {
   wp_enqueue_script( 'wp-widgets' );
   wp_add_inline_script( 'wp-widgets', 'wp.widgets.registerLegacyWidgetBlock()' );
} );