gutenbergdocs/reference-guides/block-api/block-templates.md

# 模板

区块模板被定义为一组区块项目的列表。这类区块可以包含预定义的属性、占位符内容，并且可以是静态或动态的。区块模板允许为编辑器会话指定默认的初始状态。

模板的适用范围包括：

-   在客户端动态设置默认状态（例如 `defaultBlock`）
-   注册为特定文章类型的默认模板

计划新增功能：

-   保存并作为“页面模板”分配给页面
-   在 `template.php` 文件中定义，或从站点特定的自定义文章类型（`wp_templates`）中拉取
-   作为主题层级的等效方案

## API

模板可以在 JS 或 PHP 中声明为一个 blockTypes 数组（区块名称和可选属性）。

以下第一个 PHP 示例为文章创建了一个包含图片区块的模板，您可以根据需要向模板中添加任意数量的区块。

PHP 示例：

```php
<?php
function myplugin_register_template() {
    $post_type_object = get_post_type_object( 'post' );
    $post_type_object->template = array(
        array( 'core/image' ),
    );
}
add_action( 'init', 'myplugin_register_template' );
```

以下 JavaScript 示例使用 [InnerBlocks](https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/inner-blocks/README.md) 和模板创建了一个新区块，插入时会基于模板生成一组区块。

```js
const el = React.createElement;
const { registerBlockType } = wp.blocks;
const { InnerBlocks } = wp.blockEditor;

const BLOCKS_TEMPLATE = [
	[ 'core/image', {} ],
	[ 'core/paragraph', { placeholder: '图片详情' } ],
];

registerBlockType( 'myplugin/template', {
	title: '我的模板区块',
	category: 'widgets',
	edit: ( props ) => {
		return el( InnerBlocks, {
			template: BLOCKS_TEMPLATE,
			templateLock: false,
		} );
	},
	save: ( props ) => {
		return el( InnerBlocks.Content, {} );
	},
} );
```

有关实际使用模板的完整示例，请参阅 [元区块教程](/docs/how-to-guides/metabox.md#step-4-finishing-touches)。

## 区块属性

要查找可在模板中定义的所有区块属性的完整列表，请查阅区块的 `block.json` 文件，并查看 `attributes` 和 `supports` 值。

例如，[packages/block-library/src/heading/block.json](https://github.com/WordPress/gutenberg/blob/c62ccd80c7c6abb85740cf8745439029bf0f4d35/packages/block-library/src/heading/block.json#L5-L25) 显示该区块具有 `level` 属性，并支持 `anchor` 参数。

如果您没有安装 Gutenberg 插件，可以在 `wp-includes/blocks/heading/block.json` 中找到 `block.json` 文件。

## 自定义文章类型

自定义文章类型可以在注册过程中注册自己的模板：

```php
function myplugin_register_book_post_type() {
	$args = array(
		'public' => true,
		'label'  => '书籍',
		'show_in_rest' => true,
		'template' => array(
			array( 'core/image', array(
				'align' => 'left',
			) ),
			array( 'core/heading', array(
				'placeholder' => '添加作者...',
			) ),
			array( 'core/paragraph', array(
				'placeholder' => '添加描述...',
			) ),
		),
	);
	register_post_type( 'book', $args );
}
add_action( 'init', 'myplugin_register_book_post_type' );
```

## 锁定

有时可能需要在用户界面锁定模板，使得呈现的区块无法被操作。这可以通过 `template_lock` 属性实现。

```php
function myplugin_register_template() {
	$post_type_object = get_post_type_object( 'post' );
	$post_type_object->template = array(
		array( 'core/paragraph', array(
			'placeholder' => '添加描述...',
		) ),
	);
	$post_type_object->template_lock = 'all';
}
add_action( 'init', 'myplugin_register_template' );
```

_选项：_

-   `contentOnly` — 阻止所有操作。此外，没有内容的区块类型会从列表视图中隐藏，并且无法在区块列表中获得焦点。与其他锁定类型不同，此设置不能被子级覆盖。
-   `all` — 阻止所有操作。无法插入新区块、移动现有区块或删除区块。
-   `insert` — 阻止插入或移除区块，但允许移动现有区块。

锁定设置可以由 InnerBlocks 继承。如果未在 InnerBlocks 区域中设置 `templateLock`，则使用父级 InnerBlocks 区域的锁定设置。如果区块是顶级区块，则使用当前文章类型的锁定配置。

## 单个区块锁定

除了模板级锁定之外，您还可以锁定单个区块；您可以在属性级别使用 `lock` 属性来实现这一点。区块级锁定的优先级高于 `templateLock` 功能。目前，您可以锁定移动和删除区块的操作。

```js
attributes: {
  // 防止区块被移动或移除。
  lock: {
    remove: true,
    move: true,
  }
}
```

_选项：_

-   `remove` — 锁定区块，防止其被移除。
-   `move` — 锁定区块，防止其被移动。

您可以将此功能与 `templateLock` 结合使用，通过将 `remove` 或 `move` 设置为 `false` 来锁定除单个区块之外的所有区块。

```php
$template = array(
	array( 'core/image', array(
		'align' => 'left',
	) ),
	array( 'core/heading', array(
		'placeholder' => '添加作者...',
	) ),
	// 允许移动或移除段落区块。
	array( 'core/paragraph', array(
		'placeholder' => '添加描述...',
		'lock' => array(
			'move'   => false,
			'remove' => false,
		),
	) ),
);
```

## 嵌套模板

像列区块这样的容器区块也支持模板。这是通过为区块分配嵌套模板来实现的。

```php
$template = array(
	array( 'core/paragraph', array(
		'placeholder' => '添加根级段落',
	) ),
	array( 'core/columns', array(), array(
		array( 'core/column', array(), array(
			array( 'core/image', array() ),
		) ),
		array( 'core/column', array(), array(
			array( 'core/paragraph', array(
				'placeholder' => '添加内部段落'
			) ),
		) ),
	) )
);
```