云策 WordPress 开发者社区

类文档

WP_Widget_Block

查看官方原文 ↗
💡 云策文档标注

概述

WP_Widget_Block 是 WordPress 核心类，用于实现一个包含块的部件（Block widget），继承自 WP_Widget。它允许在小部件区域中嵌入块内容，并提供动态类名处理以支持主题向后兼容。

关键要点

  • 继承自 WP_Widget，用于创建和管理块部件。
  • 包含核心方法如 __construct、widget、form、update 等，用于初始化、输出内容、处理设置表单和更新实例。
  • 通过 get_dynamic_classname 方法根据块内容动态生成容器 HTML 类名，以兼容传统小部件。
  • 使用过滤器如 widget_block_content 和 widget_block_dynamic_classname 允许自定义输出和类名。
  • 在自定义器中通过 set_is_wide_widget_in_customizer 方法确保块部件不被视为宽部件。

代码示例

// 示例：WP_Widget_Block 的构造函数
public function __construct() {
    $widget_ops = array(
        'classname'                   => 'widget_block',
        'description'                 => __( 'A widget containing a block.' ),
        'customize_selective_refresh' => true,
        'show_instance_in_rest'       => true,
    );
    $control_ops = array(
        'width'  => 400,
        'height' => 350,
    );
    parent::__construct( 'block', __( 'Block' ), $widget_ops, $control_ops );

    add_filter( 'is_wide_widget_in_customizer', array( $this, 'set_is_wide_widget_in_customizer' ), 10, 2 );
}

注意事项

  • 默认实例包含 'content' 字段，用于存储块内容。
  • 在 update 方法中，根据用户权限处理内容过滤，使用 wp_kses_post 进行安全过滤。
  • 动态类名生成基于块名称，例如 'core/paragraph' 对应 'widget_block widget_text'。
  • 引入于 WordPress 5.8.0 版本。
📄 原文内容

Core class used to implement a Block widget.

Description

See also

Methods

Name Description
WP_Widget_Block::__construct Sets up a new Block widget instance.
WP_Widget_Block::form Outputs the Block widget settings form.
WP_Widget_Block::get_dynamic_classname Calculates the classname to use in the block widget’s container HTML.
WP_Widget_Block::set_is_wide_widget_in_customizer Makes sure no block widget is considered to be wide.
WP_Widget_Block::update Handles updating settings for the current Block widget instance.
WP_Widget_Block::widget Outputs the content for the current Block widget instance.

Source

class WP_Widget_Block extends WP_Widget {


	/**

	 * Default instance.

	 *

	 * @since 5.8.0

	 * @var array

	 */

	protected $default_instance = array(

		'content' => '',

	);


	/**

	 * Sets up a new Block widget instance.

	 *

	 * @since 5.8.0

	 */

	public function __construct() {

		$widget_ops  = array(

			'classname'                   => 'widget_block',

			'description'                 => __( 'A widget containing a block.' ),

			'customize_selective_refresh' => true,

			'show_instance_in_rest'       => true,

		);

		$control_ops = array(

			'width'  => 400,

			'height' => 350,

		);

		parent::__construct( 'block', __( 'Block' ), $widget_ops, $control_ops );


		add_filter( 'is_wide_widget_in_customizer', array( $this, 'set_is_wide_widget_in_customizer' ), 10, 2 );

	}


	/**

	 * Outputs the content for the current Block widget instance.

	 *

	 * @since 5.8.0

	 *

	 * @param array $args     Display arguments including 'before_title', 'after_title',

	 *                        'before_widget', and 'after_widget'.

	 * @param array $instance Settings for the current Block widget instance.

	 */

	public function widget( $args, $instance ) {

		$instance = wp_parse_args( $instance, $this->default_instance );


		echo str_replace(

			'widget_block',

			$this->get_dynamic_classname( $instance['content'] ),

			$args['before_widget']

		);


		/**

		 * Filters the content of the Block widget before output.

		 *

		 * @since 5.8.0

		 *

		 * @param string          $content  The widget content.

		 * @param array           $instance Array of settings for the current widget.

		 * @param WP_Widget_Block $widget   Current Block widget instance.

		 */

		echo apply_filters(

			'widget_block_content',

			$instance['content'],

			$instance,

			$this

		);


		echo $args['after_widget'];

	}


	/**

	 * Calculates the classname to use in the block widget's container HTML.

	 *

	 * Usually this is set to `$this->widget_options['classname']` by

	 * dynamic_sidebar(). In this case, however, we want to set the classname

	 * dynamically depending on the block contained by this block widget.

	 *

	 * If a block widget contains a block that has an equivalent legacy widget,

	 * we display that legacy widget's class name. This helps with theme

	 * backwards compatibility.

	 *

	 * @since 5.8.0

	 *

	 * @param string $content The HTML content of the current block widget.

	 * @return string The classname to use in the block widget's container HTML.

	 */

	private function get_dynamic_classname( $content ) {

		$blocks = parse_blocks( $content );


		$block_name = isset( $blocks[0] ) ? $blocks[0]['blockName'] : null;


		switch ( $block_name ) {

			case 'core/paragraph':

				$classname = 'widget_block widget_text';

				break;

			case 'core/calendar':

				$classname = 'widget_block widget_calendar';

				break;

			case 'core/search':

				$classname = 'widget_block widget_search';

				break;

			case 'core/html':

				$classname = 'widget_block widget_custom_html';

				break;

			case 'core/archives':

				$classname = 'widget_block widget_archive';

				break;

			case 'core/latest-posts':

				$classname = 'widget_block widget_recent_entries';

				break;

			case 'core/latest-comments':

				$classname = 'widget_block widget_recent_comments';

				break;

			case 'core/tag-cloud':

				$classname = 'widget_block widget_tag_cloud';

				break;

			case 'core/categories':

				$classname = 'widget_block widget_categories';

				break;

			case 'core/audio':

				$classname = 'widget_block widget_media_audio';

				break;

			case 'core/video':

				$classname = 'widget_block widget_media_video';

				break;

			case 'core/image':

				$classname = 'widget_block widget_media_image';

				break;

			case 'core/gallery':

				$classname = 'widget_block widget_media_gallery';

				break;

			case 'core/rss':

				$classname = 'widget_block widget_rss';

				break;

			default:

				$classname = 'widget_block';

		}


		/**

		 * The classname used in the block widget's container HTML.

		 *

		 * This can be set according to the name of the block contained by the block widget.

		 *

		 * @since 5.8.0

		 *

		 * @param string $classname  The classname to be used in the block widget's container HTML,

		 *                           e.g. 'widget_block widget_text'.

		 * @param string $block_name The name of the block contained by the block widget,

		 *                           e.g. 'core/paragraph'.

		 */

		return apply_filters( 'widget_block_dynamic_classname', $classname, $block_name );

	}


	/**

	 * Handles updating settings for the current Block widget instance.

	 *

	 * @since 5.8.0


	 * @param array $new_instance New settings for this instance as input by the user via

	 *                            WP_Widget::form().

	 * @param array $old_instance Old settings for this instance.

	 * @return array Settings to save or bool false to cancel saving.

	 */

	public function update( $new_instance, $old_instance ) {

		$instance = array_merge( $this->default_instance, $old_instance );


		if ( current_user_can( 'unfiltered_html' ) ) {

			$instance['content'] = $new_instance['content'];

		} else {

			$instance['content'] = wp_kses_post( $new_instance['content'] );

		}


		return $instance;

	}


	/**

	 * Outputs the Block widget settings form.

	 *

	 * @since 5.8.0

	 *

	 * @see WP_Widget_Custom_HTML::render_control_template_scripts()

	 *

	 * @param array $instance Current instance.

	 */

	public function form( $instance ) {

		$instance = wp_parse_args( (array) $instance, $this->default_instance );

		?>

		<p>

			<label for="<?php echo $this->get_field_id( 'content' ); ?>">


			</label>

			<textarea id="<?php echo $this->get_field_id( 'content' ); ?>" name="<?php echo $this->get_field_name( 'content' ); ?>" rows="6" cols="50" class="widefat code"></textarea>

		</p>

		</pre><p class="wporg-dot-link-list"><a href="https://developer.wordpress.org/reference/files/wp-includes/widgets/class-wp-widget-block.php/">View all references</a> <a href="https://core.trac.wordpress.org/browser/tags/6.9.4/src/wp-includes/widgets/class-wp-widget-block.php#L17">View on Trac</a> <a href="https://github.com/WordPress/wordpress-develop/blob/6.9.4/src/wp-includes/widgets/class-wp-widget-block.php#L17-L232">View on GitHub</a></p></section>


		<section class="wp-block-wporg-code-reference-related" data-nosnippet="true"><h2 id="related" class="is-toc-heading wp-block-heading has-heading-5-font-size" tabindex="-1" ><a href="#related">Related</a></h2> <section style="margin-top:var(--wp--preset--spacing--20)" class="wp-block-wporg-code-table" id="uses"><figure class="wp-block-table "><table><thead><tr><th scope="col">Uses</th><th scope="col">Description</th></tr></thead><tbody><tr class=""><td><a href="https://developer.wordpress.org/reference/classes/wp_widget/">WP_Widget</a><code>wp-includes/class-wp-widget.php


Core base class extended to register widgets.

Changelog

Version Description
5.8.0 Introduced.