Функция register_block_script_handle() позволяет зарегистрировать скрипт для блока, используя метаданные блока и автоматически генерируя уникальное имя. Эта функция проверяет, был ли предоставлен путь к файлу, и регистрирует скрипт, используя сведения из метаданных.
register_block_script_handle( array $metadata, string $field_name, int $index = 0 ): string|false
Функция register_block_script_handle() помогает найти и зарегистрировать скрипт для блока на основе переданных метаданных. Она считывает информацию из указанного поля метаданных и обрабатывает её, создавая уникальный хэндл для скрипта или возвращая уже зарегистрированный хэндл.
Параметры:
- $metadata (array) — Массив с метаданными блока.
- $field_name (string) — Имя поля в метаданных, где содержится информация о скрипте.
- $index (int) — Индекс скрипта в случае, если передано несколько скриптов. По умолчанию 0.
Возвращает строку с хэндлом скрипта при успешной регистрации или false при ошибке.
Пример 1: Регистрация Скрипта для Блока с Основным Скриптом
Допустим, у нас есть блок с основным скриптом, и мы хотим зарегистрировать его, чтобы скрипт выполнялся на фронтенде.
add_action( 'init', function() {
$block_metadata = array(
'name' => 'my-plugin/custom-block',
'file' => __DIR__ . '/custom-block.php',
'script' => 'build/custom-block.js',
'version' => '1.0.0',
);
$script_handle = register_block_script_handle( $block_metadata, 'script' );
if ( $script_handle ) {
wp_enqueue_script( $script_handle );
}
});
В этом примере создается скрипт для блока
my-plugin/custom-block. Уникальный хэндл для скрипта генерируется на основе имени блока и подключается на фронтенде.
Пример 2: Регистрация Скрипта для Редактора Блока
Теперь представим, что у нас есть блок, который использует отдельный скрипт для редактора, чтобы добавить дополнительные функции или стили только в интерфейсе редактирования.
add_action( 'init', function() {
$block_metadata = array(
'name' => 'my-plugin/editor-enhancements',
'file' => __DIR__ . '/editor-enhancements.php',
'editorScript' => 'assets/editor-script.js',
'textdomain' => 'my-plugin',
);
$script_handle = register_block_script_handle( $block_metadata, 'editorScript' );
if ( $script_handle ) {
wp_enqueue_script( $script_handle );
}
});
Здесь мы регистрируем скрипт для редактора блока
my-plugin/editor-enhancements, который будет подключен только при редактировании блока. Указаниеtextdomainобеспечивает возможность локализации текста в скрипте.
Пример 3: Регистрация Нескольких Скриптов для Блока
Если необходимо зарегистрировать несколько скриптов для одного блока, можно указать индекс, чтобы регистрировать каждый скрипт отдельно.
add_action( 'init', function() {
$block_metadata = array(
'name' => 'my-plugin/multi-script-block',
'file' => __DIR__ . '/multi-script-block.php',
'viewScript' => array(
'build/view-script1.js',
'build/view-script2.js',
),
);
$script_handle1 = register_block_script_handle( $block_metadata, 'viewScript', 0 );
$script_handle2 = register_block_script_handle( $block_metadata, 'viewScript', 1 );
if ( $script_handle1 ) {
wp_enqueue_script( $script_handle1 );
}
if ( $script_handle2 ) {
wp_enqueue_script( $script_handle2 );
}
});
В этом примере регистрируется несколько скриптов для одного блока. Скрипты
viewScriptподключаются на фронтенде по индексам0и1, что позволяет использовать сразу два скрипта для одного блока.
Советы по Использованию
- Использование пути к скрипту: Путь к скрипту следует указывать в формате, относительно корня плагина. Например,
build/script.js. - Локализация скриптов: Если скрипт включает текст, нуждающийся в переводе, укажите поле
textdomainв метаданных блока, чтобы сделать локализацию доступной. - Хэндл для скрипта: Если скрипт был зарегистрирован с уникальным хэндлом, WordPress не будет его перерегистрировать, что обеспечивает экономию ресурсов.
- Подключение через хук
init: Рекомендуется подключать функциюregister_block_script_handle()через хукinit, чтобы регистрация выполнялась в нужное время.
Заключение
Функция register_block_script_handle() в WordPress является удобным инструментом для регистрации скриптов, связанных с блоками, и автоматической генерации уникальных хэндлов. Это значительно упрощает подключение скриптов для блоков, обеспечивая их удобное использование как в редакторе, так и на фронтенде.