title: "模板" post_status: publish comment_status: open taxonomy: category: - gutenberg-docs post_tag: - Block Api - Reference Guides - Repos

模板

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

模板的适用范围包括：

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

计划新增功能：

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

API

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

第一个 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 和模板创建了一个新区块，插入时会根据模板生成一组区块。

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

const BLOCKS_TEMPLATE = [
    [ 'core/image', {} ],
    [ 'core/paragraph', { placeholder: 'Image Details' } ],
];

registerBlockType( 'myplugin/template', {
    title: 'My Template Block',
    category: 'widgets',
    edit: ( props ) => {
        return el( InnerBlocks, {
            template: BLOCKS_TEMPLATE,
            templateLock: false,
        } );
    },
    save: ( props ) => {
        return el( InnerBlocks.Content, {} );
    },
} );

查看 Meta Block 教程获取完整的使用模板示例。

区块属性

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

例如，packages/block-library/src/heading/block.json 显示该区块具有 level 属性，并支持 anchor 参数。

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

Custom post types

A custom post type can register its own template during registration:

function myplugin_register_book_post_type() {
    $args = array(
        'public' => true,
        'label'  => 'Books',
        'show_in_rest' => true,
        'template' => array(
            array( 'core/image', array(
                'align' => 'left',
            ) ),
            array( 'core/heading', array(
                'placeholder' => 'Add Author...',
            ) ),
            array( 'core/paragraph', array(
                'placeholder' => 'Add Description...',
            ) ),
        ),
    );
    register_post_type( 'book', $args );
}
add_action( 'init', 'myplugin_register_book_post_type' );

锁定

有时可能需要锁定 UI 上的模板，以防止呈现的区块被操作。这可以通过 template_lock 属性实现。

function myplugin_register_template() {
    $post_type_object = get_post_type_object( 'post' );
    $post_type_object->template = array(
        array( 'core/paragraph', array(
            'placeholder' => 'Add Description...',
        ) ),
    );
    $post_type_object->template_lock = 'all';
}
add_action( 'init', 'myplugin_register_template' );

选项：

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

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

Individual block locking

Alongside template level locking, you can lock individual blocks; you can do this using a lock attribute on the attributes level. Block-level lock takes priority over the templateLock feature. Currently, you can lock moving and removing blocks.

attributes: {
  // Prevent a block from being moved or removed.
  lock: {
    remove: true,
    move: true,
  }
}

Options:

remove — Locks the ability of a block from being removed.
move — Locks the ability of a block from being moved.

You can use this with templateLock to lock all blocks except a single block by using false in remove or move.

$template = array(
    array( 'core/image', array(
        'align' => 'left',
    ) ),
    array( 'core/heading', array(
        'placeholder' => 'Add Author...',
    ) ),
    // Allow a Paragraph block to be moved or removed.
    array( 'core/paragraph', array(
        'placeholder' => 'Add Description...',
        'lock' => array(
            'move'   => false,
            'remove' => false,
        ),
    ) ),
);

嵌套模板

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

$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' => '添加一个内部段落'
            ) ),
        ) ),
    ) )
);