# register_block_script_handle()

URL: https://chugunov.pro/api-wordpress/functions/register_block_script_handle/
Проверено на WordPress 6.9, обновлено 06.08.2026.
Источник: независимый русскоязычный справочник chugunov.pro. Не является официальной документацией WordPress.

Тип: функция.
Появился в версии: 5.5.0.

## Сигнатура

```php
register_block_script_handle( array $metadata, string $field_name, int $index ): string|false
```

## Описание

Находит дескриптор скрипта для выбранного поля метаданных блока. Определяет, когда указан путь к файлу, и при необходимости находит соответствующий файл ресурса с данными, нужными для регистрации скрипта под автоматически сгенерированным именем дескриптора. Иначе возвращает необработанный дескриптор скрипта.

## Параметры

- `$metadata` `array` — обязательный. Метаданные блока.
- `$field_name` `string` — обязательный. Имя поля, выбираемого из метаданных.
- `$index` `int` — необязательный. Индекс скрипта для регистрации, когда передано несколько элементов.
  
  Значение по умолчанию 0.

## Возвращаемое значение

`string|false`

## Исходный код

Файл: `wp-includes/blocks.php:225`

```php
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 = $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 = $script_asset['dependencies'] ?? array();
	$block_version       = $metadata['version'] ?? false;
	$script_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;
}
```

## История изменений

- 6.5.0 — The asset file is optional. Added script handle support in the asset file.
- 6.1.0 — Added $index parameter.
- 5.5.0 — Introduced.

## Связанные

Использует: [`get_block_asset_url`](https://chugunov.pro/api-wordpress/functions/get_block_asset_url/), [`generate_block_asset_handle`](https://chugunov.pro/api-wordpress/functions/generate_block_asset_handle/), [`remove_block_asset_path_prefix`](https://chugunov.pro/api-wordpress/functions/remove_block_asset_path_prefix/), [`wp_set_script_translations`](https://chugunov.pro/api-wordpress/functions/wp_set_script_translations/), [`wp_script_is`](https://chugunov.pro/api-wordpress/functions/wp_script_is/), [`wp_register_script`](https://chugunov.pro/api-wordpress/functions/wp_register_script/), [`wp_normalize_path`](https://chugunov.pro/api-wordpress/functions/wp_normalize_path/).
Используется в: [`register_block_type_from_metadata`](https://chugunov.pro/api-wordpress/functions/register_block_type_from_metadata/).

Оригинал в официальной документации: https://developer.wordpress.org/reference/functions/register_block_script_handle/