register_block_style_handle()
云策文档标注
概述
register_block_style_handle() 函数用于处理块元数据中的样式字段，自动检测文件路径并注册样式，返回样式句柄。它支持核心块的特殊处理，包括样式注册、版本控制和 RTL 支持。
关键要点
- 函数从块元数据中提取样式字段，支持数组形式和多索引选择。
- 自动生成样式句柄，避免重复注册，并处理核心块与自定义块的差异。
- 根据 SCRIPT_DEBUG 常量添加 .min 后缀，并注册样式到 WordPress 系统。
- 支持 RTL（从右到左）语言环境，自动添加相关元数据。
- 返回样式句柄或 false 表示失败，确保错误处理。
代码示例
function register_block_style_handle( $metadata, $field_name, $index = 0 ) {
// 函数实现代码，包括参数检查、样式句柄生成、核心块处理、样式注册和 RTL 支持。
}注意事项
- 对于核心块，当 wp_should_load_separate_core_block_assets() 返回 false 时，跳过单个样式注册。
- 样式路径需通过 remove_block_asset_path_prefix() 处理，确保正确性。
- 版本控制基于文件修改时间或块元数据版本，取决于 SCRIPT_DEBUG 设置。
- 函数依赖多个辅助函数，如 generate_block_asset_handle() 和 wp_register_style()，需确保环境兼容。
原文内容
Finds a style handle for the block metadata field. It detects when a path to file was provided and registers the style under automatically generated handle name. It returns unprocessed style handle otherwise.
Parameters
$metadataarrayrequired-
Block metadata.
$field_namestringrequired-
Field name to pick from metadata.
$indexintoptional-
Index of the style to register when multiple items passed.
Default 0.
Source
function register_block_style_handle( $metadata, $field_name, $index = 0 ) {
if ( empty( $metadata[ $field_name ] ) ) {
return false;
}
$style_handle = $metadata[ $field_name ];
if ( is_array( $style_handle ) ) {
if ( empty( $style_handle[ $index ] ) ) {
return false;
}
$style_handle = $style_handle[ $index ];
}
$style_handle_name = generate_block_asset_handle( $metadata['name'], $field_name, $index );
// If the style handle is already registered, skip re-registering.
if ( wp_style_is( $style_handle_name, 'registered' ) ) {
return $style_handle_name;
}
static $wpinc_path_norm = '';
if ( ! $wpinc_path_norm ) {
$wpinc_path_norm = wp_normalize_path( realpath( ABSPATH . WPINC ) );
}
$is_core_block = isset( $metadata['file'] ) && str_starts_with( $metadata['file'], $wpinc_path_norm );
// Skip registering individual styles for each core block when a bundled version provided.
if ( $is_core_block && ! wp_should_load_separate_core_block_assets() ) {
return false;
}
$style_path = remove_block_asset_path_prefix( $style_handle );
$is_style_handle = $style_handle === $style_path;
// Allow only passing style handles for core blocks.
if ( $is_core_block && ! $is_style_handle ) {
return false;
}
// Return the style handle unless it's the first item for every core block that requires special treatment.
if ( $is_style_handle && ! ( $is_core_block && 0 === $index ) ) {
return $style_handle;
}
// Check whether styles should have a ".min" suffix or not.
$suffix = SCRIPT_DEBUG ? '' : '.min';
if ( $is_core_block ) {
$style_path = ( 'editorStyle' === $field_name ) ? "editor{$suffix}.css" : "style{$suffix}.css";
}
$style_path_norm = wp_normalize_path( realpath( dirname( $metadata['file'] ) . '/' . $style_path ) );
$style_uri = get_block_asset_url( $style_path_norm );
$block_version = ! $is_core_block && isset( $metadata['version'] ) ? $metadata['version'] : false;
$version = $style_path_norm && defined( 'SCRIPT_DEBUG' ) && SCRIPT_DEBUG ? filemtime( $style_path_norm ) : $block_version;
$result = wp_register_style(
$style_handle_name,
$style_uri,
array(),
$version
);
if ( ! $result ) {
return false;
}
if ( $style_uri ) {
wp_style_add_data( $style_handle_name, 'path', $style_path_norm );
if ( $is_core_block ) {
$rtl_file = str_replace( "{$suffix}.css", "-rtl{$suffix}.css", $style_path_norm );
} else {
$rtl_file = str_replace( '.css', '-rtl.css', $style_path_norm );
}
if ( is_rtl() && file_exists( $rtl_file ) ) {
wp_style_add_data( $style_handle_name, 'rtl', 'replace' );
wp_style_add_data( $style_handle_name, 'suffix', $suffix );
wp_style_add_data( $style_handle_name, 'path', $rtl_file );
}
}
return $style_handle_name;
}