_block_bindings_term_data_get_value()
云策文档标注
概述
_block_bindings_term_data_get_value() 是 WordPress 6.9.0 引入的函数，用于从 Term Data 源获取值，支持多种字段如名称、链接等。它处理导航块和其他块的上下文差异，并确保数据安全性和兼容性。
关键要点
- 函数参数：接受 $source_args（数组，必须包含 'field' 键）和 $block_instance（WP_Block 实例），返回混合类型的值。
- 导航块处理：为 WordPress 6.9+ 的导航块提供向后兼容性，从块属性读取 term_id 和 taxonomy，其他块使用上下文。
- 数据获取：基于 term_id 和 taxonomy 获取 term 数据，检查 taxonomy 是否公开可查询，否则需要 'read' 权限。
- 字段支持：支持 'id'、'name'、'link'、'slug'、'description'、'parent'、'count' 字段，返回相应转义值，无效字段返回 null。
- 错误处理：缺少参数、term 不存在或 taxonomy 不可访问时返回 null，确保函数健壮性。
代码示例
// 示例：获取 term 名称
$value = _block_bindings_term_data_get_value(
array( 'field' => 'name' ),
$block_instance
);
// 返回转义的 term 名称或 null注意事项
- 导航块（core/navigation-link 和 core/navigation-submenu）使用块属性，其他块使用上下文，这是 WordPress 6.9+ 的硬编码例外，不应移除。
- 函数内部使用 esc_html()、esc_url()、wp_kses_post() 进行转义，确保输出安全。
- 依赖函数如 get_term()、get_taxonomy() 和 current_user_can()，需确保环境支持。
原文内容
Gets value for Term Data source.
Parameters
$source_argsarrayrequired-
Array containing source arguments used to look up the override value.
Example: array( “field” => “name” ). $block_instanceWP_Blockrequired-
The block instance.
Source
function _block_bindings_term_data_get_value( array $source_args, $block_instance ) {
if ( empty( $source_args['field'] ) ) {
return null;
}
/*
* BACKWARDS COMPATIBILITY: Hardcoded exception for navigation blocks.
* Required for WordPress 6.9+ navigation blocks. DO NOT REMOVE.
*/
$block_name = $block_instance->name ?? '';
$is_navigation_block = in_array(
$block_name,
array( 'core/navigation-link', 'core/navigation-submenu' ),
true
);
if ( $is_navigation_block ) {
// Navigation blocks: read from block attributes.
$term_id = $block_instance->attributes['id'] ?? null;
$type = $block_instance->attributes['type'] ?? '';
// Map UI shorthand to taxonomy slug when using attributes.
$taxonomy = ( 'tag' === $type ) ? 'post_tag' : $type;
} else {
// All other blocks: use context
$term_id = $block_instance->context['termId'] ?? null;
$taxonomy = $block_instance->context['taxonomy'] ?? '';
}
// If we don't have required identifiers, bail early.
if ( empty( $term_id ) || empty( $taxonomy ) ) {
return null;
}
// Get the term data.
$term = get_term( $term_id, $taxonomy );
if ( is_wp_error( $term ) || ! $term ) {
return null;
}
// Check if taxonomy exists and is publicly queryable.
$taxonomy_object = get_taxonomy( $taxonomy );
if ( ! $taxonomy_object || ! $taxonomy_object->publicly_queryable ) {
if ( ! current_user_can( 'read' ) ) {
return null;
}
}
switch ( $source_args['field'] ) {
case 'id':
return esc_html( (string) $term_id );
case 'name':
return esc_html( $term->name );
case 'link':
// Only taxonomy entities are supported by Term Data.
$term_link = get_term_link( $term );
return is_wp_error( $term_link ) ? null : esc_url( $term_link );
case 'slug':
return esc_html( $term->slug );
case 'description':
return wp_kses_post( $term->description );
case 'parent':
return esc_html( (string) $term->parent );
case 'count':
return esc_html( (string) $term->count );
default:
return null;
}
}
Changelog
| Version | Description |
|---|---|
| 6.9.0 | Introduced. |