get_block_categories()
云策文档标注
概述
get_block_categories() 函数用于返回块编辑器（block editor）中显示的块类型（block types）的所有分类（categories）。它接受一个参数，可以是 WP_Post 对象或 WP_Block_Editor_Context 对象，并返回一个分类数组。
关键要点
- 函数返回块编辑器中的块类型分类数组，便于在编辑器中组织和显示块。
- 参数 $post_or_block_editor_context 是必需的，可以是 WP_Post 对象或 WP_Block_Editor_Context 对象，用于提供上下文。
- 内部使用 get_default_block_categories() 获取默认分类，并通过过滤器（filters）允许开发者自定义分类。
- 支持两个过滤器：'block_categories_all'（自 5.8.0 起）和已弃用的 'block_categories'（自 5.0.0 引入，5.8.0 弃用），后者在存在帖子上下文时仍被调用。
- 函数处理参数类型，如果传入 WP_Post 对象，会自动创建 WP_Block_Editor_Context 对象。
代码示例
function get_block_categories( $post_or_block_editor_context ) {
$block_categories = get_default_block_categories();
$block_editor_context = $post_or_block_editor_context instanceof WP_Post ?
new WP_Block_Editor_Context(
array(
'post' => $post_or_block_editor_context,
)
) : $post_or_block_editor_context;
$block_categories = apply_filters( 'block_categories_all', $block_categories, $block_editor_context );
if ( ! empty( $block_editor_context->post ) ) {
$post = $block_editor_context->post;
$block_categories = apply_filters_deprecated( 'block_categories', array( $block_categories, $post ), '5.8.0', 'block_categories_all' );
}
return $block_categories;
}注意事项
- 自 WordPress 5.8.0 起，推荐使用 'block_categories_all' 过滤器替代已弃用的 'block_categories' 过滤器，以支持更灵活的块编辑器上下文。
- 函数在块编辑器设置和自定义小部件等场景中被调用，确保分类与当前编辑环境匹配。
- 参数类型检查确保兼容性，如果传入 WP_Post，会自动转换为 WP_Block_Editor_Context 对象。
原文内容
Returns all the categories for block types that will be shown in the block editor.
Parameters
$post_or_block_editor_contextWP_Post|WP_Block_Editor_Contextrequired-
The current post object or the block editor context.
Source
function get_block_categories( $post_or_block_editor_context ) {
$block_categories = get_default_block_categories();
$block_editor_context = $post_or_block_editor_context instanceof WP_Post ?
new WP_Block_Editor_Context(
array(
'post' => $post_or_block_editor_context,
)
) : $post_or_block_editor_context;
/**
* Filters the default array of categories for block types.
*
* @since 5.8.0
*
* @param array[] $block_categories Array of categories for block types.
* @param WP_Block_Editor_Context $block_editor_context The current block editor context.
*/
$block_categories = apply_filters( 'block_categories_all', $block_categories, $block_editor_context );
if ( ! empty( $block_editor_context->post ) ) {
$post = $block_editor_context->post;
/**
* Filters the default array of categories for block types.
*
* @since 5.0.0
* @deprecated 5.8.0 Use the 'block_categories_all' filter instead.
*
* @param array[] $block_categories Array of categories for block types.
* @param WP_Post $post Post being loaded.
*/
$block_categories = apply_filters_deprecated( 'block_categories', array( $block_categories, $post ), '5.8.0', 'block_categories_all' );
}
return $block_categories;
}
Hooks
- apply_filters_deprecated( ‘block_categories’, array[] $block_categories, WP_Post $post )
-
Filters the default array of categories for block types.
- apply_filters( ‘block_categories_all’, array[] $block_categories, WP_Block_Editor_Context $block_editor_context )
-
Filters the default array of categories for block types.