云策 WordPress 开发者社区

类文档

WP_Widget_Links

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

概述

WP_Widget_Links 是 WordPress 核心类，用于实现链接（Links）小工具，继承自 WP_Widget。它管理链接的显示、设置表单和更新逻辑。

关键要点

  • 继承自 WP_Widget，用于创建和管理链接小工具。
  • 提供四个主要方法：__construct（构造函数）、widget（输出内容）、update（处理设置更新）和 form（输出设置表单）。
  • 使用 wp_list_bookmarks() 函数显示链接，支持过滤器和多种显示选项。
  • 设置包括显示图像、名称、描述、评分、分类、排序方式和限制数量。

代码示例

// 示例：WP_Widget_Links 的 widget 方法核心部分
$widget_links_args = array(
    'title_before'     => $args['before_title'],
    'title_after'      => $args['after_title'],
    'category_before'  => $before_widget,
    'category_after'   => $args['after_widget'],
    'show_images'      => $show_images,
    'show_description' => $show_description,
    'show_name'        => $show_name,
    'show_rating'      => $show_rating,
    'category'         => $category,
    'class'            => 'linkcat widget',
    'orderby'          => $orderby,
    'order'            => $order,
    'limit'            => $limit,
);
wp_list_bookmarks( apply_filters( 'widget_links_args', $widget_links_args, $instance ) );

注意事项

  • widget 方法使用 apply_filters 允许通过 'widget_links_args' 钩子自定义参数。
  • update 方法验证输入，确保 orderby 值有效，并处理整数类型转换。
  • form 方法生成 HTML 表单，使用 get_field_id 和 get_field_name 确保唯一性。
  • 自 WordPress 2.8.0 引入，是核心小工具系统的一部分。
📄 原文内容

Core class used to implement a Links widget.

Description

See also

Methods

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

Source

class WP_Widget_Links extends WP_Widget {


	/**

	 * Sets up a new Links widget instance.

	 *

	 * @since 2.8.0

	 */

	public function __construct() {

		$widget_ops = array(

			'description'                 => __( 'Your blogroll' ),

			'customize_selective_refresh' => true,

		);

		parent::__construct( 'links', __( 'Links' ), $widget_ops );

	}


	/**

	 * Outputs the content for the current Links 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 Links widget instance.

	 */

	public function widget( $args, $instance ) {

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

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

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

		$show_images      = isset( $instance['images'] ) ? $instance['images'] : true;

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

		$orderby          = isset( $instance['orderby'] ) ? $instance['orderby'] : 'name';

		$order            = 'rating' === $orderby ? 'DESC' : 'ASC';

		$limit            = isset( $instance['limit'] ) ? $instance['limit'] : -1;


		$before_widget = preg_replace( '/ id="[^"]*"/', ' id="%id"', $args['before_widget'] );


		$widget_links_args = array(

			'title_before'     => $args['before_title'],

			'title_after'      => $args['after_title'],

			'category_before'  => $before_widget,

			'category_after'   => $args['after_widget'],

			'show_images'      => $show_images,

			'show_description' => $show_description,

			'show_name'        => $show_name,

			'show_rating'      => $show_rating,

			'category'         => $category,

			'class'            => 'linkcat widget',

			'orderby'          => $orderby,

			'order'            => $order,

			'limit'            => $limit,

		);


		/**

		 * Filters the arguments for the Links widget.

		 *

		 * @since 2.6.0

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

		 *

		 * @see wp_list_bookmarks()

		 *

		 * @param array $widget_links_args An array of arguments to retrieve the links list.

		 * @param array $instance          The settings for the particular instance of the widget.

		 */

		wp_list_bookmarks( apply_filters( 'widget_links_args', $widget_links_args, $instance ) );

	}


	/**

	 * Handles updating settings for the current Links 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 ) {

		$new_instance = (array) $new_instance;

		$instance     = array(

			'images'      => 0,

			'name'        => 0,

			'description' => 0,

			'rating'      => 0,

		);

		foreach ( $instance as $field => $val ) {

			if ( isset( $new_instance[ $field ] ) ) {

				$instance[ $field ] = 1;

			}

		}


		$instance['orderby'] = 'name';

		if ( in_array( $new_instance['orderby'], array( 'name', 'rating', 'id', 'rand' ), true ) ) {

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

		}


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

		$instance['limit']    = ! empty( $new_instance['limit'] ) ? (int) $new_instance['limit'] : -1;


		return $instance;

	}


	/**

	 * Outputs the settings form for the Links widget.

	 *

	 * @since 2.8.0

	 *

	 * @param array $instance Current settings.

	 */

	public function form( $instance ) {


		// Defaults.

		$instance  = wp_parse_args(

			(array) $instance,

			array(

				'images'      => true,

				'name'        => true,

				'description' => false,

				'rating'      => false,

				'category'    => false,

				'orderby'     => 'name',

				'limit'       => -1,

			)

		);

		$link_cats = get_terms( array( 'taxonomy' => 'link_category' ) );

		$limit     = (int) $instance['limit'];

		if ( ! $limit ) {

			$limit = -1;

		}

		?>

		<p>

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

			<select class="widefat" id="<?php echo $this->get_field_id( 'category' ); ?>" name="<?php echo $this->get_field_name( 'category' ); ?>">

				<option value=""></option>


					<option value="<?php echo (int) $link_cat->term_id; ?>" <?php selected( $instance['category'], $link_cat->term_id ); ?>>

						name ); ?>

					</option>


			</select>

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

			<select name="<?php echo $this->get_field_name( 'orderby' ); ?>" id="<?php echo $this->get_field_id( 'orderby' ); ?>" class="widefat">

				<option value="name"<?php selected( $instance['orderby'], 'name' ); ?>></option>

				<option value="rating"<?php selected( $instance['orderby'], 'rating' ); ?>></option>

				<option value="id"<?php selected( $instance['orderby'], 'id' ); ?>></option>

				<option value="rand"<?php selected( $instance['orderby'], 'rand' ); ?>></option>

			</select>

		</p>


		<p>

			<input class="checkbox" type="checkbox"<?php checked( $instance['images'], true ); ?> id="get_field_id( 'images' ); ?>" name="get_field_name( 'images' ); ?>" />

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

			<br />


			<input class="checkbox" type="checkbox"<?php checked( $instance['name'], true ); ?> id="get_field_id( 'name' ); ?>" name="get_field_name( 'name' ); ?>" />

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

			<br />


			<input class="checkbox" type="checkbox"<?php checked( $instance['description'], true ); ?> id="get_field_id( 'description' ); ?>" name="get_field_name( 'description' ); ?>" />

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

			<br />


			<input class="checkbox" type="checkbox"<?php checked( $instance['rating'], true ); ?> id="get_field_id( 'rating' ); ?>" name="get_field_name( 'rating' ); ?>" />

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

		</p>


		<p>

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

			<input id="<?php echo $this->get_field_id( 'limit' ); ?>" name="<?php echo $this->get_field_name( 'limit' ); ?>" type="text" value="<?php echo ( -1 !== $limit ) ? (int) $limit : ''; ?>" size="3" />

		</p>

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