云策 WordPress 开发者社区

函数文档

register_block_type_from_metadata()

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

概述

register_block_type_from_metadata() 函数用于从 block.json 文件中的元数据注册块类型。它解析元数据并映射到 WP_Block_Type 设置，支持核心块优化和国际化处理。

关键要点

  • 参数 $file_or_folder 必须指向 block.json 文件或包含该文件的文件夹路径，文件名需以 block.json 结尾。
  • 可选参数 $args 可覆盖或补充元数据中的设置，接受 WP_Block_Type 的公共属性。
  • 函数返回 WP_Block_Type 对象（成功时）或 false（失败时），失败可能因元数据无效或缺少名称。
  • 内部处理包括元数据读取、属性映射（如 apiVersion 到 api_version）、脚本/样式注册，以及核心块的特殊样式处理。
  • 支持通过 block.json 中的 render 字段定义服务器端渲染回调，使用 PHP 模板文件。
  • 提供过滤器 block_type_metadata 和 block_type_metadata_settings 用于自定义元数据和设置。
  • 从 WordPress 5.8 开始，推荐使用 register_block_type() 替代此函数，除非需要支持旧版本（5.5-5.7）。

代码示例

// 示例：从 block.json 注册块类型
register_block_type_from_metadata( __DIR__ . '/block.json', array(
    'title' => '自定义标题', // 可覆盖元数据中的标题
    'category' => 'widgets', // 补充分类设置
) );

注意事项

  • 在主题中使用时，block.json 中的脚本和样式注册可能受限，需检查版本兼容性。
  • 避免在 blockHooks 中将块挂载到自身，以防止无限递归错误。
  • 确保元数据文件路径正确，否则函数可能返回 false。
📄 原文内容

Registers a block type from the metadata stored in the block.json file.

Parameters

$file_or_folderstringrequired
Path to the JSON file with metadata definition for the block or path to the folder where the block.json file is located.
If providing the path to a JSON file, the filename must end with block.json.
$argsarrayoptional
Array of block type arguments. Accepts any public property of WP_Block_Type. See WP_Block_Type::__construct() for information on accepted arguments.

Default:array()

Return

WP_Block_Type|false The registered block type on success, or false on failure.

Source

function register_block_type_from_metadata( $file_or_folder, $args = array() ) {
	/*
	 * Get an array of metadata from a PHP file.
	 * This improves performance for core blocks as it's only necessary to read a single PHP file
	 * instead of reading a JSON file per-block, and then decoding from JSON to PHP.
	 * Using a static variable ensures that the metadata is only read once per request.
	 */

	$file_or_folder = wp_normalize_path( $file_or_folder );

	$metadata_file = ( ! str_ends_with( $file_or_folder, 'block.json' ) ) ?
		trailingslashit( $file_or_folder ) . 'block.json' :
		$file_or_folder;

	$is_core_block        = str_starts_with( $file_or_folder, wp_normalize_path( ABSPATH . WPINC ) );
	$metadata_file_exists = $is_core_block || file_exists( $metadata_file );
	$registry_metadata    = WP_Block_Metadata_Registry::get_metadata( $file_or_folder );

	if ( $registry_metadata ) {
		$metadata = $registry_metadata;
	} elseif ( $metadata_file_exists ) {
		$metadata = wp_json_file_decode( $metadata_file, array( 'associative' => true ) );
	} else {
		$metadata = array();
	}

	if ( ! is_array( $metadata ) || ( empty( $metadata['name'] ) && empty( $args['name'] ) ) ) {
		return false;
	}

	$metadata['file'] = $metadata_file_exists ? wp_normalize_path( realpath( $metadata_file ) ) : null;

	/**
	 * Filters the metadata provided for registering a block type.
	 *
	 * @since 5.7.0
	 *
	 * @param array $metadata Metadata for registering a block type.
	 */
	$metadata = apply_filters( 'block_type_metadata', $metadata );

	// Add `style` and `editor_style` for core blocks if missing.
	if ( ! empty( $metadata['name'] ) && str_starts_with( $metadata['name'], 'core/' ) ) {
		$block_name = str_replace( 'core/', '', $metadata['name'] );

		if ( ! isset( $metadata['style'] ) ) {
			$metadata['style'] = "wp-block-$block_name";
		}
		if ( current_theme_supports( 'wp-block-styles' ) && wp_should_load_separate_core_block_assets() ) {
			$metadata['style']   = (array) $metadata['style'];
			$metadata['style'][] = "wp-block-{$block_name}-theme";
		}
		if ( ! isset( $metadata['editorStyle'] ) ) {
			$metadata['editorStyle'] = "wp-block-{$block_name}-editor";
		}
	}

	$settings          = array();
	$property_mappings = array(
		'apiVersion'      => 'api_version',
		'name'            => 'name',
		'title'           => 'title',
		'category'        => 'category',
		'parent'          => 'parent',
		'ancestor'        => 'ancestor',
		'icon'            => 'icon',
		'description'     => 'description',
		'keywords'        => 'keywords',
		'attributes'      => 'attributes',
		'providesContext' => 'provides_context',
		'usesContext'     => 'uses_context',
		'selectors'       => 'selectors',
		'supports'        => 'supports',
		'styles'          => 'styles',
		'variations'      => 'variations',
		'example'         => 'example',
		'allowedBlocks'   => 'allowed_blocks',
	);
	$textdomain        = ! empty( $metadata['textdomain'] ) ? $metadata['textdomain'] : null;
	$i18n_schema       = get_block_metadata_i18n_schema();

	foreach ( $property_mappings as $key => $mapped_key ) {
		if ( isset( $metadata[ $key ] ) ) {
			$settings[ $mapped_key ] = $metadata[ $key ];
			if ( $metadata_file_exists && $textdomain && isset( $i18n_schema->$key ) ) {
				$settings[ $mapped_key ] = translate_settings_using_i18n_schema( $i18n_schema->$key, $settings[ $key ], $textdomain );
			}
		}
	}

	if ( ! empty( $metadata['render'] ) ) {
		$template_path = wp_normalize_path(
			realpath(
				dirname( $metadata['file'] ) . '/' .
				remove_block_asset_path_prefix( $metadata['render'] )
			)
		);
		if ( $template_path ) {
			/**
			 * Renders the block on the server.
			 *
			 * @since 6.1.0
			 *
			 * @param array    $attributes Block attributes.
			 * @param string   $content    Block default content.
			 * @param WP_Block $block      Block instance.
			 *
			 * @return string Returns the block content.
			 */
			$settings['render_callback'] = static function ( $attributes, $content, $block ) use ( $template_path ) {
				ob_start();
				require $template_path;
				return ob_get_clean();
			};
		}
	}

	// If `variations` is a string, it's the name of a PHP file that
	// generates the variations.
	if ( ! empty( $metadata['variations'] ) && is_string( $metadata['variations'] ) ) {
		$variations_path = wp_normalize_path(
			realpath(
				dirname( $metadata['file'] ) . '/' .
				remove_block_asset_path_prefix( $metadata['variations'] )
			)
		);
		if ( $variations_path ) {
			/**
			 * Generates the list of block variations.
			 *
			 * @since 6.7.0
			 *
			 * @return string Returns the list of block variations.
			 */
			$settings['variation_callback'] = static function () use ( $variations_path ) {
				$variations = require $variations_path;
				return $variations;
			};
			// The block instance's `variations` field is only allowed to be an array
			// (of known block variations). We unset it so that the block instance will
			// provide a getter that returns the result of the `variation_callback` instead.
			unset( $settings['variations'] );
		}
	}

	$settings = array_merge( $settings, $args );

	$script_fields = array(
		'editorScript' => 'editor_script_handles',
		'script'       => 'script_handles',
		'viewScript'   => 'view_script_handles',
	);
	foreach ( $script_fields as $metadata_field_name => $settings_field_name ) {
		if ( ! empty( $settings[ $metadata_field_name ] ) ) {
			$metadata[ $metadata_field_name ] = $settings[ $metadata_field_name ];
		}
		if ( ! empty( $metadata[ $metadata_field_name ] ) ) {
			$scripts           = $metadata[ $metadata_field_name ];
			$processed_scripts = array();
			if ( is_array( $scripts ) ) {
				for ( $index = 0; $index < count( $scripts ); $index++ ) {
					$result = register_block_script_handle(
						$metadata,
						$metadata_field_name,
						$index
					);
					if ( $result ) {
						$processed_scripts[] = $result;
					}
				}
			} else {
				$result = register_block_script_handle(
					$metadata,
					$metadata_field_name
				);
				if ( $result ) {
					$processed_scripts[] = $result;
				}
			}
			$settings[ $settings_field_name ] = $processed_scripts;
		}
	}

	$module_fields = array(
		'viewScriptModule' => 'view_script_module_ids',
	);
	foreach ( $module_fields as $metadata_field_name => $settings_field_name ) {
		if ( ! empty( $settings[ $metadata_field_name ] ) ) {
			$metadata[ $metadata_field_name ] = $settings[ $metadata_field_name ];
		}
		if ( ! empty( $metadata[ $metadata_field_name ] ) ) {
			$modules           = $metadata[ $metadata_field_name ];
			$processed_modules = array();
			if ( is_array( $modules ) ) {
				for ( $index = 0; $index < count( $modules ); $index++ ) {
					$result = register_block_script_module_id(
						$metadata,
						$metadata_field_name,
						$index
					);
					if ( $result ) {
						$processed_modules[] = $result;
					}
				}
			} else {
				$result = register_block_script_module_id(
					$metadata,
					$metadata_field_name
				);
				if ( $result ) {
					$processed_modules[] = $result;
				}
			}
			$settings[ $settings_field_name ] = $processed_modules;
		}
	}

	$style_fields = array(
		'editorStyle' => 'editor_style_handles',
		'style'       => 'style_handles',
		'viewStyle'   => 'view_style_handles',
	);
	foreach ( $style_fields as $metadata_field_name => $settings_field_name ) {
		if ( ! empty( $settings[ $metadata_field_name ] ) ) {
			$metadata[ $metadata_field_name ] = $settings[ $metadata_field_name ];
		}
		if ( ! empty( $metadata[ $metadata_field_name ] ) ) {
			$styles           = $metadata[ $metadata_field_name ];
			$processed_styles = array();
			if ( is_array( $styles ) ) {
				for ( $index = 0; $index < count( $styles ); $index++ ) {
					$result = register_block_style_handle(
						$metadata,
						$metadata_field_name,
						$index
					);
					if ( $result ) {
						$processed_styles[] = $result;
					}
				}
			} else {
				$result = register_block_style_handle(
					$metadata,
					$metadata_field_name
				);
				if ( $result ) {
					$processed_styles[] = $result;
				}
			}
			$settings[ $settings_field_name ] = $processed_styles;
		}
	}

	if ( ! empty( $metadata['blockHooks'] ) ) {
		/**
		 * Map camelCased position string (from block.json) to snake_cased block type position.
		 *
		 * @var array
		 */
		$position_mappings = array(
			'before'     => 'before',
			'after'      => 'after',
			'firstChild' => 'first_child',
			'lastChild'  => 'last_child',
		);

		$settings['block_hooks'] = array();
		foreach ( $metadata['blockHooks'] as $anchor_block_name => $position ) {
			// Avoid infinite recursion (hooking to itself).
			if ( $metadata['name'] === $anchor_block_name ) {
				_doing_it_wrong(
					__METHOD__,
					__( 'Cannot hook block to itself.' ),
					'6.4.0'
				);
				continue;
			}

			if ( ! isset( $position_mappings[ $position ] ) ) {
				continue;
			}

			$settings['block_hooks'][ $anchor_block_name ] = $position_mappings[ $position ];
		}
	}

	/**
	 * Filters the settings determined from the block type metadata.
	 *
	 * @since 5.7.0
	 *
	 * @param array $settings Array of determined settings for registering a block type.
	 * @param array $metadata Metadata provided for registering a block type.
	 */
	$settings = apply_filters( 'block_type_metadata_settings', $settings, $metadata );

	$metadata['name'] = ! empty( $settings['name'] ) ? $settings['name'] : $metadata['name'];

	return WP_Block_Type_Registry::get_instance()->register(
		$metadata['name'],
		$settings
	);
}

View all references View on Trac View on GitHub

Hooks

apply_filters( ‘block_type_metadata’, array $metadata )

Filters the metadata provided for registering a block type.

apply_filters( ‘block_type_metadata_settings’, array $settings, array $metadata )

Filters the settings determined from the block type metadata.

Uses Description
WP_Block_Metadata_Registry::get_metadata()wp-includes/class-wp-block-metadata-registry.php

Retrieves block metadata for a given block within a specific collection.
register_block_script_module_id()wp-includes/blocks.php

Finds a script module ID for the selected block metadata field. It detects when a path to file was provided and optionally finds a corresponding asset file with details necessary to register the script module under with an automatically generated module ID. It returns unprocessed script module ID otherwise.
translate_settings_using_i18n_schema()wp-includes/l10n.php

Translates the provided settings value using its i18n schema.
wp_json_file_decode()wp-includes/functions.php

Reads and decodes a JSON file.
get_block_metadata_i18n_schema()wp-includes/blocks.php

Gets i18n schema for block’s metadata read from block.json file.
wp_should_load_separate_core_block_assets()wp-includes/script-loader.php

Checks whether separate styles should be loaded for core blocks.
register_block_script_handle()wp-includes/blocks.php

Finds a script handle for the selected block metadata field. It detects when a path to file was provided and optionally finds a corresponding asset file with details necessary to register the script under automatically generated handle name. It returns unprocessed script handle otherwise.
register_block_style_handle()wp-includes/blocks.php

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.
remove_block_asset_path_prefix()wp-includes/blocks.php

Removes the block asset’s path prefix if provided.
WP_Block_Type_Registry::get_instance()wp-includes/class-wp-block-type-registry.php

Utility method to retrieve the main instance of the class.
wp_normalize_path()wp-includes/functions.php

Normalizes a filesystem path.
current_theme_supports()wp-includes/theme.php

Checks a theme’s support for a given feature.
__()wp-includes/l10n.php

Retrieves the translation of $text.
trailingslashit()wp-includes/formatting.php

Appends a trailing slash.
_doing_it_wrong()wp-includes/functions.php

Marks something as being incorrectly called.
apply_filters()wp-includes/plugin.php

Calls the callback functions that have been added to a filter hook.

Show 11 moreShow less

Used by Description
wp_register_block_types_from_metadata_collection()wp-includes/blocks.php

Registers all block types from a block metadata collection.
register_block_type()wp-includes/blocks.php

Registers a block type. The recommended way is to register a block type using the metadata stored in the block.json file.

Changelog

Version Description
6.7.0 Allow PHP filename as variations argument.
6.5.0 Added support for allowedBlocks, viewScriptModule, and viewStyle fields.
6.4.0 Added support for blockHooks field.
6.3.0 Added selectors field.
6.1.0 Added support for render field.
5.9.0 Added support for variations and viewScript fields.
5.7.0 Added support for textdomain field and i18n handling for all translatable fields.
5.5.0 Introduced.

Show 3 moreShow less

User Contributed Notes

  1. Skip to note 3 content


    mrwweb


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

    In WordPress 5.8, the ability to use block.json metadata was added to the register_block_type function. Therefore, register_block_type_from_metadata is now redundant and the shorter register_block_type is preferred. The only reason to use register_block_type_from_metadata is for supporting sites on WordPress versions 5.5 – 5.7.