模板

最后更新：2026-10-17 10:55:29

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

模板的范围包括：

在客户端动态设置默认状态。（例如 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 文件。

自定义文章类型

自定义文章类型可以在注册期间注册自己的模板：

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 区域的锁定。如果区块是顶级区块，则使用当前文章类型的锁定配置。

单个区块锁定

除了模板级别的锁定外，您还可以锁定单个区块；您可以使用属性级别的 lock 属性来执行此操作。区块级别的锁定优先于 templateLock 功能。目前，您可以锁定移动和删除区块。

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

选项：

remove — 锁定区块被删除的能力。
move — 锁定区块被移动的能力。

您可以将此与 templateLock 结合使用，通过在 remove 或 move 中使用 false 来锁定所有区块，除了单个区块。

$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,
        ),
    ) ),
);

嵌套模板

容器区块（如列区块）也支持模板。这是通过将嵌套模板分配给区块来实现的。

$template = array(
    array( 'core/paragraph', array(
        'placeholder' => 'Add a root-level paragraph',
    ) ),
    array( 'core/columns', array(), array(
        array( 'core/column', array(), array(
            array( 'core/image', array() ),
        ) ),
        array( 'core/column', array(), array(
            array( 'core/paragraph', array(
                'placeholder' => 'Add an inner paragraph'
            ) ),
        ) ),
    ) )
);