从零开发一个 WordPress 自定义区块：从 theme.json 到区块样式 (2)

准备：环境与目录结构

2026 年 WordPress 已到 6.7+，区块 API 稳定。本地用 wp-env 或 Docker。主题根目录建 /blocks/my-cta/，内含 block.json、index.js、style.scss、editor.scss、render.php。确保 Node 18+ 与 @wordpress/scripts 已装。

若你还在评估整站该用模板还是定制，可参考 模板还是定制：WordPress 建站怎么选，再决定是否自建区块体系。

实施步骤

1. 写 block.json 声明元信息与属性
2. PHP 中用 register_block_type 注册并挂 render_callback
3. 拆编辑器样式与前端样式，接入 theme.json
4. 用 register_block_pattern 做区块样板
5. 构建、插入测试并验证前台输出
6. 出错时按回滚段移除注册

block.json 字段

block.json 是区块唯一真源。2026 年必填：apiVersion 用 3；name 命名空间/区块名；title、category、icon、description；attributes 定义动态数据；editorScript、style、editorStyle 指向构建产物；render 指向 PHP 模板。

{
  'apiVersion': 3,
  'name': 'mytheme/my-cta',
  'title': 'My CTA',
  'category': 'design',
  'icon': 'megaphone',
  'description': 'A custom call to action block.',
  'attributes': {
    'content': { 'type': 'string', 'default': '' },
    'align': { 'type': 'string', 'default': 'wide' }
  },
  'editorScript': 'file:./index.js',
  'style': 'file:./style-index.css',
  'editorStyle': 'file:./index.css',
  'render': 'file:./render.php'
}

注意 JSON 里不能用注释，键名双引号在真实文件里要合法；此处为示例转义。踩坑：apiVersion 2 与 3 的 useOnce 等行为不同，新项目一律 3。

属性类型与默认值

string、number、boolean、object、array 都支持。给 default 能避免 undefined。前台通过 $attributes 读取。

register_block_type 注册

在主题 functions.php 或插件主文件调用。2026 推荐传 block.json 路径，由核心解析。

add_action( 'init', function() {
    register_block_type( __DIR__ . '/blocks/my-cta/block.json' );
} );

若用 render.php，需在 block.json 里指定 render。注册后编辑器出现该区块即成功。失败常因路径错或 init 太早，检查 __DIR__。

带回调的动态渲染

不用 render 字段时，可传数组：register_block_type( 'mytheme/my-cta', [ 'render_callback' => 'my_cta_render' ] ); 适合逻辑复杂场景。

区块样式与前端样式分离

编辑器样式只影响画布，前端样式走 style 句柄。用 @wordpress/scripts 构建，editor.scss 进 index.css，style.scss 进 style-index.css。

theme.json 里在 styles.blocks 下按 mytheme/my-cta 设 presets，实现主题级覆盖而不改区块源码。这是 2026 年推荐做法。

{
  'version': 3,
  'styles': {
    'blocks': {
      'mytheme/my-cta': {
        'color': { 'background': '#f5f5f5' }
      }
    }
  }
}

验证：前台查看源码含 style-index.css 且背景色生效，编辑器里不串样式。回滚：删 theme.json 对应节点并清缓存。

区块样板

样板让用户一键插入预设组合。用 register_block_pattern 在 init 注册。

register_block_pattern(
  'mytheme/cta-hero',
  array(
    'title' => 'CTA Hero',
    'content' => '<!-- wp:mytheme/my-cta {"align":"full"} /-->'
  )
);

样板内容须是序列化区块注释。可在文章编辑器「样板」面板看到即成功。失败多因注释格式错，用官方 区块编辑器手册 校验。

验证与回滚

验证：跑 npm run build，进文章页插入区块，填内容保存，前台查看 DOM 与 CSS。回滚：注释 init 里的 register 调用，或删 blocks 目录，站点恢复原状。

若团队缺人维护这类定制，可了解 WordPress 企业网站开发 服务页，把区块体系交给我们托管。

常见问题

block.json 改了不生效怎么办？

清 opcache 与浏览器缓存，重跑构建；确认 apiVersion 与文件路径。

前台没样式如何排查？

看 style 句柄是否入队，查 style-index.css 是否生成，theme.json version 是否为 3。

样板不显示是什么原因？

检查 register 是否在 init，序列化注释是否转义正确，分类是否过滤。

动作清单

• 初始化 blocks/my-cta 目录并写 block.json
• 在 functions.php 注册 block type
• 拆 editor.scss 与 style.scss 并构建
• 在 theme.json 添加 blocks 样式节点
• 注册至少一个区块样板并测试插入

想让区块开发落地无忧？见 WordPress 企业网站开发，我们提供 2026 年全栈支持。

参考资料与延伸阅读

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