云策 WordPress 开发者社区

钩子文档

block_categories

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

概述

block_categories 是一个 WordPress 过滤器，用于修改块类型的默认分类数组。自 WordPress 5.8.0 起已弃用，建议使用 block_categories_all 过滤器替代。

关键要点

  • block_categories 过滤器允许开发者自定义块编辑器中的块分类，例如添加新分类或调整现有分类。
  • 该过滤器接受两个参数：$block_categories（块分类数组）和 $post（当前加载的文章对象），可用于根据文章内容或类型动态调整分类。
  • 自 WordPress 5.8.0 起，block_categories 已被弃用，应改用 block_categories_all 过滤器，后者提供了更灵活的上下文参数。
  • 使用 block_categories_all 时，可以通过 $editor_context 参数访问文章信息，实现基于文章类型的分类逻辑。

代码示例

/**
 * 注册一个新的块分类“My Plugin”（如果尚不存在）。
 *
 * @param   array $categories     块分类列表。
 * @return  array
 */
function wpdocs_new_block_category( $categories ) {
    // 插件的块分类标题和别名。
    $block_category = array( 'title' => esc_html__( 'My Plugin', 'text-domain' ), 'slug' => 'myplugin' );
    $category_slugs = wp_list_pluck( $categories, 'slug' );

    if ( ! in_array( $block_category['slug'], $category_slugs, true ) ) {
        $categories = array_merge(
            $categories,
            array(
                array(
                    'title' => $block_category['title'], // 必需
                    'slug'  => $block_category['slug'], // 必需
                    'icon'  => 'wordpress', // WordPress Dashicon 别名或自定义 SVG
                ),
            )
        );
    }

    return $categories;
}
add_filter( 'block_categories', 'wpdocs_new_block_category' );

注意事项

  • block_categories 过滤器在 WordPress 5.8.0 中已弃用，继续使用可能会触发弃用通知，建议尽快迁移到 block_categories_all。
  • 在 block_categories_all 过滤器中，第二个参数是 $editor_context，它提供了更丰富的上下文信息，包括文章对象，便于实现更复杂的分类逻辑。
📄 原文内容

Filters the default array of categories for block types.

Parameters

$block_categoriesarray[]
Array of categories for block types.
$postWP_Post
Post being loaded.

Source

$block_categories = apply_filters_deprecated( 'block_categories', array( $block_categories, $post ), '5.8.0', 'block_categories_all' );

View all references View on Trac View on GitHub

Used by Description
get_block_categories()wp-includes/block-editor.php

Returns all the categories for block types that will be shown in the block editor.

Changelog

Version Description
5.8.0 Deprecated. Use the ‘block_categories_all’ filter instead.
5.0.0 Introduced.

User Contributed Notes

  1. Skip to note 3 content


    Mahdi Yazdani


    You must log in to vote on the helpfulness of this noteVote results for this note: 2You must log in to vote on the helpfulness of this note

    Register a new block category for “My Plugin” if it doesn’t exist already.

    Note: You can also pass a second argument $post to generate a different category depending on the post’s content or type.

    /**
 * Creating a new (custm) block category.
 *
 * @param   array $categories     List of block categories.
 * @return  array
 */
function wpdocs_new_block_category( $categories ) {
    // Plugin’s block category title and slug.
    $block_category = array( 'title' => esc_html__( 'My Plugin', 'text-domain' ), 'slug' => 'myplugin' );
    $category_slugs = wp_list_pluck( $categories, 'slug' );

    if ( ! in_array( $block_category['slug'], $category_slugs, true ) ) {
        $categories = array_merge(
            $categories,
            array(
                array(
                    'title' => $block_category['title'], // Required
                    'slug'  => $block_category['slug'], // Required
                    'icon'  => 'wordpress', // Slug of a WordPress Dashicon or custom SVG
                ),
            )
        );
    }

    return $categories;
}
add_filter( 'block_categories', 'wpdocs_new_block_category' );

  2. Skip to note 4 content


    Cory Hughart


    You must log in to vote on the helpfulness of this noteVote results for this note: 2You must log in to vote on the helpfulness of this note

    If you’ve come here because you’re getting deprecation notices about `block_categories`, as of 5.8 this filter is deprecated. Use `block_categories_all` instead.

    If you need to apply categories based on post type or other $post data, you can do so like this:

    /**
 * Create a custom block category for posts only.
 *
 * @param   array $categories     List of block categories.
 * @return  array
 */
function wpdocs_post_block_category( $categories, $editor_context ) {
	if ( $editor_context->post instanceof WP_Post && 'post' === $editor_context->post->post_type ) {
		$categories = array_merge(
			$categories,
			array(
				'title' => __( 'Title' ), // Required
				'slug'  => 'slug', // Required
				'icon'  => 'wordpress', // Slug of a WordPress Dashicon or custom SVG
			)
		);
	}

	return $categories;
}
add_filter( 'block_categories_all', 'wpdocs_post_block_category' );