WordPress 主题开发：Patterns（块样板）完全指南

发布于 作者:

WordPress 的 Patterns（官方译名“块样板”）是主题开发中实用的工具之一，没有“之一”。它让你能把一组 Block 保存下来，然后在任意页面、任意位置随时插入。本质上，Patterns 就是一段预置的 Block HTML 代码。对于主题开发者来说，Patterns 的价值已经超越了简单的布局复用——从提供首页布局、加载资源到搭配 Block Locking 控制用户编辑权限，它几乎无处不在。这篇文章要把 Patterns 的方方面面讲透：它是什么、怎么注册、如何与 PHP 配合、如何嵌入模板，以及如何为你的用户提供更精细的编辑体验。

什么是 Patterns？

不必想得太复杂。所谓 Pattern（块样板），就是一段由多个 Block 组合而成的、可重复使用的布局。比如，一个“带标题和按钮的封面图”，或者一个“包含产品图片、价格和购买按钮的卡片”——这些你都可以做成 Pattern。

用户只需要在编辑器里点几下，就能把整个布局插进去，然后替换里面的文字和图片即可。

Patterns 与可复用块（Synced Patterns）的区别

新手特别容易在这两个概念上栽跟头，我直接说重点：

  • 可复用块（从 WordPress 6.3 起叫“同步样板”）：你在任何地方修改它，所有用到它的地方都会跟着变。它存的是内容本身。
  • Patterns（普通块样板）：插进去之后就是一段静态布局，改一个地方不会影响别处。它存的是结构，不是具体内容。

怎么选？一句话：需要内容全球同步，用可复用块；需要给用户一个结构框架，让他们自由填充内容，用 Patterns。

一个典型的反面案例：有人在主题的 /patterns/ 目录下放了一个文件，想让它的内容随主题文件更新而同步，结果发现根本不生效。因为主题 /patterns/ 目录注册的 Patterns 是静态的，数据不会自动同步——这正是“Patterns vs 可复用块”典型的误用场景。

注册 Patterns：两种主流方法

方法一：用 /patterns/ 目录（推荐）

从 WordPress 6.0 开始，这是省事的做法。你只需要在主题根目录下新建一个 /patterns/ 文件夹，然后把每个 Pattern 写成一个 PHP 文件即可。

文件开头必须有标准的 PHP 文档注释，包含 Title 和 Slug（这两项是必须的），其他如 Categories、Description 都是可选但强烈建议加上的。

来看一个示例文件 patterns/hero-section.php：

php

<?php
/**
 * Title: 首页英雄区
 * Slug: mytheme/hero-section
 * Categories: featured, hero
 * Description: 带标题、描述和按钮的全宽英雄区
 * Keywords: 封面, 号召性用语
 * Viewport Width: 1400
 */
?>

<!-- wp:cover {"url":"<?php echo esc_url( get_template_directory_uri() . '/assets/images/hero-bg.jpg' ); ?>","dimRatio":50} -->
<div class="wp-block-cover">
    <div class="wp-block-cover__inner-container">
        <!-- wp:heading {"textAlign":"center","level":1} -->
        <h1 class="has-text-align-center">欢迎来到我的网站</h1>
        <!-- /wp:heading -->

        <!-- wp:paragraph {"align":"center"} -->
        <p class="has-text-align-center">一个用 Block 构建的现代主题</p>
        <!-- /wp:paragraph -->

        <!-- wp:buttons {"layout":{"type":"flex","justifyContent":"center"}} -->
        <div class="wp-block-buttons">
            <!-- wp:button -->
            <div class="wp-block-button">
                <a class="wp-block-button__link wp-element-button" href="#">开始体验</a>
            </div>
            <!-- /wp:button -->
        </div>
        <!-- /wp:buttons -->
    </div>
</div>
<!-- /wp:cover -->

注意：虽然文件是 PHP，但里面的内容完全是 Block 的 HTML 标记（也就是“块标记语言”）。只有在你需要用 PHP 动态输出内容（比如图片路径、国际化文本）时，才需要在 <?php ?> 里写代码。

方法二：用 register_block_pattern() 函数

如果你需要在 functions.php 或插件里动态注册 Pattern，用这个函数就行：

php

function mytheme_register_patterns() {
    register_block_pattern(
        'mytheme/cta-button',
        [
            'title'       => __( '号召性用语按钮', 'mytheme' ),
            'description' => _x( '一个简单的 CTA 按钮组', 'Block pattern description', 'mytheme' ),
            'categories'  => [ 'buttons' ],
            'content'     => '<!-- wp:buttons --><div class="wp-block-buttons"><!-- wp:button --><div class="wp-block-button"><a class="wp-block-button__link wp-element-button">立即购买</a></div><!-- /wp:button --></div><!-- /wp:buttons -->',
        ]
    );
}
add_action( 'init', 'mytheme_register_patterns' );

核心就两点：content 参数里放 Block 的 HTML 代码；整个注册过程挂在 init 钩子上执行。

注销 Pattern：如何去掉不需要的

用 unregister_block_pattern() 函数可以移除任何已注册的 Pattern，包括 WordPress 自带的：

php

// 移除自己主题注册的
unregister_block_pattern( 'mytheme/hero-section' );

// 移除核心自带的（前缀是 core）
unregister_block_pattern( 'core/heading-paragraph' );

如果你的主题完全不想要任何核心自带的 Patterns，也可以直接禁用：

php

add_theme_support( 'disable-custom-patterns' );

在 Patterns 里使用 PHP

Patterns 的 content 本质上是 HTML + Block 标记，但你可以在里面嵌入 PHP 代码来实现动态内容。常见的几个场景：

1. 国际化（多语言支持）

php

<!-- wp:heading -->
<h2><?php esc_html_e( '我们的服务', 'mytheme' ); ?></h2>
<!-- /wp:heading -->

2. 引用主题资源（图片、字体等）

php

<!-- wp:image -->
<figure class="wp-block-image">
    <img src="<?php echo esc_url( get_template_directory_uri() . '/assets/images/logo.svg' ); ?>" alt="Logo" />
</figure>
<!-- /wp:image -->

3. 加载站点数据（导航菜单、新文章等）

php

<!-- wp:navigation {"ref":<?php echo wp_get_nav_menu_object( 'primary' )->term_id; ?>} /-->

注意：Patterns 文件里的 PHP 代码在注册时就会被执行，所以如果你在 register_block_pattern() 的 content 参数里直接用 file_get_contents() 读取另一个文件，里面的 PHP 代码不会被解析——它只会被当作纯文本输出。

在模板中使用 Patterns

在模板文件（index.html、single.html 等）里，可以直接通过 wp:pattern Block 来插入已注册的 Pattern：

html

<!-- wp:pattern {"slug":"mytheme/hero-section"} /-->

这是一种比直接在模板里写全套 Block 标记更干净的做法，尤其是在下面两种情况下：

  • 复用同一个布局：同样的 Pattern 用在多个模板里，改一处全更新。
  • 给用户留余地：用户可以在 Site Editor 里替换掉你指定的 Pattern，换成他们自己的。

比如一个典型的首页模板 home.html：

html

<!-- wp:template-part {"slug":"header"} /-->

<!-- wp:group -->
<div class="wp-block-group">
    <!-- wp:pattern {"slug":"mytheme/hero"} /-->
    <!-- wp:pattern {"slug":"mytheme/features"} /-->
    <!-- wp:pattern {"slug":"mytheme/testimonials"} /-->
</div>
<!-- /wp:group -->

<!-- wp:template-part {"slug":"footer"} /-->

这样写的好处是：模板本身只是“骨架”，具体的布局内容交给了 Patterns 去承载。用户可以在 Site Editor 里自由替换这些 Patterns，而不用动模板结构。

Block Type Patterns：把 Pattern 关联到特定 Block

这是一个容易被忽略但非常实用的功能。通过在注册 Pattern 时指定 blockTypes 参数，你可以让某个 Pattern 出现在特定 Block 的“转换”或“设计”菜单中。

举个例子，你想给网站的“页眉”提供几种不同的设计方案，让用户在编辑页眉时可以直接切换：

php

register_block_pattern(
    'mytheme/header-style-1',
    [
        'title'      => __( '经典页眉', 'mytheme' ),
        'blockTypes' => [ 'core/template-part/header' ],
        'content'    => '<!-- 这里是页眉的 Block 标记 -->',
    ]
);

当用户在 Site Editor 里编辑 Header 模板部件时，右侧的“设计”面板里就会出现你提供的这些方案。

同理，你也可以把 Pattern 绑定到 core/query、core/cover 等任何 Block 上，让你的用户有更多“一键换风格”的选项。

Patterns 与 Block Locking（锁定）

Block Locking 是 WordPress 6.0 引入的 API，它允许你锁定 Block 或 Block 组里的某些部分，防止用户误删或误改。

在 Patterns 里用 Block Locking 特别合适，因为它能帮你“框定”用户的操作边界——用户可以替换文字、图片，但不能把整个结构搞乱。

锁定的三种模式

  1. lock: { "move": true }：不能拖动挪动位置，但能编辑内容。
  2. lock: { "remove": true }：不能删除，但能移动。
  3. lock: { "move": true, "remove": true }：既不能移动也不能删除（完全锁定）。

在 Pattern 中使用锁定

直接把 lock 属性写在外层的 <!-- wp:group --> 或 <!-- wp:cover --> Block 里就行：

php

<!-- wp:group {"lock":{"move":true,"remove":true}} -->
<div class="wp-block-group">
    <!-- wp:heading -->
    <h2>会员专享优惠</h2>
    <!-- /wp:heading -->

    <!-- wp:paragraph -->
    <p>注册即享 9 折，限时一周</p>
    <!-- /wp:paragraph -->

    <!-- wp:buttons -->
    <div class="wp-block-buttons">
        <!-- wp:button -->
        <div class="wp-block-button">
            <a class="wp-block-button__link wp-element-button">立即注册</a>
        </div>
        <!-- /wp:button -->
    </div>
    <!-- /wp:buttons -->
</div>
<!-- /wp:group -->

这个 Pattern 插入后，整体结构被锁死。用户只能修改里面的文字和链接，不能删除整个区域，也不能把它拖到别的位置。有效避免了“用户把布局搞垮了然后找你救场”的尴尬。

总结

Patterns 是 WordPress 主题开发的基石，理解它比学会用一百个 Block 插件都重要。我们梳理了几个核心点：

  • 本质：Patterns 是预置的 Block 布局，存的是结构；可复用块存的是内容，两者不要搞混。
  • 注册：优先用 /patterns/ 目录 + PHP 文件的方式，简单且符合 WordPress 官方习惯；需要动态注册时用 register_block_pattern()。
  • PHP 应用：在 Patterns 里可以用 PHP 做国际化、加载资源、查询数据，但要注意 content 里的 PHP 代码在注册时就会执行。
  • 模板中使用：用 <!-- wp:pattern {"slug":"..."} /--> 在模板里插入 Patterns，让模板保持简洁。
  • Block Type 绑定：通过 blockTypes 把 Pattern 挂到特定 Block 的“设计”菜单中，提供更精细的用户体验。
  • Block Locking：用锁定 API 保护 Patterns 的结构，让用户在安全范围内编辑内容。