wordpress-block-theming

WordPress 区块主题技能

全面掌握使用全站编辑（FSE）架构构建 WordPress 区块主题所需的知识。

绝对规则

• 禁止使用表情符号：生成的内容中任何地方都不得使用表情符号，包括标题、段落、按钮文本或任何其他文本。此规则适用于所有模板、样式和内容。

主题架构

目录结构

theme-slug/
├── theme.json           # Central configuration file
├── style.css            # Theme metadata + custom CSS
├── functions.php        # Asset enqueuing, pattern registration
├── templates/           # Block templates
│   ├── index.html       # Main/fallback template
│   ├── single.html      # Single post
│   ├── page.html        # Single page
│   ├── archive.html     # Archive listings
│   ├── search.html      # Search results
│   └── 404.html         # Not found
├── parts/               # Reusable template parts
│   ├── header.html      # Site header
│   └── footer.html      # Site footer
└── patterns/            # Block patterns
    ├── hero.php
    ├── features.php
    └── cta.php

theme.json 配置

theme.json 文件是区块主题的核心配置文件。它定义了：

Schema 和版本

{
  "$schema": "https://schemas.wp.org/trunk/theme.json",
  "version": 3
}

设置

定义编辑器中可用的选项：

{
  "settings": {
    "appearanceTools": true,
    "layout": { "contentSize": "800px", "wideSize": "1280px" },
    "color": {
      "palette": [ /* 5 colors: primary, secondary, accent, light, dark */ ],
      "defaultPalette": false,
      "defaultGradients": false
    },
    "typography": {
      "fontFamilies": [ /* heading + body font families */ ],
      "fontSizes": [ /* 5-6 step scale: small through huge */ ]
    },
    "spacing": {
      "units": ["px", "em", "rem", "%", "vw", "vh"],
      "spacingSizes": [ /* 6 steps from compact to spacious */ ]
    }
  }
}

样式

定义网站和区块的默认样式：

{
  "styles": {
    "color": { /* background + text from palette */ },
    "typography": { /* body font family, medium size, line-height 1.5-1.65 */ },
    "elements": {
      "heading": { /* heading font family, appropriate weight, line-height 1.1-1.3 */ },
      "link": { /* accent color */ },
      "button": { /* accent background, light text, border-radius */ }
    }
  }
}

排版

• 选择美观、独特且有趣的字体。避免使用 Arial 和 Inter 等通用字体，改用能提升前端美感的独特选择，尝试出人意料且富有个性的字体。将独特的展示字体与精致的正文字体搭配。
• 字号比例：保持字号实用、适中。正文：1rem。标题：适度递增（h1 ≤ 2.5–3rem）。使用 clamp() 设置响应式展示文本，但最大值控制在约 3.5rem。避免使用超过 4rem 的“超大”字号——这类字号很少能改善设计，往往还会损害设计效果。推荐使用 6 级字号比例：0.875rem / 1rem / 1.25rem / 1.75rem / 2.25rem / clamp(2.5rem, 4vw, 3.5rem)。
• 行高：正文：1.5–1.65。标题：1.1–1.3。任何文本的行高都不得低于 1.0。在 theme.json 中通过 styles.typography.lineHeight 和 styles.elements.heading.typography.lineHeight 设置。

区块模板

模板使用 WordPress 区块标记（带有 JSON 属性的 HTML 注释）。

模板结构

<main class="wp-block-group">
  
</main>

模板部件

页眉要求

• 使用适合网站背景色的受限布局组
• 弹性行布局：site-title（级别：0——渲染为 <p> 而非 <h1>）+ navigation
• 使用适当的间距预设设置内边距

页脚要求

• 使用受限布局组，样式与页眉一致或相互补充
• 内容根据网站类型而异（版权信息、社交链接、联系信息等）
• 在 style.css 中重置页脚外边距

区块样式

样式是用于注册可重复使用区块内容的 PHP 文件。

样式注册

<?php
/**
 * Title: Hero Section
 * Slug: theme-slug/hero
 * Categories: featured
 */
?>

...

functions.php

保持 functions.php 简洁。主要用途：

引入 Google Fonts

重要： 始终使用 enqueue_block_assets 钩子（而非 wp_enqueue_scripts），确保字体在前端和区块编辑器中都能加载。

<?php
/**
 * Theme functions and definitions
 */

// Enqueue Google Fonts and theme stylesheet for both front-end and block editor
function theme_slug_enqueue_assets() {
    wp_enqueue_style(
        'theme-slug-fonts',
        'https://fonts.googleapis.com/css2?family=Clash+Display:wght@400;500;600;700&family=DM+Sans:wght@400;500;600&display=swap',
        array(),
        null
    );

    wp_enqueue_style(
        'theme-slug-style',
        get_stylesheet_uri(),
        array( 'theme-slug-fonts' ),
        wp_get_theme()->get( 'Version' )
    );
}
add_action( 'enqueue_block_assets', 'theme_slug_enqueue_assets' );

// Register block patterns
function theme_slug_register_patterns() {
    register_block_pattern_category(
        'theme-slug',
        array( 'label' => __( 'Theme Patterns', 'theme-slug' ) )
    );
}
add_action( 'init', 'theme_slug_register_patterns' );

生成代码中的安全性

• 当 functions.php 输出任何来自用户的数据时，使用 WordPress 转义函数：
  • HTML 上下文：esc_html()
  • 属性上下文：esc_attr()
  • URL 上下文：esc_url()
• 生成的主题代码中不得使用 eval()、create_function()、shell_exec()、exec() 或 system()
• 带有硬编码内容的静态区块主题（默认情况）无需转义——WordPress 核心区块会处理这些内容。仅当生成用于渲染动态数据的 PHP 时才需要转义。

style.css

style.css 文件包含主题元数据和自定义 CSS。 重要 始终将设计中无法通过 theme.json 实现的自定义 CSS 添加到 style.css，尤其是对设计美感至关重要的布局和构图技巧，例如动画/动态效果。

/*
Theme Name: Theme Name
Theme URI: https://example.com
Author: Author Name
Author URI: https://example.com
Description: A beautiful WordPress block theme
Version: 1.0.0
Requires at least: 6.0
Tested up to: 6.7
Requires PHP: 7.4
License: GNU General Public License v2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html
Text Domain: theme-slug
*/

区块主题中的动画和动态效果

动画能为区块主题增添活力，但 WordPress 区块标记需要采用特定模式，才能将 CSS 动画应用到区块。

className 模式

通过 className JSON 属性为区块添加动画类。WordPress 会将其渲染为包装 div 上的类：

<div class="wp-block-group alignfull fade-up">
  
</div>

此方法适用于任何区块——组、列、标题、段落、按钮和图像：

<h2 class="wp-block-heading slide-in-left">Features</h2>



<div class="wp-block-columns alignwide stagger-children">
  ...
</div>

style.css 中的动画类

在每个主题的 style.css 中生成并调整以下类（这些仅为示例，不要局限于此）：

入场动画：

.fade-up {
  opacity: 0;
  transform: translateY(30px);
  animation: fadeUp 0.6s ease forwards;
}
.fade-in {
  opacity: 0;
  animation: fadeIn 0.6s ease forwards;
}
.slide-in-left {
  opacity: 0;
  transform: translateX(-40px);
  animation: slideIn 0.7s ease forwards;
}
.slide-in-right {
  opacity: 0;
  transform: translateX(40px);
  animation: slideIn 0.7s ease forwards;
}

@keyframes fadeUp { to { opacity: 1; transform: translateY(0); } }
@keyframes fadeIn { to { opacity: 1; } }
@keyframes slideIn { to { opacity: 1; transform: translateX(0); } }

子元素错落动画 — 通过 nth-child 应用延迟：

.stagger-children > * {
  opacity: 0;
  transform: translateY(20px);
  animation: fadeUp 0.5s ease forwards;
}
.stagger-children > *:nth-child(1) { animation-delay: 0.1s; }
.stagger-children > *:nth-child(2) { animation-delay: 0.2s; }
.stagger-children > *:nth-child(3) { animation-delay: 0.3s; }
.stagger-children > *:nth-child(4) { animation-delay: 0.4s; }

交互过渡效果：

.hover-lift {
  transition: transform 0.2s ease, box-shadow 0.2s ease;
}
.hover-lift:hover {
  transform: translateY(-4px);
  box-shadow: 0 12px 24px rgba(0,0,0,0.15);
}
.hover-glow {
  transition: box-shadow 0.3s ease;
}
.hover-glow:hover {
  box-shadow: 0 0 20px rgba(var(--wp--preset--color--accent-rgb, 0,0,0), 0.3);
}

持续的环境动效：

.float {
  animation: float 3s ease-in-out infinite;
}
@keyframes float {
  0%, 100% { transform: translateY(0); }
  50% { transform: translateY(-10px); }
}
.pulse-subtle {
  animation: pulse 2s ease-in-out infinite;
}
@keyframes pulse {
  0%, 100% { opacity: 1; }
  50% { opacity: 0.7; }
}

通过 functions.php 实现滚动触发显示

最具影响力的动画模式——随着用户滚动逐步显示区块——需要一段简短的 IntersectionObserver 脚本。将其添加到 functions.php：

// Enqueue scroll animation observer
function theme_slug_scroll_animations() {
    wp_add_inline_script( 'theme-slug-style', "
        document.addEventListener('DOMContentLoaded', function() {
            var els = document.querySelectorAll('.animate-on-scroll');
            if (!els.length) return;
            var observer = new IntersectionObserver(function(entries) {
                entries.forEach(function(entry) {
                    if (entry.isIntersecting) {
                        entry.target.classList.add('is-visible');
                        observer.unobserve(entry.target);
                    }
                });
            }, { threshold: 0.15 });
            els.forEach(function(el) { observer.observe(el); });
        });
    " );
}
add_action( 'enqueue_block_assets', 'theme_slug_scroll_animations' );

注意： wp_add_inline_script 需要已有已注册的脚本句柄。由于区块主题不一定总有已注册的脚本，更可靠的做法是直接输出脚本：

// Scroll animation observer — outputs inline script
function theme_slug_scroll_animations() {
    ?>
    <script>
    document.addEventListener('DOMContentLoaded', function() {
        var els = document.querySelectorAll('.animate-on-scroll');
        if (!els.length) return;
        var observer = new IntersectionObserver(function(entries) {
            entries.forEach(function(entry) {
                if (entry.isIntersecting) {
                    entry.target.classList.add('is-visible');
                    observer.unobserve(entry.target);
                }
            });
        }, { threshold: 0.15 });
        els.forEach(function(el) { observer.observe(el); });
    });
    </script>
    <?php
}
add_action( 'wp_footer', 'theme_slug_scroll_animations' );

然后在 style.css 中配套添加 CSS，让元素初始时隐藏，并在添加 .is-visible 后播放动画：

.animate-on-scroll {
  opacity: 0;
  transform: translateY(30px);
  transition: opacity 0.6s ease, transform 0.6s ease;
}
.animate-on-scroll.is-visible {
  opacity: 1;
  transform: translateY(0);
}

在区块级 Group 区块上使用 className: "animate-on-scroll"：

<div class="wp-block-group alignfull animate-on-scroll">
  
</div>

prefers-reduced-motion（必需）

每个主题都必须在 style.css 中包含以下内容：

@media (prefers-reduced-motion: reduce) {
  *, *::before, *::after {
    animation-duration: 0.01ms !important;
    transition-duration: 0.01ms !important;
  }
}

动画的使用量

并非每个元素都需要动画。优先为以下元素添加动画：

• Hero 区块入场 — 打造第一印象（淡入上移、缩放或滑入）
• 滚动时显示区块 — 使用 animate-on-scroll 为主要内容区块添加动画
• 交互元素 — 使用 hover-lift 为卡片添加悬停效果，为按钮添加过渡效果
• 1-2 个装饰性环境动效 — 浮动形状、渐变变化或脉冲强调效果

避免为每个标题、段落和按钮单独添加动画——这会制造视觉噪声，而非带来愉悦体验。

按行排列的卡片布局

对于等高、等宽的卡片（可选：CTA 底部对齐），除非用户另有说明，否则请使用以下结构：

Columns (className: "equal-cards")
  └── Column
        verticalAlignment: "stretch"
        width: "X%" where X = 100 / number_of_cards (e.g., 2 cards = 50%, 3 cards = 33.33%, 4 cards = 25%)
        └── Group [card wrapper]
              └── [content: headings, paragraphs, images*, lists]
              └── (optional) Buttons (className: "cta-bottom")

宽度规则：同一行中的所有卡片宽度必须相等。将每列宽度计算为 100% / 卡片数量（例如，3 张卡片各占 33.33%）。所有列的宽度总和必须恰好等于 100%——不得超过父元素的宽度。

*卡片中的图片：style="height:200px;object-fit:cover;width:100%"

必需的 CSS（style.css）：

.equal-cards > .wp-block-column {
  display: flex;
  flex-direction: column;
  flex-grow: 0;
}
.equal-cards > .wp-block-column > .wp-block-group {
  display: flex;
  flex-direction: column;
  flex-grow: 1;
}

如果存在底部对齐的 CTA，除非另有说明，否则请确保其保持底部对齐：

.equal-cards .cta-bottom {
  margin-top: auto;
  justify-content: center;
}

始终添加以下 CSS，以重置页脚的上边距：

.wp-site-blocks > footer {
  margin-block-start: 0;
}

着陆页构图

生成首页区块标记时，应像着陆页设计师一样思考，而不是像模板组装者一样。每个区块都应是视觉上鲜明、全宽的区域，让页面在用户滚动时呈现出节奏感和视觉冲击力。

区块架构

• 重置区块边距：为包裹着陆页区块的每个顶层 Group 区块添加 "style":{"spacing":{"margin":{"top":"0"}}}。这会覆盖 .wp-site-blocks 直接子级的 WordPress 默认上边距，用户也可以在编辑器中轻松调整。
• 区块布局宽度：Hero 区块、页眉组、封面区块和功能网格应使用 "align":"wide" 或 "align":"full"，而不是默认的窄内容宽度。只有以文本阅读为主的区块才使用默认（内容）对齐方式。
• 请勿使用 <inner-blocks>；在每个区块中输出完整展开的标记。
• 列对齐方式：除非另有明确指示，否则始终在 wp:columns 区块上设置 "align":"wide"（并在包装器 div 上添加 alignwide 类）。
• 不要添加装饰性 HTML 注释：绝不要在模板、模板部件或样板中插入 或 之类的区块标签注释。只允许使用 WordPress 区块注释（``）。

首页的每个主要区块都必须为 alignfull ——横跨整个视口，铺满边缘。内部内容可以限制宽度，但区块包装器必须填满屏幕宽度。这就是全出血包装器、受限内容模式：

``

**首页区块绝不可只使用 {"layout":{"type":"constrained"}} 而不加 "align":"full"。**若没有 alignfull，区块会以 contentSize（800px）宽度显示，页面看起来就会狭窄乏味。

由你决定哪些区块最适合这个网站。不要遵循僵化的模板。请考虑网站类型、受众和主要目标：

• 作品集需要铺满全宽的项目图库
• SaaS 需要配有明确价值主张的功能网格
• 餐厅需要令人垂涎的图片和菜单区块
• 代理机构需要案例研究卡片和社会认同
• 密室逃脱需要氛围感和沉浸感

视觉节奏

在用户滚动页面时交替使用不同的视觉效果，营造节奏感：

技巧	WordPress 实现方式
交替背景	在 background 和 surface 之间交替设置 backgroundColor（醒目的区块可使用 primary/secondary）
全出血图片	使用 "align":"full" 和品牌调色板中的 overlayColor 设置 Cover 区块
边缘到边缘的媒体与文本	使用 "align":"full" 的 wp:media-text，交替安排图片和内容的位置
醒目的 CTA 横幅	使用全宽 Group 区块，设置 primary 或 accent 背景，并将文本居中
间隔区块	在区块之间使用 wp:spacer，留出呼吸空间

每个区块在视觉上都应与相邻区块有所区别。如果相邻两个区块的背景颜色和布局模式相同，页面就会显得单调——请更换背景、翻转图片位置、将网格改为单列，或插入 Cover 区块作为间隔。

图片处理

初始构建网站时，只添加用户提供的图片/图片 URL。图库图片 URL 在区块编辑器中经常无法加载，导致设计出错。 仔细查看用户提供的图片，并在合适时将其纳入设计；如果图片不适合设计，则不要勉强使用。

不使用图片营造丰富的视觉效果

由于只能使用用户提供的图片／图片 URL，如果没有可用图片，请通过以下方式传递氛围感并提升视觉趣味：

• CSS 渐变：使用线性、径向和锥形渐变营造深度感与色彩效果
• 色块：大胆使用背景色，打造视觉层次
• 将排版作为设计：使用大号、独特的标题；创意搭配字体；调整文字大小和字重
• CSS 图案：使用 CSS 渐变创建重复背景（条纹、圆点、网格）
• 阴影与深度：使用 box-shadow、text-shadow 和 drop-shadow 增强立体感
• 边框与框架：创意运用边框、轮廓和装饰性框架
• 间距与布局：使用充足的留白或可控的紧凑布局营造氛围
• CSS 伪元素：使用 ::before 和 ::after 添加装饰性视觉元素
• 色彩叠加层：使用带透明度的分层 div 营造氛围效果