云策 WordPress 开发者社区

函数文档

post_categories_meta_box()

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

概述

post_categories_meta_box() 是 WordPress 核心函数，用于在文章编辑页面显示分类元框的表单字段。它处理分类选择、添加新分类和权限检查，支持自定义分类法。

关键要点

  • 函数接受两个参数：$post（WP_Post 对象）和 $box（元框参数数组），其中 $box['args'] 可包含 'taxonomy' 参数，默认为 'category'。
  • 输出包含分类选项卡（所有分类和常用分类）、分类复选框列表、添加新分类表单（基于用户权限），并调用 wp_dropdown_categories() 等辅助函数。
  • 使用 apply_filters('post_edit_category_parent_dropdown_args', $parent_dropdown_args) 钩子过滤父级下拉菜单参数，增强可定制性。
  • 依赖多个核心函数，如 wp_terms_checklist()、wp_dropdown_categories()、current_user_can() 等，确保功能完整和安全。

代码示例

function post_categories_meta_box( $post, $box ) {
    $defaults = array( 'taxonomy' => 'category' );
    if ( ! isset( $box['args'] ) || ! is_array( $box['args'] ) ) {
        $args = array();
    } else {
        $args = $box['args'];
    }
    $parsed_args = wp_parse_args( $args, $defaults );
    $tax_name    = esc_attr( $parsed_args['taxonomy'] );
    $taxonomy    = get_taxonomy( $parsed_args['taxonomy'] );
    // 输出 HTML 和 PHP 代码，包括分类列表和表单
}

注意事项

  • 确保 $post 参数是有效的 WP_Post 对象，否则可能导致错误。
  • 通过 $box['args'] 自定义分类法时，需确保分类法已注册，否则函数可能无法正常工作。
  • 添加新分类功能受 current_user_can('edit_terms') 权限控制，开发时应考虑用户角色和权限设置。
  • 使用 esc_attr() 和 esc_html() 进行输出转义，以防止 XSS 攻击，提升安全性。
📄 原文内容

Displays post categories form fields.

Parameters

$postWP_Postrequired
Current post object.
$boxarrayrequired
Categories meta box arguments.
  • id string
    Meta box 'id' attribute.
  • title string
    Meta box title.
  • callback callable
    Meta box display callback.
  • args array
    Extra meta box arguments.
    • taxonomy string
      Taxonomy. Default 'category'.

Source

function post_categories_meta_box( $post, $box ) {
	$defaults = array( 'taxonomy' => 'category' );
	if ( ! isset( $box['args'] ) || ! is_array( $box['args'] ) ) {
		$args = array();
	} else {
		$args = $box['args'];
	}
	$parsed_args = wp_parse_args( $args, $defaults );
	$tax_name    = esc_attr( $parsed_args['taxonomy'] );
	$taxonomy    = get_taxonomy( $parsed_args['taxonomy'] );
	?>
	<div id="taxonomy-<?php echo $tax_name; ?>" class="categorydiv">
		<ul id="<?php echo $tax_name; ?>-tabs" class="category-tabs">
			<li class="tabs"><a href="#<?php echo $tax_name; ?>-all">labels->all_items; ?></a></li>
			<li class="hide-if-no-js"><a href="#<?php echo $tax_name; ?>-pop">labels->most_used ); ?></a></li>
		</ul>

		<div id="<?php echo $tax_name; ?>-pop" class="tabs-panel" style="display: none;">
			<ul id="<?php echo $tax_name; ?>checklist-pop" class="categorychecklist form-no-clear" >
				
			</ul>
		</div>

		<div id="<?php echo $tax_name; ?>-all" class="tabs-panel">
			";
			?>
			<ul id="<?php echo $tax_name; ?>checklist" data-wp-lists="list:<?php echo $tax_name; ?>" class="categorychecklist form-no-clear">
				ID,
					array(
						'taxonomy'     => $tax_name,
						'popular_cats' => $popular_ids,
					)
				);
				?>
			</ul>
		</div>
	cap->edit_terms ) ) : ?>
			<div id="<?php echo $tax_name; ?>-adder" class="wp-hidden-children">
				<a id="<?php echo $tax_name; ?>-add-toggle" href="#<?php echo $tax_name; ?>-add" class="hide-if-no-js taxonomy-add-new">
					labels->add_new_item );
					?>
				</a>
				<p id="<?php echo $tax_name; ?>-add" class="category-add wp-hidden-child">
					<label class="screen-reader-text" for="new<?php echo $tax_name; ?>">labels->add_new_item; ?></label>
					<input type="text" name="new<?php echo $tax_name; ?>" id="new<?php echo $tax_name; ?>" class="form-required form-input-tip" value="<?php echo esc_attr( $taxonomy->labels->new_item_name ); ?>" aria-required="true" />
					<label class="screen-reader-text" for="new<?php echo $tax_name; ?>_parent">
						labels->parent_item_colon; ?>
					</label>
					 $tax_name,
						'hide_empty'       => 0,
						'name'             => 'new' . $tax_name . '_parent',
						'orderby'          => 'name',
						'hierarchical'     => 1,
						'show_option_none' => '— ' . $taxonomy->labels->parent_item . ' —',
					);

					/**
					 * Filters the arguments for the taxonomy parent dropdown on the Post Edit page.
					 *
					 * @since 4.4.0
					 *
					 * @param array $parent_dropdown_args {
					 *     Optional. Array of arguments to generate parent dropdown.
					 *
					 *     @type string   $taxonomy         Name of the taxonomy to retrieve.
					 *     @type bool     $hide_if_empty    True to skip generating markup if no
					 *                                      categories are found. Default 0.
					 *     @type string   $name             Value for the 'name' attribute
					 *                                      of the select element.
					 *                                      Default "new{$tax_name}_parent".
					 *     @type string   $orderby          Which column to use for ordering
					 *                                      terms. Default 'name'.
					 *     @type bool|int $hierarchical     Whether to traverse the taxonomy
					 *                                      hierarchy. Default 1.
					 *     @type string   $show_option_none Text to display for the "none" option.
					 *                                      Default "— {$parent} —",
					 *                                      where `$parent` is 'parent_item'
					 *                                      taxonomy label.
					 * }
					 */
					$parent_dropdown_args = apply_filters( 'post_edit_category_parent_dropdown_args', $parent_dropdown_args );

					wp_dropdown_categories( $parent_dropdown_args );
					?>
					<input type="button" id="<?php echo $tax_name; ?>-add-submit" data-wp-lists="add:<?php echo $tax_name; ?>checklist:<?php echo $tax_name; ?>-add" class="button category-add-submit" value="<?php echo esc_attr( $taxonomy->labels->add_new_item ); ?>" />
					
					<span id="<?php echo $tax_name; ?>-ajax-response"></span>
				</p>
			</div>
		
	</div>
	</pre><p class="wporg-dot-link-list"><a href="https://developer.wordpress.org/reference/files/wp-admin/includes/meta-boxes.php/">View all references</a> <a href="https://core.trac.wordpress.org/browser/tags/6.9.4/src/wp-admin/includes/meta-boxes.php#L635">View on Trac</a> <a href="https://github.com/WordPress/wordpress-develop/blob/6.9.4/src/wp-admin/includes/meta-boxes.php#L635-L736">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/post_edit_category_parent_dropdown_args/"><span class="hook-func">apply_filters</span>( ‘post_edit_category_parent_dropdown_args’,  <nobr><span class="arg-type">array</span> <span class="arg-name">$parent_dropdown_args</span></nobr> )</a></dt><dd><p>Filters the arguments for the taxonomy parent dropdown on the Post Edit page.</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/wp_popular_terms_checklist/">wp_popular_terms_checklist()</a><code>wp-admin/includes/template.php
Retrieves a list of the most popular terms from the specified taxonomy.

wp_terms_checklist()wp-admin/includes/template.php
Outputs an unordered list of checkbox input elements labelled with term names.

wp_dropdown_categories()wp-includes/category-template.php
Displays or retrieves the HTML dropdown list of categories.

wp_nonce_field()wp-includes/functions.php
Retrieves or display nonce hidden field for forms.

current_user_can()wp-includes/capabilities.php
Returns whether the current user has the specified capability.

__()wp-includes/l10n.php
Retrieves the translation of $text.

esc_attr()wp-includes/formatting.php
Escaping for HTML attributes.

esc_html()wp-includes/formatting.php
Escaping for HTML blocks.

wp_parse_args()wp-includes/functions.php
Merges user defined arguments into defaults array.

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.

Show 7 moreShow less

Changelog

VersionDescription
2.6.0Introduced.

User Contributed Notes

You must log in before being able to contribute a note or feedback.