如何使用theme.json构建自定义WordPress区块主题：一步步指南

摘要

使用全站编辑（FSE）构建自定义WordPress区块主题可能令人望而生畏，但theme.json简化了这一过程。本指南将引导您设置最小区块主题、在theme.json中定义全局样式（如颜色和排版）以及使用区块标记创建自定义模板。您将学习添加区块模式和样式变体，从而实现无需PHP模板文件的完全可设计网站。我们将涵盖常见错误，例如混合经典主题和区块主题功能，并展示如何测试您的主题。最后，您将拥有一个现代化、可扩展且可投入生产的区块主题。这种方法利用WordPress的最新功能，实现更快、更直观的开发。

引言

全站编辑（FSE）彻底改变了WordPress主题开发，让您可以直观地设计网站的每个部分。但许多开发者仍依赖经典主题，或难以从头创建区块主题。解锁FSE能力的关键是theme.json——一个控制全局样式、设置和模板的配置文件。本文提供了一份实用的一步步指南，教您如何使用theme.json构建自定义区块主题。您将学习设置文件夹结构、定义调色板和排版预设、使用区块标记创建自定义模板以及添加样式变体。最后，您将拥有一个易于维护和扩展的生产级区块主题。让我们深入探索，揭开FSE开发的神秘面纱。

要更广泛地了解FSE如何塑造WordPress设计的未来，请查看Gutenberg FSE：2026年WordPress设计的未来。

1. 设置最小区块主题

一个区块主题至少需要两个文件：style.css和index.html。让我们创建它们。

文件夹结构

在wp-content/themes/目录中创建一个名为my-block-theme的文件夹。内部放置：

• style.css
• index.html
• （可选）theme.json

style.css

尽管区块主题较少依赖CSS，但style.css仍是主题识别所必需的：

/*
Theme Name: My Block Theme
Theme URI: https://example.com
Author: Your Name
Description: A custom block theme built with theme.json.
Version: 1.0
Requires at least: 5.9
Tested up to: 6.5
Requires PHP: 7.4
License: GPL v2 or later
Text Domain: my-block-theme
*/

Requires at least: 5.9行确保主题能与FSE功能配合使用。

index.html

这是您的后备模板。它必须以区块标记开头。创建一个简单布局：

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

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

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

这使用了区块语法来包含页眉和页脚模板部分，并显示文章标题和内容。

注意事项： 区块主题不得包含如header.php或footer.php之类的PHP模板文件。混合经典模板和区块模板会破坏FSE。

激活主题

通过FTP或zip安装上传文件夹，然后激活它。您应该会看到一个空白站点，带有最小结构。接下来，我们将使用theme.json来设置样式。

2. 掌握theme.json：全局样式与设置

theme.json集中管理所有设计控件。它位于主题文件夹的根目录。让我们创建一个包含颜色和排版设置的theme.json。

基本结构

{
    "version": 2,
    "settings": {
        "color": {
            "palette": [
                {
                    "slug": "primary",
                    "color": "#007cba",
                    "name": "Primary"
                },
                {
                    "slug": "secondary",
                    "color": "#005a87",
                    "name": "Secondary"
                },
                {
                    "slug": "background",
                    "color": "#ffffff",
                    "name": "Background"
                }
            ],
            "gradients": []
        },
        "typography": {
            "fontFamilies": [
                {
                    "fontFamily": "-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif",
                    "slug": "system",
                    "name": "System"
                },
                {
                    "fontFamily": "'Georgia', serif",
                    "slug": "serif",
                    "name": "Serif"
                }
            ],
            "fontSizes": [
                {
                    "slug": "small",
                    "size": "14px",
                    "name": "Small"
                },
                {
                    "slug": "medium",
                    "size": "18px",
                    "name": "Medium"
                },
                {
                    "slug": "large",
                    "size": "24px",
                    "name": "Large"
                }
            ]
        },
        "spacing": {
            "padding": true,
            "margin": true,
            "units": ["px", "em", "rem"]
        }
    },
    "styles": {
        "color": {
            "background": "var(--wp--preset--color--background)",
            "text": "var(--wp--preset--color--primary)"
        },
        "typography": {
            "fontFamily": "var(--wp--preset--font-family--system)",
            "fontSize": "var(--wp--preset--font-size--medium)"
        }
    }
}

这定义了一个调色板、字体系列、字号和全局样式。var()函数引用了WordPress自动生成的CSS自定义属性。用户之后可以在站点编辑器中更改这些值。

提示： 使用CSS自定义属性以获得一致性。避免在CSS文件中硬编码值；让theme.json成为唯一事实来源。

3. 创建自定义模板

区块模板是带有区块标记的HTML文件。它们遵循类似经典模板文件的层次结构。例如，为单篇文章创建single.html：

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

<!-- wp:group {"tagName":"main","layout":{"type":"constrained"}} -->
<main class="wp-block-group">
    <!-- wp:post-title {"level":1} /-->
    <!-- wp:post-featured-image /-->
    <!-- wp:post-content /-->
    <!-- wp:post-navigation-link {"type":"previous"} /-->
    <!-- wp:post-navigation-link {"type":"next"} /-->
</main>
<!-- /wp:group -->

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

类似地，创建page.html、archive.html等。您还可以通过在查询循环内添加wp:post-template区块来创建自定义模板。

对于高级自定义，考虑构建自定义区块。了解方法请参阅超越基本区块：打造自定义Gutenberg区块以增强WordPress功能。

模板部分

创建一个parts/文件夹用于可重用部分。例如，header.html：

<!-- wp:group {"tagName":"header","layout":{"type":"flex","flexWrap":"nowrap"}} -->
<header class="wp-block-group">
    <!-- wp:site-logo /-->
    <!-- wp:navigation {"themeLocation":"primary"} /-->
</header>
<!-- /wp:group -->

以及footer.html：

<!-- wp:paragraph {"align":"center"} -->
<p class="has-text-align-center">&copy; 2025 My Site</p>
<!-- /wp:paragraph -->

4. 添加区块模式和样式变体

区块模式是预设计的布局。在patterns/文件夹中定义它们。创建patterns/hero.php：

<?php
/**
 * Title: Hero
 * Slug: my-block-theme/hero
 * Categories: hero
 */
?>
<!-- wp:cover {"overlayColor":"primary","minHeight":50,"align":"full"} -->
<div class="wp-block-cover alignfull" style="min-height:50vh">
    <span aria-hidden="true" class="wp-block-cover__background has-primary-background-color"></span>
    <div class="wp-block-cover__inner-container">
        <!-- wp:heading {"textAlign":"center","level":1,"style":{"color":{"text":"#ffffff"}}} -->
        <h1 class="has-text-align-center has-text-color" style="color:#ffffff">欢迎</h1>
        <!-- /wp:heading -->
        <!-- wp:paragraph {"align":"center","textColor":"white"} -->
        <p class="has-text-align-center has-white-color">这是一个自定义英雄区域</p>
        <!-- /wp:paragraph -->
    </div>
</div>
<!-- /wp:cover -->

样式变体允许用户切换整体外观。创建styles/default.json和styles/dark.json来覆盖主题设置。

5. 注意事项与最佳实践

• 性能： theme.json会被缓存。更改后清除缓存。如有需要，可使用wp_register_theme_json钩子。
• 向后兼容性： 区块主题仅在WordPress 5.9及以上版本中有效。如果您的网站必须支持较旧版本，可考虑混合方法，但避免混合模板文件。
• 子主题： 区块主题可作为经典子主题的父主题，但反之则不行。在style.css中使用template来声明父区块主题。
• 国际化： 在PHP模板部分中使用__()函数来处理可翻译字符串。在区块标记中，通过textDomain属性指定文本域。

有关插件开发最佳实践的更多信息，请参阅构建稳健的WordPress插件：最佳实践实用指南。

结论

使用theme.json构建自定义区块主题让您能够创建一个完全可设计且无需接触PHP的网站。通过遵循本指南，您已经设置了一个最小主题、定义了全局样式、创建了自定义模板并添加了模式。请务必进行彻底测试，特别是对于存档页或自定义文章类型等边缘情况。随着WordPress的发展，区块主题将成为标准。立即开始利用FSE来简化您的工作流程，并为客户提供无与伦比的灵活性。

如果您想进一步加快主题创建速度，可以考虑使用一个能根据描述生成完整网站的工具。例如，您可以描述所需的布局，几分钟内即可获得一个可用的区块主题。

准备将您的区块主题上线？只需一段纯文本描述，即可生成一个功能齐全的落地页或网站——无需编码。