wp_popular_terms_checklist()

💡 云策文档标注

概述

wp_popular_terms_checklist() 函数用于从指定分类法中检索最流行的术语列表。如果 $display 参数为 true，则输出带有复选框的 HTML 列表，并可根据全局 $post_ID 标记关联术语为选中状态。

关键要点

函数从指定分类法中按使用次数降序检索术语，默认返回前 10 个。
当 $display 为 true 时，输出复选框列表，每个术语显示名称和复选框，若与当前文章关联则标记为选中。
返回值为流行术语 ID 的数组，便于进一步处理。
函数内部使用 get_terms() 获取术语，并检查当前用户权限以控制输出。

代码示例

function wp_popular_terms_checklist( $taxonomy, $default_term = 0, $number = 10, $display = true ) {
    $post = get_post();

    if ( $post && $post->ID ) {
        $checked_terms = wp_get_object_terms( $post->ID, $taxonomy, array( 'fields' => 'ids' ) );
    } else {
        $checked_terms = array();
    }

    $terms = get_terms(
        array(
            'taxonomy'     => $taxonomy,
            'orderby'      => 'count',
            'order'        => 'DESC',
            'number'       => $number,
            'hierarchical' => false,
        )
    );

    $tax = get_taxonomy( $taxonomy );

    $popular_ids = array();

    foreach ( (array) $terms as $term ) {
        $popular_ids[] = $term->term_id;

        if ( ! $display ) { // Hack for Ajax use.
            continue;
        }

        $id      = "popular-$taxonomy-$term->term_id";
        $checked = in_array( $term->term_id, $checked_terms, true ) ? 'checked="checked"' : '';
        ?>

        <li id="<?php echo $id; ?>" class="popular-category">
            <label class="selectit">
                <input id="in-<?php echo $id; ?>" type="checkbox" <?php echo $checked; ?> value="<?php echo (int) $term->term_id; ?>" <?php disabled( ! current_user_can( $tax->cap->assign_terms ) ); ?> />
                <?php echo esc_html( apply_filters( 'the_category', $term->name, '', '' ) ); ?>
            </label>
        </li>

        <?php
    }

    return $popular_ids;
}

注意事项

函数自 WordPress 2.5.0 版本引入，主要用于后台管理界面，如文章和链接分类元框。
当 $display 为 false 时，函数仅返回术语 ID 数组，适用于 Ajax 调用等场景。
输出部分包含 HTML 和 PHP 混合代码，需确保在适当上下文中使用。

📄 原文内容

Retrieves a list of the most popular terms from the specified taxonomy.

Description

If the $display argument is true then the elements for a list of checkbox <input> elements labelled with the names of the selected terms is output.
If the $post_ID global is not empty then the terms associated with that post will be marked as checked.

Parameters

$taxonomystringrequired: Taxonomy to retrieve terms from.
$default_termintoptional: Not used.
$numberintoptional: Number of terms to retrieve.

Default:10
$displaybooloptional: Whether to display the list as well.

Default:true

Return

int[] Array of popular term IDs.

Source

function wp_popular_terms_checklist( $taxonomy, $default_term = 0, $number = 10, $display = true ) {

	$post = get_post();
	if ( $post && $post->ID ) {

		$checked_terms = wp_get_object_terms( $post->ID, $taxonomy, array( 'fields' => 'ids' ) );

	} else {

		$checked_terms = array();

	}
	$terms = get_terms(

		array(

			'taxonomy'     => $taxonomy,

			'orderby'      => 'count',

			'order'        => 'DESC',

			'number'       => $number,

			'hierarchical' => false,

		)

	);
	$tax = get_taxonomy( $taxonomy );
	$popular_ids = array();
	foreach ( (array) $terms as $term ) {

		$popular_ids[] = $term->term_id;
		if ( ! $display ) { // Hack for Ajax use.

			continue;

		}
		$id      = "popular-$taxonomy-$term->term_id";

		$checked = in_array( $term->term_id, $checked_terms, true ) ? 'checked="checked"' : '';

		?>
		<li id="<?php echo $id; ?>" class="popular-category">

			<label class="selectit">

				<input id="in-<?php echo $id; ?>" type="checkbox" <?php echo $checked; ?> value="term_id; ?>" cap->assign_terms ) ); ?> />

				name, '', '' ) );

				?>

			</label>

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

		<section class="wp-block-wporg-code-reference-hooks"><h2 id="hooks" class="is-toc-heading wp-block-heading has-heading-5-font-size" tabindex="-1" ><a href="#hooks">Hooks</a></h2> <dl><dt class="wp-block-wporg-code-reference-title has-normal-font-size"><a href="https://developer.wordpress.org/reference/hooks/the_category/"><span class="hook-func">apply_filters</span>( ‘the_category’,  <nobr><span class="arg-type">string</span> <span class="arg-name">$thelist</span></nobr>,  <nobr><span class="arg-type">string</span> <span class="arg-name">$separator</span></nobr>,  <nobr><span class="arg-type">string</span> <span class="arg-name">$parents</span></nobr> )</a></dt><dd><p>Filters the category or list of categories.</p>

</dd></dl></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/functions/disabled/">disabled()</a><code>wp-includes/general-template.php

Outputs the HTML disabled attribute.



wp_get_object_terms()wp-includes/taxonomy.php

Retrieves the terms associated with the given object(s), in the supplied taxonomies.



get_terms()wp-includes/taxonomy.php

Retrieves the terms in a given taxonomy or list of taxonomies.



current_user_can()wp-includes/capabilities.php

Returns whether the current user has the specified capability.



esc_html()wp-includes/formatting.php

Escaping for HTML blocks.



get_taxonomy()wp-includes/taxonomy.php

Retrieves the taxonomy object of $taxonomy.



apply_filters()wp-includes/plugin.php

Calls the callback functions that have been added to a filter hook.



get_post()wp-includes/post.php

Retrieves post data given a post ID or post object.





Show 5 moreShow less

Used by	Description
_wp_ajax_add_hierarchical_term()`wp-admin/includes/ajax-actions.php`	Handles adding a hierarchical term via AJAX.
link_categories_meta_box()`wp-admin/includes/meta-boxes.php`	Displays link categories form fields.
post_categories_meta_box()`wp-admin/includes/meta-boxes.php`	Displays post categories form fields.

Changelog

Version	Description
2.5.0	Introduced.

云策 WordPress 开发者社区

函数文档