レガシーウィジェットブロック
Topics
レガシーウィジェットブロックを使用すると、プラグインで登録したサードパーティ製のウィジェットや、従来のウィジェットエディターを使用して追加したウィジェットを追加、編集、プレビューできます。
サードパーティ製のウィジェットを挿入するには、ブロック挿入ツールを使用してレガシーウィジェットブロックを挿入し、ブロックのドロップダウンからウィジェットを選択します。
また、サードパーティ製のウィジェットは、ブロック挿入ツールでウィジェット名を検索し、ウィジェットを選択しても追加できます。このとき、レガシーウィジェットブロックのバリエーションが挿入されます。
レガシーウィジェットブロックと互換性
widget-added イベント
レガシーウィジェットブロックは、カスタマイザーと同様の方法でウィジェットのフォームを表示するため、ほとんどのサードパーティ製ウィジェットと互換性があります。
ウィジェットがフォームで JavaScript を使用する場合、'widget-added' jQuery イベントが documentでトリガーされた後で、DOM にイベントが追加されることは重要です。
たとえば次の例では、ウィジェットは、「Change password」チェックボックスがチェックされると、「Password」フィールドを表示します。
( 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'] ) ) {
// 名前は必須。なければ何も表示するものはない
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以前のバージョンでは、WP_Widget を継承したクラスで、$show_instance_in_rest を true に設定することで、この機能を有効化できました。
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 の投稿エディターのような他のブロックエディター内で、レガシーウィジェットブロックを許可できます。これはデフォルトでは有効になっていません。
まず、レガシーウィジェットに必要なスタイルとスクリプトがページに読み込まれていることを確認します。便利な方法として、ユーザーがウィジェットの管理画面にアクセスした際に通常実行される、すべてのフックを手動で実行します。
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' );
}
} );
次に、@wordpress/widgets パッケージで定義されているregisterLegacyWidgetBlock を使用して、レガシーウィジェットブロックを登録します。
add_action( 'enqueue_block_editor_assets', function() {
wp_enqueue_script( 'wp-widgets' );
wp_add_inline_script( 'wp-widgets', 'wp.widgets.registerLegacyWidgetBlock()' );
} );
最終更新日: