WordPress全站编辑（FSE）与区块编辑器指南：theme.json配置与站点编辑器实战

wordpress-block-editor-fse by bobmatnyc/claude-mpm-skills

160 周安装量

28 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/bobmatnyc/claude-mpm-skills --skill wordpress-block-editor-fse

内容管理系统网站优化 WordPress

🇨🇳中文介绍

WordPress 区块编辑器与全站编辑

概述

全站编辑（FSE）已可用于生产环境（自 WP 6.2 起），并将所有内容（包括页眉、页脚、模板，而不仅仅是内容）都视为区块。区块主题使用 HTML 模板 + theme.json，而非 PHP 文件 + style.css。

关键组件：

theme.json : 集中管理颜色、排版、间距、布局
HTML 模板 : 基于区块的文件（index.html、single.html）
模板部件 : 可复用组件（header.html、footer.html）
区块模式 : 预设计的区块布局
站点编辑器 : 可视化模板定制

适用场景： ✅ 新主题、统一的设计系统、非技术用户的定制 ❌ 复杂的服务器逻辑、团队不熟悉区块、重度依赖 PHP

全站编辑架构

区块主题 vs 经典主题

区块主题	经典主题
包含区块的 HTML 文件	包含模板标签的 PHP 文件
theme.json + CSS	functions.php + style.css
站点编辑器（可视化）	定制器（设置）
用户编辑模板	定制能力有限

站点编辑器功能

模板编辑（页面、文章、归档页）

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

自动生成的 CSS 自定义属性

颜色：var(--wp--preset--color--primary)
字体：var(--wp--preset--font-family--system)
尺寸：var(--wp--preset--font-size--large)
间距：var(--wp--preset--spacing--50)

带有 fluid: { min, max } 的字体尺寸会使用 clamp() 自动缩放：

{
  "slug": "large",
  "size": "1.5rem",
  "fluid": { "min": "1.25rem", "max": "1.5rem" }
}

my-block-theme/
├── style.css                 # 主题元数据（必需）
├── theme.json                # 设置/样式（必需）
├── templates/
│   ├── index.html           # 后备模板（必需）
│   ├── single.html
│   ├── page.html
│   └── archive.html
├── parts/
│   ├── header.html
│   └── footer.html
├── patterns/                 # 区块模式
│   └── hero.php
└── functions.php             # 可选设置

/*
Theme Name: My Block Theme
Requires at least: 6.4
Requires PHP: 8.1
Version: 1.0.0
*/

templates/single.html:

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

<!-- wp:group {"layout":{"type":"constrained"}} -->
<div class="wp-block-group">
  <!-- wp:post-title {"level":1} /-->
  <!-- wp:post-featured-image /-->
  <!-- wp:post-content /-->
  <!-- wp:post-date /-->
</div>
<!-- /wp:group -->

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

templates/index.html（带查询循环）：

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

<!-- wp:group {"tagName":"main"} -->
<main class="wp-block-group">
  <!-- wp:query {"queryId":1,"query":{"perPage":10,"postType":"post"}} -->
  <div class="wp-block-query">
    <!-- wp:post-template {"layout":{"type":"grid","columnCount":3}} -->
      <!-- wp:post-featured-image {"isLink":true} /-->
      <!-- wp:post-title {"isLink":true} /-->
      <!-- wp:post-excerpt /-->
    <!-- /wp:post-template -->

    <!-- wp:query-pagination -->
      <!-- wp:query-pagination-previous /-->
      <!-- wp:query-pagination-numbers /-->
      <!-- wp:query-pagination-next /-->
    <!-- /wp:query-pagination -->
  </div>
  <!-- /wp:query -->
</main>
<!-- /wp:group -->

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

parts/header.html:

<!-- wp:group {"layout":{"type":"flex","justifyContent":"space-between"}} -->
<div class="wp-block-group">
  <!-- wp:site-logo {"width":60} /-->
  <!-- wp:navigation /-->
</div>
<!-- /wp:group -->

patterns/hero.php:

<?php
/**
 * Title: Hero Section
 * Slug: my-theme/hero
 * Categories: featured
 */
?>
<!-- wp:cover {"url":"<?php echo esc_url(get_template_directory_uri()); ?>/assets/images/hero.jpg","dimRatio":50,"minHeight":500,"align":"full"} -->
<div class="wp-block-cover alignfull">
  <div class="wp-block-cover__inner-container">
    <!-- wp:heading {"textAlign":"center","level":1,"fontSize":"xx-large"} -->
    <h1>Welcome to Our Site</h1>
    <!-- /wp:heading -->

    <!-- 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">Get Started</a></div>
      <!-- /wp:button -->
    </div>
    <!-- /wp:buttons -->
  </div>
</div>
<!-- /wp:cover -->

注册模式分类：

add_action('init', 'register_pattern_categories');
function register_pattern_categories() {
  register_block_pattern_category('hero', [
    'label' => __('Hero Sections', 'my-theme')
  ]);
  register_block_pattern_category('cta', [
    'label' => __('Call to Action', 'my-theme')
  ]);
}

自定义区块开发

block.json 元数据（区块 API v3）

blocks/testimonial/block.json:

{
  "$schema": "https://schemas.wp.org/trunk/block.json",
  "apiVersion": 3,
  "name": "my-theme/testimonial",
  "title": "Testimonial",
  "category": "widgets",
  "icon": "format-quote",
  "attributes": {
    "content": {
      "type": "string",
      "source": "html",
      "selector": ".testimonial-content"
    },
    "author": { "type": "string", "default": "" },
    "role": { "type": "string", "default": "" },
    "rating": { "type": "number", "default": 5 }
  },
  "supports": {
    "html": false,
    "align": ["wide", "full"],
    "color": { "background": true, "text": true },
    "spacing": { "padding": true, "margin": true }
  },
  "render": "file:./render.php"
}

从 HTML 提取数据的不同方式：

"attributes": {
  "title": {
    "type": "string",
    "source": "html",
    "selector": "h2"
  },
  "linkUrl": {
    "type": "string",
    "source": "attribute",
    "selector": "a",
    "attribute": "href"
  },
  "isActive": {
    "type": "boolean",
    "default": false
  },
  "items": {
    "type": "array",
    "source": "query",
    "selector": ".item",
    "query": {
      "text": { "type": "string", "source": "text" }
    }
  }
}

服务端渲染（render.php）

blocks/testimonial/render.php:

<?php
$content = $attributes['content'] ?? '';
$author = $attributes['author'] ?? '';
$role = $attributes['role'] ?? '';
$rating = absint($attributes['rating'] ?? 5);

$wrapper_attributes = get_block_wrapper_attributes([
  'class' => 'testimonial-block',
]);
?>

<div <?php echo $wrapper_attributes; ?>>
  <blockquote class="testimonial-content">
    <?php echo wp_kses_post($content); ?>
  </blockquote>

  <?php if ($rating > 0) : ?>
    <div class="testimonial-rating">
      <?php for ($i = 1; $i <= 5; $i++) : ?>
        <span class="star <?php echo $i <= $rating ? 'filled' : 'empty'; ?>">
          <?php echo $i <= $rating ? '★' : '☆'; ?>
        </span>
      <?php endfor; ?>
    </div>
  <?php endif; ?>

  <?php if ($author || $role) : ?>
    <cite class="testimonial-author">
      <span class="author-name"><?php echo esc_html($author); ?></span>
      <?php if ($role) : ?>
        <span class="author-role"><?php echo esc_html($role); ?></span>
      <?php endif; ?>
    </cite>
  <?php endif; ?>
</div>

客户端渲染（React）

blocks/testimonial/index.js:

import { registerBlockType } from '@wordpress/blocks';
import { useBlockProps, RichText, InspectorControls } from '@wordpress/block-editor';
import { PanelBody, RangeControl, TextControl } from '@wordpress/components';
import { __ } from '@wordpress/i18n';

registerBlockType('my-theme/testimonial', {
  edit: ({ attributes, setAttributes }) => {
    const { content, author, role, rating } = attributes;
    const blockProps = useBlockProps();

    return (
      <>
        <InspectorControls>
          <PanelBody title={__('Settings', 'my-theme')}>
            <TextControl
              label={__('Author', 'my-theme')}
              value={author}
              onChange={(v) => setAttributes({ author: v })}
            />
            <TextControl
              label={__('Role', 'my-theme')}
              value={role}
              onChange={(v) => setAttributes({ role: v })}
            />
            <RangeControl
              label={__('Rating', 'my-theme')}
              value={rating}
              onChange={(v) => setAttributes({ rating: v })}
              min={1}
              max={5}
            />
          </PanelBody>
        </InspectorControls>

        <div {...blockProps}>
          <RichText
            tagName="blockquote"
            value={content}
            onChange={(v) => setAttributes({ content: v })}
            placeholder={__('Testimonial text...', 'my-theme')}
          />

          <div className="testimonial-rating">
            {[1, 2, 3, 4, 5].map((star) => (
              <span
                key={star}
                onClick={() => setAttributes({ rating: star })}
              >
                {star <= rating ? '★' : '☆'}
              </span>
            ))}
          </div>

          <cite>
            <RichText
              tagName="span"
              value={author}
              onChange={(v) => setAttributes({ author: v })}
              placeholder={__('Author', 'my-theme')}
            />
          </cite>
        </div>
      </>
    );
  },
  save: () => null, // 服务端渲染
});

add_action('init', 'register_custom_blocks');
function register_custom_blocks() {
  register_block_type(__DIR__ . '/blocks/testimonial');
}

InspectorControls（设置侧边栏）

区块设置的常用控件：

import {
  InspectorControls,
  PanelColorSettings,
  MediaUpload
} from '@wordpress/block-editor';
import {
  PanelBody,
  SelectControl,
  ToggleControl,
  RangeControl,
  Button
} from '@wordpress/components';

<InspectorControls>
  <PanelBody title="Layout">
    <SelectControl
      label="Columns"
      value={columns}
      options={[
        { label: '2', value: 2 },
        { label: '3', value: 3 },
        { label: '4', value: 4 }
      ]}
      onChange={(v) => setAttributes({ columns: parseInt(v) })}
    />

    <ToggleControl
      label="Enable Shadow"
      checked={enableShadow}
      onChange={(v) => setAttributes({ enableShadow: v })}
    />

    <RangeControl
      label="Border Radius"
      value={borderRadius}
      onChange={(v) => setAttributes({ borderRadius: v })}
      min={0}
      max={50}
    />
  </PanelBody>

  <PanelBody title="Media">
    <MediaUpload
      onSelect={(media) => setAttributes({ imageUrl: media.url })}
      allowedTypes={['image']}
      render={({ open }) => (
        <Button onClick={open} variant="secondary">
          {imageUrl ? 'Change Image' : 'Select Image'}
        </Button>
      )}
    />
  </PanelBody>

  <PanelColorSettings
    title="Colors"
    colorSettings={[
      {
        value: bgColor,
        onChange: (v) => setAttributes({ bgColor: v }),
        label: 'Background'
      }
    ]}
  />
</InspectorControls>

启用 WordPress 功能：

"supports": {
  "html": false,
  "anchor": true,
  "align": ["wide", "full"],
  "color": {
    "background": true,
    "text": true,
    "gradients": true
  },
  "spacing": {
    "padding": true,
    "margin": true,
    "blockGap": true
  },
  "typography": {
    "fontSize": true,
    "lineHeight": true,
    "fontWeight": true
  }
}

使用区块编辑器的自定义文章类型

add_action('init', 'register_book_cpt');
function register_book_cpt() {
  register_post_type('book', [
    'labels' => [
      'name' => __('Books', 'my-theme'),
      'singular_name' => __('Book', 'my-theme'),
    ],
    'public' => true,
    'has_archive' => true,
    'supports' => ['title', 'editor', 'thumbnail'],
    'show_in_rest' => true,  // 区块编辑器必需
    'menu_icon' => 'dashicons-book',
    'template' => [          // 默认区块
      ['core/paragraph', ['placeholder' => 'Book description...']],
      ['core/image'],
      ['my-theme/book-details'],
    ],
    'template_lock' => 'insert', // 无法添加/移除区块
  ]);

  // 注册分类法
  register_taxonomy('genre', 'book', [
    'labels' => ['name' => __('Genres', 'my-theme')],
    'hierarchical' => true,
    'show_in_rest' => true,  // 必需
  ]);
}

false: 无限制
'all': 无法修改结构
'insert': 无法添加/移除，但可以重新排序
'contentOnly': 仅可编辑内容

在 theme.json 中注册

"customTemplates": [
  {
    "name": "single-book",
    "title": "Book Template",
    "postTypes": ["book"]
  }
]

{
  "scripts": {
    "start": "wp-scripts start",
    "build": "wp-scripts build"
  },
  "devDependencies": {
    "@wordpress/scripts": "^27.0.0"
  }
}

npm install
npm run start  # 开发环境，带热重载
npm run build  # 生产环境构建（压缩）

{
  "core": "WordPress/WordPress#6.7",
  "phpVersion": "8.3",
  "themes": ["./my-block-theme"],
  "config": {
    "WP_DEBUG": true,
    "SCRIPT_DEBUG": true
  }
}

npx @wordpress/env start
# 访问：http://localhost:8888
# 管理员：admin / password

npx @wordpress/env stop
npx @wordpress/env clean  # 重置数据库

从经典主题迁移

模板标签到区块的映射

经典	区块等效
`the_title()`	`<!-- wp:post-title /-->`
`the_content()`	`<!-- wp:post-content /-->`
`the_post_thumbnail()`	`<!-- wp:post-featured-image /-->`
`the_date()`	`<!-- wp:post-date /-->`
`wp_nav_menu()`	`<!-- wp:navigation /-->`
`get_header()`	`<!-- wp:template-part {"slug":"header"} /-->`
`get_footer()`	`<!-- wp:template-part {"slug":"footer"} /-->`
`get_sidebar()`	`<!-- wp:template-part {"slug":"sidebar"} /-->`

提取设计令牌 从 style.css → theme.json
转换 PHP 模板 为 HTML 区块模板
在 functions.php 中添加区块支持：

add_theme_support('wp-block-styles');

add_theme_support('align-wide');
add_theme_support('responsive-embeds');

4. 使用真实内容进行彻底测试

WordPress 会根据已注册的区块定义验证区块标记。无效的区块会在编辑器中显示错误：

常见的验证错误：

属性类型不匹配（字符串 vs 数字）
缺少必需的属性
不正确的 HTML 结构
更改了属性名称

修复验证错误：

// 为向后兼容性添加已弃用的版本
const deprecated = [
  {
    attributes: {
      oldName: { type: 'string' }
    },
    migrate: (attributes) => ({
      newName: attributes.oldName
    }),
    save: (props) => {
      // 旧的保存函数
    }
  }
];

性能与最佳实践

✅ 尽可能使用服务端渲染（render.php） ✅ 利用区块支持（减少自定义 CSS） ✅ 禁用未使用的功能："defaultPalette": false ✅ 使用 CSS 自定义属性保持一致性 ❌ 避免对静态内容使用客户端渲染 ❌ 不要用 !important 覆盖核心区块

✅ 语义化 HTML（<header>、<main>、<footer>） ✅ 自定义区块的键盘导航 ✅ WCAG AA 颜色对比度（最低 4.5:1） ✅ 所有图片的替代文本 ❌ 不要假设 FSE 就是可访问的（需要测试）

❌ 混合经典和区块方法 ❌ 硬编码颜色（使用 CSS 变量） ❌ 重新发明区块支持 ❌ 跳过可访问性测试 ❌ 在 HTML 模板中使用 get_header()

wordpress-plugin-fundamentals : 钩子系统、CPTs
react : 区块编辑器组件
typescript : 类型安全的区块开发
php-security : 清理区块属性

theme.json 对于区块主题是必需的
HTML 模板在 FSE 中取代了 PHP
服务端渲染通常优于客户端渲染
区块支持减少了自定义代码
可访问性需要测试

超过 5 个 CSS 文件 → 使用 theme.json
HTML 模板中有 PHP 标签 → 使用区块
对静态内容使用客户端渲染 → 使用 render.php
没有进行键盘测试 → 存在可访问性问题
硬编码值 → 使用 CSS 自定义属性

WordPress: 6.7+ | PHP: 8.1+ | 工具: @wordpress/scripts, wp-env

🇺🇸English

WordPress Block Editor & Full Site Editing

Overview

Full Site Editing (FSE) is production-ready (since WP 6.2) and treats everything as blocks—headers, footers, templates, not just content. Block themes use HTML templates + theme.json instead of PHP files + style.css.

Key Components:

theme.json : Centralized colors, typography, spacing, layout
HTML Templates : Block-based files (index.html, single.html)
Template Parts : Reusable components (header.html, footer.html)
Block Patterns : Pre-designed block layouts
Site Editor : Visual template customization

When to Use: ✅ New themes, consistent design systems, non-technical user customization ❌ Complex server logic, team unfamiliar with blocks, heavy PHP dependencies

Full Site Editing Architecture

Block Themes vs Classic Themes

Block Themes	Classic Themes
HTML files with blocks	PHP files with template tags
theme.json + CSS	functions.php + style.css
Site Editor (visual)	Customizer (settings)
User edits templates	Limited customization

Site Editor Capabilities

Template editing (pages, posts, archives)
Template parts (header/footer variations)
Global styles (colors, typography site-wide)
Pattern library (save/reuse block compositions)
Navigation menus (block-based)
Style variations (alternate design presets)

theme.json Configuration

theme.json v3 (WP 6.7) provides centralized design control. WordPress auto-generates CSS custom properties.

Production Example

{
  "$schema": "https://schemas.wp.org/trunk/theme.json",
  "version": 3,
  "settings": {
    "appearanceTools": true,
    "useRootPaddingAwareAlignments": true,
    "layout": {
      "contentSize": "800px",
      "wideSize": "1200px"
    },
    "color": {
      "palette": [
        { "slug": "primary", "color": "#0073aa", "name": "Primary" },
        { "slug": "secondary", "color": "#005177", "name": "Secondary" },
        { "slug": "base", "color": "#ffffff", "name": "Base" },
        { "slug": "contrast", "color": "#000000", "name": "Contrast" }
      ],
      "defaultPalette": false,
      "defaultGradients": false
    },
    "typography": {
      "fontFamilies": [
        {
          "fontFamily": "-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif",
          "slug": "system",
          "name": "System Font"
        }
      ],
      "fontSizes": [
        { "slug": "small", "size": "0.875rem", "name": "Small" },
        { "slug": "medium", "size": "1rem", "name": "Medium" },
        {
          "slug": "large",
          "size": "1.5rem",
          "name": "Large",
          "fluid": { "min": "1.25rem", "max": "1.5rem" }
        }
      ],
      "fontWeight": true,
      "lineHeight": true
    },
    "spacing": {
      "units": ["px", "em", "rem", "vh", "vw", "%"],
      "padding": true,
      "margin": true,
      "spacingSizes": [
        { "slug": "30", "size": "0.5rem", "name": "XS" },
        { "slug": "40", "size": "1rem", "name": "S" },
        { "slug": "50", "size": "1.5rem", "name": "M" },
        { "slug": "60", "size": "2rem", "name": "L" }
      ]
    },
    "border": { "radius": true, "color": true, "width": true }
  },
  "styles": {
    "color": {
      "background": "var(--wp--preset--color--base)",
      "text": "var(--wp--preset--color--contrast)"
    },
    "typography": {
      "fontFamily": "var(--wp--preset--font-family--system)",
      "fontSize": "var(--wp--preset--font-size--medium)",
      "lineHeight": "1.6"
    },
    "elements": {
      "link": {
        "color": { "text": "var(--wp--preset--color--primary)" },
        ":hover": {
          "color": { "text": "var(--wp--preset--color--secondary)" }
        }
      },
      "h1": {
        "typography": {
          "fontSize": "var(--wp--preset--font-size--large)",
          "fontWeight": "700"
        }
      },
      "button": {
        "color": {
          "background": "var(--wp--preset--color--primary)",
          "text": "var(--wp--preset--color--base)"
        },
        "border": { "radius": "4px" },
        ":hover": {
          "color": { "background": "var(--wp--preset--color--secondary)" }
        }
      }
    },
    "blocks": {
      "core/quote": {
        "border": {
          "width": "0 0 0 4px",
          "color": "var(--wp--preset--color--primary)"
        },
        "spacing": { "padding": { "left": "var(--wp--preset--spacing--60)" } }
      }
    }
  },
  "customTemplates": [
    {
      "name": "page-wide",
      "title": "Full Width Page",
      "postTypes": ["page"]
    }
  ]
}

CSS Custom Properties Auto-Generated

Colors: var(--wp--preset--color--primary)
Fonts: var(--wp--preset--font-family--system)
Sizes: var(--wp--preset--font-size--large)
Spacing: var(--wp--preset--spacing--50)

Fluid Typography

Font sizes with fluid: { min, max } auto-scale using clamp():

{
  "slug": "large",
  "size": "1.5rem",
  "fluid": { "min": "1.25rem", "max": "1.5rem" }
}

Block Theme Architecture

Required Files

my-block-theme/
├── style.css                 # Theme metadata (REQUIRED)
├── theme.json                # Settings/styles (REQUIRED)
├── templates/
│   ├── index.html           # Fallback (REQUIRED)
│   ├── single.html
│   ├── page.html
│   └── archive.html
├── parts/
│   ├── header.html
│   └── footer.html
├── patterns/                 # Block patterns
│   └── hero.php
└── functions.php             # Optional setup

style.css Metadata

/*
Theme Name: My Block Theme
Requires at least: 6.4
Requires PHP: 8.1
Version: 1.0.0
*/

HTML Template Structure

templates/single.html:

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

<!-- wp:group {"layout":{"type":"constrained"}} -->
<div class="wp-block-group">
  <!-- wp:post-title {"level":1} /-->
  <!-- wp:post-featured-image /-->
  <!-- wp:post-content /-->
  <!-- wp:post-date /-->
</div>
<!-- /wp:group -->

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

templates/index.html (with query loop):

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

<!-- wp:group {"tagName":"main"} -->
<main class="wp-block-group">
  <!-- wp:query {"queryId":1,"query":{"perPage":10,"postType":"post"}} -->
  <div class="wp-block-query">
    <!-- wp:post-template {"layout":{"type":"grid","columnCount":3}} -->
      <!-- wp:post-featured-image {"isLink":true} /-->
      <!-- wp:post-title {"isLink":true} /-->
      <!-- wp:post-excerpt /-->
    <!-- /wp:post-template -->

    <!-- wp:query-pagination -->
      <!-- wp:query-pagination-previous /-->
      <!-- wp:query-pagination-numbers /-->
      <!-- wp:query-pagination-next /-->
    <!-- /wp:query-pagination -->
  </div>
  <!-- /wp:query -->
</main>
<!-- /wp:group -->

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

Template Parts

parts/header.html:

<!-- wp:group {"layout":{"type":"flex","justifyContent":"space-between"}} -->
<div class="wp-block-group">
  <!-- wp:site-logo {"width":60} /-->
  <!-- wp:navigation /-->
</div>
<!-- /wp:group -->

Block Patterns

patterns/hero.php:

<?php
/**
 * Title: Hero Section
 * Slug: my-theme/hero
 * Categories: featured
 */
?>
<!-- wp:cover {"url":"<?php echo esc_url(get_template_directory_uri()); ?>/assets/images/hero.jpg","dimRatio":50,"minHeight":500,"align":"full"} -->
<div class="wp-block-cover alignfull">
  <div class="wp-block-cover__inner-container">
    <!-- wp:heading {"textAlign":"center","level":1,"fontSize":"xx-large"} -->
    <h1>Welcome to Our Site</h1>
    <!-- /wp:heading -->

    <!-- 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">Get Started</a></div>
      <!-- /wp:button -->
    </div>
    <!-- /wp:buttons -->
  </div>
</div>
<!-- /wp:cover -->

Register pattern categories:

add_action('init', 'register_pattern_categories');
function register_pattern_categories() {
  register_block_pattern_category('hero', [
    'label' => __('Hero Sections', 'my-theme')
  ]);
  register_block_pattern_category('cta', [
    'label' => __('Call to Action', 'my-theme')
  ]);
}

Custom Block Development

block.json Metadata (Block API v3)

blocks/testimonial/block.json:

{
  "$schema": "https://schemas.wp.org/trunk/block.json",
  "apiVersion": 3,
  "name": "my-theme/testimonial",
  "title": "Testimonial",
  "category": "widgets",
  "icon": "format-quote",
  "attributes": {
    "content": {
      "type": "string",
      "source": "html",
      "selector": ".testimonial-content"
    },
    "author": { "type": "string", "default": "" },
    "role": { "type": "string", "default": "" },
    "rating": { "type": "number", "default": 5 }
  },
  "supports": {
    "html": false,
    "align": ["wide", "full"],
    "color": { "background": true, "text": true },
    "spacing": { "padding": true, "margin": true }
  },
  "render": "file:./render.php"
}

Attribute Sources

Different ways to extract data from HTML:

"attributes": {
  "title": {
    "type": "string",
    "source": "html",
    "selector": "h2"
  },
  "linkUrl": {
    "type": "string",
    "source": "attribute",
    "selector": "a",
    "attribute": "href"
  },
  "isActive": {
    "type": "boolean",
    "default": false
  },
  "items": {
    "type": "array",
    "source": "query",
    "selector": ".item",
    "query": {
      "text": { "type": "string", "source": "text" }
    }
  }
}

Server-Side Rendering (render.php)

blocks/testimonial/render.php:

<?php
$content = $attributes['content'] ?? '';
$author = $attributes['author'] ?? '';
$role = $attributes['role'] ?? '';
$rating = absint($attributes['rating'] ?? 5);

$wrapper_attributes = get_block_wrapper_attributes([
  'class' => 'testimonial-block',
]);
?>

<div <?php echo $wrapper_attributes; ?>>
  <blockquote class="testimonial-content">
    <?php echo wp_kses_post($content); ?>
  </blockquote>

  <?php if ($rating > 0) : ?>
    <div class="testimonial-rating">
      <?php for ($i = 1; $i <= 5; $i++) : ?>
        <span class="star <?php echo $i <= $rating ? 'filled' : 'empty'; ?>">
          <?php echo $i <= $rating ? '★' : '☆'; ?>
        </span>
      <?php endfor; ?>
    </div>
  <?php endif; ?>

  <?php if ($author || $role) : ?>
    <cite class="testimonial-author">
      <span class="author-name"><?php echo esc_html($author); ?></span>
      <?php if ($role) : ?>
        <span class="author-role"><?php echo esc_html($role); ?></span>
      <?php endif; ?>
    </cite>
  <?php endif; ?>
</div>

Client-Side Rendering (React)

blocks/testimonial/index.js:

import { registerBlockType } from '@wordpress/blocks';
import { useBlockProps, RichText, InspectorControls } from '@wordpress/block-editor';
import { PanelBody, RangeControl, TextControl } from '@wordpress/components';
import { __ } from '@wordpress/i18n';

registerBlockType('my-theme/testimonial', {
  edit: ({ attributes, setAttributes }) => {
    const { content, author, role, rating } = attributes;
    const blockProps = useBlockProps();

    return (
      <>
        <InspectorControls>
          <PanelBody title={__('Settings', 'my-theme')}>
            <TextControl
              label={__('Author', 'my-theme')}
              value={author}
              onChange={(v) => setAttributes({ author: v })}
            />
            <TextControl
              label={__('Role', 'my-theme')}
              value={role}
              onChange={(v) => setAttributes({ role: v })}
            />
            <RangeControl
              label={__('Rating', 'my-theme')}
              value={rating}
              onChange={(v) => setAttributes({ rating: v })}
              min={1}
              max={5}
            />
          </PanelBody>
        </InspectorControls>

        <div {...blockProps}>
          <RichText
            tagName="blockquote"
            value={content}
            onChange={(v) => setAttributes({ content: v })}
            placeholder={__('Testimonial text...', 'my-theme')}
          />

          <div className="testimonial-rating">
            {[1, 2, 3, 4, 5].map((star) => (
              <span
                key={star}
                onClick={() => setAttributes({ rating: star })}
              >
                {star <= rating ? '★' : '☆'}
              </span>
            ))}
          </div>

          <cite>
            <RichText
              tagName="span"
              value={author}
              onChange={(v) => setAttributes({ author: v })}
              placeholder={__('Author', 'my-theme')}
            />
          </cite>
        </div>
      </>
    );
  },
  save: () => null, // Server-side rendering
});

Block Registration

functions.php:

add_action('init', 'register_custom_blocks');
function register_custom_blocks() {
  register_block_type(__DIR__ . '/blocks/testimonial');
}

InspectorControls (Settings Sidebar)

Common controls for block settings:

import {
  InspectorControls,
  PanelColorSettings,
  MediaUpload
} from '@wordpress/block-editor';
import {
  PanelBody,
  SelectControl,
  ToggleControl,
  RangeControl,
  Button
} from '@wordpress/components';

<InspectorControls>
  <PanelBody title="Layout">
    <SelectControl
      label="Columns"
      value={columns}
      options={[
        { label: '2', value: 2 },
        { label: '3', value: 3 },
        { label: '4', value: 4 }
      ]}
      onChange={(v) => setAttributes({ columns: parseInt(v) })}
    />

    <ToggleControl
      label="Enable Shadow"
      checked={enableShadow}
      onChange={(v) => setAttributes({ enableShadow: v })}
    />

    <RangeControl
      label="Border Radius"
      value={borderRadius}
      onChange={(v) => setAttributes({ borderRadius: v })}
      min={0}
      max={50}
    />
  </PanelBody>

  <PanelBody title="Media">
    <MediaUpload
      onSelect={(media) => setAttributes({ imageUrl: media.url })}
      allowedTypes={['image']}
      render={({ open }) => (
        <Button onClick={open} variant="secondary">
          {imageUrl ? 'Change Image' : 'Select Image'}
        </Button>
      )}
    />
  </PanelBody>

  <PanelColorSettings
    title="Colors"
    colorSettings={[
      {
        value: bgColor,
        onChange: (v) => setAttributes({ bgColor: v }),
        label: 'Background'
      }
    ]}
  />
</InspectorControls>

Block Supports

Enable WordPress features:

"supports": {
  "html": false,
  "anchor": true,
  "align": ["wide", "full"],
  "color": {
    "background": true,
    "text": true,
    "gradients": true
  },
  "spacing": {
    "padding": true,
    "margin": true,
    "blockGap": true
  },
  "typography": {
    "fontSize": true,
    "lineHeight": true,
    "fontWeight": true
  }
}

Custom Post Types with Block Editor

add_action('init', 'register_book_cpt');
function register_book_cpt() {
  register_post_type('book', [
    'labels' => [
      'name' => __('Books', 'my-theme'),
      'singular_name' => __('Book', 'my-theme'),
    ],
    'public' => true,
    'has_archive' => true,
    'supports' => ['title', 'editor', 'thumbnail'],
    'show_in_rest' => true,  // REQUIRED for block editor
    'menu_icon' => 'dashicons-book',
    'template' => [          // Default blocks
      ['core/paragraph', ['placeholder' => 'Book description...']],
      ['core/image'],
      ['my-theme/book-details'],
    ],
    'template_lock' => 'insert', // Can't add/remove blocks
  ]);

  // Register taxonomy
  register_taxonomy('genre', 'book', [
    'labels' => ['name' => __('Genres', 'my-theme')],
    'hierarchical' => true,
    'show_in_rest' => true,  // REQUIRED
  ]);
}

Template Locking

false: No restrictions
'all': Cannot modify structure
'insert': Cannot add/remove, can reorder
'contentOnly': Content edits only

Register in theme.json

"customTemplates": [
  {
    "name": "single-book",
    "title": "Book Template",
    "postTypes": ["book"]
  }
]

Development Workflow

@wordpress/scripts

package.json:

{
  "scripts": {
    "start": "wp-scripts start",
    "build": "wp-scripts build"
  },
  "devDependencies": {
    "@wordpress/scripts": "^27.0.0"
  }
}

Commands:

npm install
npm run start  # Development with hot reload
npm run build  # Production build (minified)

wp-env Setup

.wp-env.json:

{
  "core": "WordPress/WordPress#6.7",
  "phpVersion": "8.3",
  "themes": ["./my-block-theme"],
  "config": {
    "WP_DEBUG": true,
    "SCRIPT_DEBUG": true
  }
}

Usage:

npx @wordpress/env start
# Access: http://localhost:8888
# Admin: admin / password

npx @wordpress/env stop
npx @wordpress/env clean  # Reset database

Migration from Classic Themes

Template Tag to Block Mapping

Classic	Block Equivalent
`the_title()`	`<!-- wp:post-title /-->`
`the_content()`	`<!-- wp:post-content /-->`
`the_post_thumbnail()`	`<!-- wp:post-featured-image /-->`
`the_date()`	`<!-- wp:post-date /-->`

Migration Steps

Extract design tokens from style.css → theme.json
Convert PHP templates to HTML block templates
Add block support in functions.php:

add_theme_support('wp-block-styles');

add_theme_support('align-wide');
add_theme_support('responsive-embeds');

4. Test thoroughly with real content

Block Validation

WordPress validates block markup against registered block definitions. Invalid blocks show errors in the editor:

Common validation errors:

Attribute type mismatch (string vs number)
Missing required attributes
Incorrect HTML structure
Changed attribute names

Fix validation errors:

// Add deprecated versions for backward compatibility
const deprecated = [
  {
    attributes: {
      oldName: { type: 'string' }
    },
    migrate: (attributes) => ({
      newName: attributes.oldName
    }),
    save: (props) => {
      // Old save function
    }
  }
];

Performance & Best Practices

Performance

✅ Use server-side rendering (render.php) when possible ✅ Leverage block supports (reduces custom CSS) ✅ Disable unused features: "defaultPalette": false ✅ Use CSS custom properties for consistency ❌ Avoid client-side rendering for static content ❌ Don't override core blocks with !important

Accessibility

✅ Semantic HTML (<header>, <main>, <footer>) ✅ Keyboard navigation for custom blocks ✅ WCAG AA color contrast (4.5:1 minimum) ✅ Alt text for all images ❌ Don't assume FSE = accessible (test required)

Anti-Patterns

❌ Mixing classic and block approaches ❌ Hardcoding colors (use CSS variables) ❌ Reinventing block supports ❌ Skipping accessibility testing ❌ Using get_header() in HTML templates

Related Skills

wordpress-plugin-fundamentals : Hook system, CPTs
react : Block editor components
typescript : Type-safe block development
php-security : Sanitize block attributes

Key Reminders

theme.json is mandatory for block themes
HTML templates replace PHP in FSE
Server-side rendering often better than client-side
Block supports reduce custom code
Accessibility requires testing

Red Flags

More than 5 CSS files → Use theme.json
PHP tags in HTML templates → Use blocks
Client rendering for static content → Use render.php
No keyboard testing → Accessibility issues
Hardcoded values → Use CSS custom properties

WordPress: 6.7+ | PHP: 8.1+ | Tools: @wordpress/scripts, wp-env

Weekly Installs

108

Repository

bobmatnyc/claud…m-skills

GitHub Stars

First Seen

Jan 23, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykPass

Installed on

opencode86

gemini-cli84

codex80

claude-code78

github-copilot77

cursor76

WordPress路由器：智能识别项目类型并自动选择工作流程的AI技能

733 周安装

WordPress全站编辑（FSE）与区块编辑器指南：theme.json配置与站点编辑器实战

🇨🇳中文介绍

WordPress 区块编辑器与全站编辑

概述

全站编辑架构

区块主题 vs 经典主题

站点编辑器功能

相关 Skills

theme.json 配置

生产环境示例

自动生成的 CSS 自定义属性

流体排版

区块主题架构

必需文件

style.css 元数据

HTML 模板结构

模板部件

区块模式

自定义区块开发

block.json 元数据（区块 API v3）

属性来源

服务端渲染（render.php）

客户端渲染（React）

区块注册

InspectorControls（设置侧边栏）

区块支持

使用区块编辑器的自定义文章类型

模板锁定

在 theme.json 中注册

开发工作流

@wordpress/scripts

wp-env 设置

从经典主题迁移

模板标签到区块的映射

迁移步骤

区块验证

性能与最佳实践

性能

可访问性

反模式

相关技能

关键提醒

危险信号

🇺🇸English

WordPress Block Editor & Full Site Editing

Overview

Full Site Editing Architecture

Block Themes vs Classic Themes

Site Editor Capabilities

theme.json Configuration

Production Example

CSS Custom Properties Auto-Generated

Fluid Typography

Block Theme Architecture

Required Files

style.css Metadata

HTML Template Structure

Template Parts

Block Patterns

Custom Block Development

block.json Metadata (Block API v3)

Attribute Sources

Server-Side Rendering (render.php)

Client-Side Rendering (React)

Block Registration

InspectorControls (Settings Sidebar)

Block Supports

Custom Post Types with Block Editor

Template Locking

Register in theme.json

Development Workflow

@wordpress/scripts

wp-env Setup

Migration from Classic Themes

Template Tag to Block Mapping

Migration Steps

Block Validation

Performance & Best Practices

Performance

Accessibility