可复用区块样板怎么做才有复用价值

准备：环境与版本现状

2026 年主流生产环境是 WordPress 6.8 与 Gutenberg 插件双轨。区块样板 API 已进入稳定期，但同步样板（Synced Patterns）仍依赖 wp_block 自定义文章类型。开始前请确认：主题已启用 block theme 模式，或至少支持 块编辑器官方文档 所述样板目录。

在 functions.php 同级建 inc/patterns.php，由 functions.php 用 require_once get_template_directory() . '/inc/patterns.php'; 引入。服务器需开启 WP_DEBUG 为 false，避免样板注册警告污染前台。

若你正在评估整站结构，可参考 2026 年 WordPress 建站教程与选服务商决策指南 来规划样板与模板的分工，避免后期返工。

实施步骤

1. 在 inc/patterns.php 中用 register_block_pattern_category 建立业务分类。
2. 用 register_block_pattern 注册普通样板，写入 content 字段为序列化区块标记。
3. 对需要统一改版的模块，用后台「样板→同步样板」界面或代码创建 wp_block 记录作为同步样板。
4. 在样板 content 中加入 lock 属性限制移动与删除。
5. 用 theme.json 或独立模板文件承载页面框架，样板只填内容槽位。
6. 执行 WP-CLI 命令验证注册结果并准备回滚点。

register_block_pattern 与分类

分类不是装饰。没有分类，样板在插入器里会堆成一团，内容团队找不到，复用价值归零。2026 年推荐按「营销组件/文章模块/站点结构」三类切分。

注册分类

在 inc/patterns.php 顶部写：

add_action( 'init', function() {
    register_block_pattern_category(
        'marketing-kit',
        array(
            'label' => _x( '营销组件', 'Block pattern category', 'textdomain' ),
        )
    );
    register_block_pattern_category(
        'post-module',
        array(
            'label' => _x( '文章模块', 'Block pattern category', 'textdomain' ),
        )
    );
} );

注册样板

同一个文件里继续注册普通样板。注意 content 里的尖括号必须转义为 < 与 >，否则 JSON 或 PHP 解析会断。

add_action( 'init', function() {
    register_block_pattern(
        'textdomain/cta-banner',
        array(
            'title'       => __( 'CTA 横幅', 'textdomain' ),
            'categories'  => array( 'marketing-kit' ),
            'content'     => '<!-- wp:group {"lock":{"move":true,"remove":true},"style":{"spacing":{"padding":{"top":"40px","bottom":"40px"}}}} -->
<div class="wp-block-group"><!-- wp:heading {"textAlign":"center"} -->
<h2 class="wp-block-heading has-text-align-center">立即联系</h2>
<!-- /wp:heading --></div>
<!-- /wp:group -->',
        )
    );
} );

为什么这么做：分类让插入器可筛选，lock 让结构不被拖散。验证做对了：进文章编辑页，打开插入器「样板」标签，应看到「营销组件」分类下出现「CTA 横幅」，插入后标题不能删、不能移。

样板锁定 lock

锁定不是全锁死，而是用 lock 对象控制 move 与 remove。上面代码已示范。若只锁移动不锁删除，写 {"move":true} 即可。

常见踩坑

• 把 lock 写在 group 外层却忘了里层 heading，内层仍可删；要逐层加。
• 用错单双引号导致 JSON 失效；PHP 数组里用双引号包 HTML 时，内部属性一律单引号。
• 锁定后客户想改文案却发现连文字都选不中——那是锁错了对象，应锁容器不锁文本块。

失败回退：注释掉对应 register_block_pattern 调用，或把 lock 字段删掉重新注册，样板即恢复自由编辑。

同步样板 vs 普通样板

普通样板是插入时的快照，改一处不影响旧文；同步样板基于 wp_block，后台改一次，全站引用处同步变。2026 年同步样板仍走「外观→样板→同步样板」管理界面。

怎么做

在后台新建同步样板「全局页脚」，得到 wp_block 文章。之后在任意页面用块插入器选它。代码层面读取：

$footer = get_post( 123 ); // 123 为 wp_block ID
echo apply_filters( 'the_content', $footer->post_content );

验证：改后台那个同步样板的电话，刷新前台任意文章，页脚电话应全变。普通样板则不会。

踩坑：把高频改版的营销条做成普通样板，结果 50 篇文章各改一遍——这就是没分清边界。回退：把同步样板导出为普通样板代码，注销后台记录即可降级。

样板与模板的边界

模板（templates/ 下 index.html 等）定页面骨架与全局区域；样板只填内容槽。若把页眉页脚写进样板，等于用样板干模板的活，多语言站会失控。

我们的 WordPress 企业网站开发 服务页提到，结构层用 theme.json 与模板锁定，内容层才交给样板，这样复用才干净。

验证边界做对了：切换主题时，模板变但样板内容仍在库中可复用；若样板里塞了导航，切主题就丢——那就是越界了。

验证流程

1. 跑 wp pattern list（WP-CLI 需装 wp-cli/pattern-command）看注册项。
2. 前台建测试页，插入每个样板，检查锁定是否生效。
3. 改一次同步样板，确认引用页同步更新。
4. 用 git diff 看 inc/patterns.php 有无语法错。
5. 让非技术编辑试插，记录找不到分类的反馈。

回滚方法

普通样板出问题：删 register_block_pattern 调用或改版本号重注册。同步样板出问题：后台移入回收站，引用处自动 fallback 为空。模板越界：把样板内容迁回 templates/ 并清缓存。

每次上线前用 wp db export 存一份，回滚直接 wp db import。

常见问题

样板插入后编辑说找不到分类怎么办？

检查是否只注册了样板没注册分类；分类 slug 必须和 categories 数组一致，且 label 不能为空。

同步样板改了但前台没变？

先清对象缓存与页面缓存；再确认引用的是 wp_block 而非普通样板快照，两者在插入器里图标不同。

lock 导致客户不能改字怎么修？

把 lock 从文本块移到外层 group，保留 move 限制但放开内部编辑。

动作清单

• 今天就在 inc/patterns.php 建两个业务分类并各注册一个样板。
• 给所有容器块加 lock，文本块不加。
• 把全站重复模块盘点一遍，决定哪些走同步样板。
• 用 WP-CLI 验证注册列表并导出数据库备份。
• 让内容团队试插并回收「找不到」的反馈。

需要把样板体系落到企业站？看我们的 WordPress 企业网站开发 或直接联系评估。

“, “faq”: [{“question”: “样板插入后编辑说找不到分类怎么办？”, “answer”: “检查是否只注册了样板没注册分类；分类 slug 必须和 categories 数组一致，且 label 不能为空。”}, {“question”: “同步样板改了但前台没变？”, “answer”: “先清对象缓存与页面缓存；再确认引用的是 wp_block 而非普通样板快照，两者在插入器里图标不同。”}, {“question”: “lock 导致客户不能改字怎么修？”, “answer”: “把 lock 从文本块移到外层 group，保留 move 限制但放开内部编辑。”}], “cover”: “Flat technical illustration of modular content blocks being reused across page templates, abstract geometric shapes, no text, no letters, no numbers, no logo, no watermark, blue and gray palette, 1200×630 composition.

参考资料与延伸阅读

• WordPress 开发者文档
• WordPress 主题开发手册
• WordPress 插件开发手册