云策 WordPress 开发者社区

类文档

WP_Widget_Recent_Posts

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

概述

WP_Widget_Recent_Posts 是 WordPress 核心类，用于实现显示最近文章的挂件。它继承自 WP_Widget，提供配置、更新和渲染功能。

关键要点

  • 继承自 WP_Widget，用于创建和管理最近文章挂件。
  • 包含四个主要方法：__construct（构造函数）、form（输出设置表单）、update（处理设置更新）和 widget（输出挂件内容）。
  • 使用 WP_Query 获取文章，支持自定义标题、文章数量和显示日期选项。
  • 提供过滤器如 widget_posts_args 和 widget_title，允许开发者自定义查询参数和标题。

代码示例

public function __construct() {
    $widget_ops = array(
        'classname'                   => 'widget_recent_entries',
        'description'                 => __( 'Your site’s most recent Posts.' ),
        'customize_selective_refresh' => true,
        'show_instance_in_rest'       => true,
    );
    parent::__construct( 'recent-posts', __( 'Recent Posts' ), $widget_ops );
    $this->alt_option_name = 'widget_recent_entries';
}

注意事项

  • 挂件设置包括标题、文章数量（默认5篇）和是否显示日期，更新时进行数据清理和验证。
  • 在 widget 方法中，使用 WP_Query 查询文章，无文章时直接返回，避免输出空内容。
  • 表单输出使用 get_field_id 和 get_field_name 方法确保唯一性和安全性。
📄 原文内容

Core class used to implement a Recent Posts widget.

Description

See also

Methods

Name Description
WP_Widget_Recent_Posts::__construct Sets up a new Recent Posts widget instance.
WP_Widget_Recent_Posts::form Outputs the settings form for the Recent Posts widget.
WP_Widget_Recent_Posts::update Handles updating the settings for the current Recent Posts widget instance.
WP_Widget_Recent_Posts::widget Outputs the content for the current Recent Posts widget instance.

Source

class WP_Widget_Recent_Posts extends WP_Widget {


	/**

	 * Sets up a new Recent Posts widget instance.

	 *

	 * @since 2.8.0

	 */

	public function __construct() {

		$widget_ops = array(

			'classname'                   => 'widget_recent_entries',

			'description'                 => __( 'Your site’s most recent Posts.' ),

			'customize_selective_refresh' => true,

			'show_instance_in_rest'       => true,

		);

		parent::__construct( 'recent-posts', __( 'Recent Posts' ), $widget_ops );

		$this->alt_option_name = 'widget_recent_entries';

	}


	/**

	 * Outputs the content for the current Recent Posts widget instance.

	 *

	 * @since 2.8.0

	 *

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

	 *                        'before_widget', and 'after_widget'.

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

	 */

	public function widget( $args, $instance ) {

		if ( ! isset( $args['widget_id'] ) ) {

			$args['widget_id'] = $this->id;

		}


		$default_title = __( 'Recent Posts' );

		$title         = ( ! empty( $instance['title'] ) ) ? $instance['title'] : $default_title;


		/** This filter is documented in wp-includes/widgets/class-wp-widget-pages.php */

		$title = apply_filters( 'widget_title', $title, $instance, $this->id_base );


		$number = ( ! empty( $instance['number'] ) ) ? absint( $instance['number'] ) : 5;

		if ( ! $number ) {

			$number = 5;

		}

		$show_date = isset( $instance['show_date'] ) ? $instance['show_date'] : false;


		$r = new WP_Query(

			/**

			 * Filters the arguments for the Recent Posts widget.

			 *

			 * @since 3.4.0

			 * @since 4.9.0 Added the `$instance` parameter.

			 *

			 * @see WP_Query::get_posts()

			 *

			 * @param array $args     An array of arguments used to retrieve the recent posts.

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

			 */

			apply_filters(

				'widget_posts_args',

				array(

					'posts_per_page'      => $number,

					'no_found_rows'       => true,

					'post_status'         => 'publish',

					'ignore_sticky_posts' => true,

				),

				$instance

			)

		);


		if ( ! $r->have_posts() ) {

			return;

		}

		?>


		';

		}

		?>


		<ul>

			posts as $recent_post ) : ?>

				ID );

				$title        = ( ! empty( $post_title ) ) ? $post_title : __( '(no title)' );

				$aria_current = '';


				if ( get_queried_object_id() === $recent_post->ID ) {

					$aria_current = ' aria-current="page"';

				}

				?>

				<li>

					<a href="<?php the_permalink( $recent_post->ID ); ?>"<?php echo $aria_current; ?>></a>


						<span class="post-date">ID ); ?></span>


				</li>


		</ul>


		';

		}


		echo $args['after_widget'];

	}


	/**

	 * Handles updating the settings for the current Recent Posts widget instance.

	 *

	 * @since 2.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 Updated settings to save.

	 */

	public function update( $new_instance, $old_instance ) {

		$instance              = $old_instance;

		$instance['title']     = sanitize_text_field( $new_instance['title'] );

		$instance['number']    = (int) $new_instance['number'];

		$instance['show_date'] = isset( $new_instance['show_date'] ) ? (bool) $new_instance['show_date'] : false;

		return $instance;

	}


	/**

	 * Outputs the settings form for the Recent Posts widget.

	 *

	 * @since 2.8.0

	 *

	 * @param array $instance Current settings.

	 */

	public function form( $instance ) {

		$title     = isset( $instance['title'] ) ? esc_attr( $instance['title'] ) : '';

		$number    = isset( $instance['number'] ) ? absint( $instance['number'] ) : 5;

		$show_date = isset( $instance['show_date'] ) ? (bool) $instance['show_date'] : false;

		?>

		<p>

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

			<input class="widefat" id="<?php echo $this->get_field_id( 'title' ); ?>" name="<?php echo $this->get_field_name( 'title' ); ?>" type="text" value="<?php echo $title; ?>" />

		</p>


		<p>

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

			<input class="tiny-text" id="<?php echo $this->get_field_id( 'number' ); ?>" name="<?php echo $this->get_field_name( 'number' ); ?>" type="number" step="1" min="1" value="<?php echo $number; ?>" size="3" />

		</p>


		<p>

			<input class="checkbox" type="checkbox"<?php checked( $show_date ); ?> id="get_field_id( 'show_date' ); ?>" name="get_field_name( 'show_date' ); ?>" />

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

		</p>

		</pre><p class="wporg-dot-link-list"><a href="https://developer.wordpress.org/reference/files/wp-includes/widgets/class-wp-widget-recent-posts.php/">View all references</a> <a href="https://core.trac.wordpress.org/browser/tags/6.9.4/src/wp-includes/widgets/class-wp-widget-recent-posts.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-recent-posts.php#L17-L184">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
2.8.0 Introduced.