概述

register_block_script_handle() 函数用于从块元数据中查找脚本句柄，支持自动注册脚本并处理路径和资产文件。它返回脚本句柄或失败时返回 false。

关键要点

• 函数从块元数据中提取指定字段的脚本句柄或路径，支持数组索引选择。
• 当提供文件路径时，函数会查找对应的 .asset.php 文件以获取依赖和版本信息，并自动生成句柄。
• 函数自动注册脚本到 WordPress，处理依赖、版本和国际化设置，特别针对 viewScript 字段添加 defer 策略。
• 返回注册后的脚本句柄，如果脚本已注册则直接返回，失败时返回 false。

代码示例

function register_block_script_handle( $metadata, $field_name, $index = 0 ) {
    if ( empty( $metadata[ $field_name ] ) ) {
        return false;
    }

    $script_handle_or_path = $metadata[ $field_name ];
    if ( is_array( $script_handle_or_path ) ) {
        if ( empty( $script_handle_or_path[ $index ] ) ) {
            return false;
        }
        $script_handle_or_path = $script_handle_or_path[ $index ];
    }

    $script_path = remove_block_asset_path_prefix( $script_handle_or_path );
    if ( $script_handle_or_path === $script_path ) {
        return $script_handle_or_path;
    }

    $path                  = dirname( $metadata['file'] );
    $script_asset_raw_path = $path . '/' . substr_replace( $script_path, '.asset.php', - strlen( '.js' ) );
    $script_asset_path     = wp_normalize_path(
        realpath( $script_asset_raw_path )
    );

    // Asset file for blocks is optional. See https://core.trac.wordpress.org/ticket/60460.
    $script_asset  = ! empty( $script_asset_path ) ? require $script_asset_path : array();
    $script_handle = isset( $script_asset['handle'] ) ?
        $script_asset['handle'] :
        generate_block_asset_handle( $metadata['name'], $field_name, $index );
    if ( wp_script_is( $script_handle, 'registered' ) ) {
        return $script_handle;
    }

    $script_path_norm    = wp_normalize_path( realpath( $path . '/' . $script_path ) );
    $script_uri          = get_block_asset_url( $script_path_norm );
    $script_dependencies = isset( $script_asset['dependencies'] ) ? $script_asset['dependencies'] : array();
    $block_version       = isset( $metadata['version'] ) ? $metadata['version'] : false;
    $script_version      = isset( $script_asset['version'] ) ? $script_asset['version'] : $block_version;
    $script_args         = array();
    if ( 'viewScript' === $field_name && $script_uri ) {
        $script_args['strategy'] = 'defer';
    }

    $result = wp_register_script(
        $script_handle,
        $script_uri,
        $script_dependencies,
        $script_version,
        $script_args
    );
    if ( ! $result ) {
        return false;
    }

    if ( ! empty( $metadata['textdomain'] ) && in_array( 'wp-i18n', $script_dependencies, true ) ) {
        wp_set_script_translations( $script_handle, $metadata['textdomain'] );
    }

    return $script_handle;
}

注意事项

• 此函数主要用于插件开发，通过 block.json 元数据注册脚本可能不适用于主题，特别是使用符号链接时需额外处理。
• 资产文件（.asset.php）是可选的，从 WordPress 6.5.0 开始支持在资产文件中指定脚本句柄。
• 函数参数包括 $metadata（块元数据数组）、$field_name（字段名）和 $index（索引，默认 0）。