# locate_block_template()

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

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

## Сигнатура

```php
locate_block_template( string $template, string $type, string[] $templates ): string
```

## Описание

Внутри передаёт содержимое блока, которое должно использоваться холстом шаблона, через глобальную переменную.

## Параметры

- `$template` `string` — обязательный. Путь к шаблону. См. locate_template().
- `$type` `string` — обязательный. Очищенное имя файла без расширения.
- `$templates` `string[]` — обязательный. Список кандидатов-шаблонов в порядке убывания приоритета.

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

`string`

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

Файл: `wp-includes/block-template.php:62`

```php
function locate_block_template( $template, $type, array $templates ) {
	global $_wp_current_template_content, $_wp_current_template_id;

	if ( ! current_theme_supports( 'block-templates' ) ) {
		return $template;
	}

	if ( $template ) {
		/*
		 * locate_template() has found a PHP template at the path specified by $template.
		 * That means that we have a fallback candidate if we cannot find a block template
		 * with higher specificity.
		 *
		 * Thus, before looking for matching block themes, we shorten our list of candidate
		 * templates accordingly.
		 */

		// Locate the index of $template (without the theme directory path) in $templates.
		$relative_template_path = str_replace(
			array( get_stylesheet_directory() . '/', get_template_directory() . '/' ),
			'',
			$template
		);
		$index                  = array_search( $relative_template_path, $templates, true );

		// If the template hierarchy algorithm has successfully located a PHP template file,
		// we will only consider block templates with higher or equal specificity.
		$templates = array_slice( $templates, 0, $index + 1 );
	}

	$block_template = resolve_block_template( $type, $templates, $template );

	if ( $block_template ) {
		$_wp_current_template_id = $block_template->id;

		if ( empty( $block_template->content ) ) {
			if ( is_user_logged_in() ) {
				$_wp_current_template_content = wp_render_empty_block_template_warning( $block_template );
			} else {
				if ( $block_template->has_theme_file ) {
					// Show contents from theme template if user is not logged in.
					$theme_template               = _get_block_template_file( 'wp_template', $block_template->slug );
					$_wp_current_template_content = file_get_contents( $theme_template['path'] );
				} else {
					$_wp_current_template_content = $block_template->content;
				}
			}
		} elseif ( ! empty( $block_template->content ) ) {
			$_wp_current_template_content = $block_template->content;
		}
		if ( isset( $_GET['_wp-find-template'] ) ) {
			wp_send_json_success( $block_template );
		}
	} else {
		if ( $template ) {
			return $template;
		}

		if ( 'index' === $type ) {
			if ( isset( $_GET['_wp-find-template'] ) ) {
				wp_send_json_error( array( 'message' => __( 'No matching template found.' ) ) );
			}
		} else {
			return ''; // So that the template loader keeps looking for templates.
		}
	}

	// Add hooks for template canvas.
	// Add viewport meta tag.
	add_action( 'wp_head', '_block_template_viewport_meta_tag', 0 );

	// Render title tag with content, regardless of whether theme has title-tag support.
	remove_action( 'wp_head', '_wp_render_title_tag', 1 );    // Remove conditional title tag rendering...
	add_action( 'wp_head', '_block_template_render_title_tag', 1 ); // ...and make it unconditional.

	// This file will be included instead of the theme's template file.
	return ABSPATH . WPINC . '/template-canvas.php';
}
```

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

- 6.3.0 — Added $_wp_current_template_id global for editing of current template directly from the admin bar.
- 5.8.0 — Introduced.

## Связанные

Использует: [`wp_render_empty_block_template_warning`](https://chugunov.pro/api-wordpress/functions/wp_render_empty_block_template_warning/), [`_get_block_template_file`](https://chugunov.pro/api-wordpress/functions/_get_block_template_file/), [`resolve_block_template`](https://chugunov.pro/api-wordpress/functions/resolve_block_template/), [`get_stylesheet_directory`](https://chugunov.pro/api-wordpress/functions/get_stylesheet_directory/), [`get_template_directory`](https://chugunov.pro/api-wordpress/functions/get_template_directory/), [`remove_action`](https://chugunov.pro/api-wordpress/functions/remove_action/), [`current_theme_supports`](https://chugunov.pro/api-wordpress/functions/current_theme_supports/), [`__`](https://chugunov.pro/api-wordpress/functions/__/), [`is_user_logged_in`](https://chugunov.pro/api-wordpress/functions/is_user_logged_in/), [`wp_send_json_success`](https://chugunov.pro/api-wordpress/functions/wp_send_json_success/), [`wp_send_json_error`](https://chugunov.pro/api-wordpress/functions/wp_send_json_error/), [`add_action`](https://chugunov.pro/api-wordpress/functions/add_action/).
Используется в: [`get_query_template`](https://chugunov.pro/api-wordpress/functions/get_query_template/).

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