184 lines
5.6 KiB
Markdown
184 lines
5.6 KiB
Markdown
# 模板
|
||
|
||
区块模板被定义为一组区块项目的列表。这类区块可以包含预定义的属性、占位符内容，并且可以是静态或动态的。区块模板允许为编辑器会话指定默认的初始状态。
|
||
|
||
模板的适用范围包括：
|
||
|
||
- 在客户端动态设置默认状态（例如 `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' => '添加内部段落'
|
||
) ),
|
||
) ),
|
||
) )
|
||
);
|
||
``` |