各位观众老爷们，大家好！我是今天的主讲人，咱们今天聊聊WordPress主题里那个神秘又强大的theme.json文件。别看它名字简单，这货可是WordPress主题样式和全局设置的底层配置大BOSS！想玩转古腾堡编辑器，想打造独一无二的WordPress主题，就必须得摸透它！
一、theme.json是个啥？ 为啥这么重要？
简单来说，theme.json就是一个JSON格式的文件，它定义了WordPress主题的全局样式、配色方案、排版规则、区块默认设置，以及各种各样的功能选项。它就像一个主题的“大脑”，告诉WordPress应该如何渲染和展示内容。
为啥它这么重要？原因如下：
- 古腾堡编辑器的大管家：
theme.json是古腾堡编辑器（WordPress的区块编辑器）的核心配置文件。它控制着编辑器中可用的样式、颜色、字体等等，让用户可以直接在编辑器里调整内容的外观，而无需手动编写CSS。 - 样式一致性的保障： 通过
theme.json，你可以定义一套统一的设计规范，确保整个网站的各个部分都遵循相同的样式规则，避免出现风格不统一的尴尬局面。 - 可维护性大大提升： 传统的WordPress主题，样式都写在CSS文件里，改起来费时费力。有了
theme.json，你可以集中管理全局样式，修改起来更加方便快捷，而且不容易出错。 - 面向未来的主题开发方式： WordPress官方一直在大力推广
theme.json，未来的主题开发将更加依赖它。掌握theme.json，就等于掌握了WordPress主题开发的未来。
二、theme.json的结构： 咱们拆开看看！
一个完整的theme.json文件通常包含以下几个主要部分：
| 节点名称 | 功能描述 |
|---|---|
version |
theme.json的版本号。WordPress会根据版本号来解析文件，确保兼容性。 |
settings |
全局设置，包括颜色、排版、布局、区块默认设置等等。这是theme.json的核心部分，也是我们重点关注的对象。 |
styles |
样式规则，可以定义全局样式、区块样式、元素样式等等。这里的样式规则会覆盖默认样式，并影响网站的最终呈现效果。 |
templateParts |
定义模板部件，例如页眉、页脚、侧边栏等等。模板部件可以重复使用，方便构建复杂的页面布局。 |
patterns |
定义区块模式，例如文章列表、图片画廊、联系表单等等。区块模式是一组预先配置好的区块集合，用户可以直接插入到页面中，节省时间和精力。 |
customTemplates |
自定义模板，允许开发者创建特定的页面模板，例如博客文章模板、产品详情页模板等等。自定义模板可以实现更加灵活的页面布局和内容展示。 |
咱们先来看一个简单的theme.json例子：
{
"version": 2,
"settings": {
"color": {
"palette": [
{
"slug": "primary",
"color": "#007bff",
"name": "Primary"
},
{
"slug": "secondary",
"color": "#6c757d",
"name": "Secondary"
},
{
"slug": "light",
"color": "#f8f9fa",
"name": "Light"
},
{
"slug": "dark",
"color": "#343a40",
"name": "Dark"
}
],
"gradients": [
{
"slug": "vivid-cyan-blue-to-vivid-purple",
"gradient": "linear-gradient(135deg,rgba(6,147,227,1) 0%,rgb(155,81,224) 100%)",
"name": "Vivid cyan blue to vivid purple"
}
]
},
"typography": {
"fontFamilies": [
{
"slug": "system-font",
"fontFamily": "-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Oxygen-Sans, Ubuntu, Cantarell, "Helvetica Neue", sans-serif",
"name": "System Font"
}
],
"fontSizes": [
{
"slug": "small",
"size": "14px",
"name": "Small"
},
{
"slug": "normal",
"size": "16px",
"name": "Normal"
},
{
"slug": "large",
"size": "20px",
"name": "Large"
}
]
}
},
"styles": {
"elements": {
"link": {
"color": {
"text": "var(--wp--preset--color--primary)"
}
}
}
}
}这个例子定义了颜色调色板、渐变色、字体族和字体大小，还设置了链接的颜色。
三、settings节点： 全局设置的秘密基地
settings节点是theme.json中最重要的一部分，它控制着主题的全局设置。咱们来详细看看它都包含哪些内容：
-
color：颜色设置-
palette：颜色调色板，定义了一组可供选择的颜色。你可以为每个颜色指定一个slug（唯一标识符）、color（颜色值）和name（颜色名称）。"color": { "palette": [ { "slug": "primary", "color": "#007bff", "name": "Primary" }, { "slug": "secondary", "color": "#6c757d", "name": "Secondary" } ] }在古腾堡编辑器中，用户就可以直接选择这些预定义的颜色，而不用手动输入颜色值。
-
gradients：渐变色，定义了一组可供选择的渐变色。你可以为每个渐变色指定一个slug、gradient（渐变色值）和name。"color": { "gradients": [ { "slug": "vivid-cyan-blue-to-vivid-purple", "gradient": "linear-gradient(135deg,rgba(6,147,227,1) 0%,rgb(155,81,224) 100%)", "name": "Vivid cyan blue to vivid purple" } ] }在古腾堡编辑器中，用户就可以直接选择这些预定义的渐变色。
link：链接颜色设置。可以设置链接的默认颜色、悬停颜色、访问过的颜色等等。background：背景颜色设置。可以设置网站的默认背景颜色。
-
-
typography：排版设置-
fontFamilies：字体族，定义了一组可供选择的字体。你可以为每个字体指定一个slug、fontFamily（字体名称）和name。"typography": { "fontFamilies": [ { "slug": "system-font", "fontFamily": "-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Oxygen-Sans, Ubuntu, Cantarell, "Helvetica Neue", sans-serif", "name": "System Font" }, { "slug": "my-custom-font", "fontFamily": "MyCustomFont, sans-serif", "name": "My Custom Font" } ] }注意，如果使用自定义字体，需要在主题的CSS文件中引入字体文件。
-
fontSizes：字体大小，定义了一组可供选择的字体大小。你可以为每个字体大小指定一个slug、size（字体大小值）和name。"typography": { "fontSizes": [ { "slug": "small", "size": "14px", "name": "Small" }, { "slug": "normal", "size": "16px", "name": "Normal" }, { "slug": "large", "size": "20px", "name": "Large" } ] }在古腾堡编辑器中，用户就可以直接选择这些预定义的字体大小。
fontWeight：字体粗细。lineHeight：行高。letterSpacing：字间距。textDecoration：文本装饰（例如下划线、删除线）。textTransform：文本转换（例如大写、小写）。
-
-
layout：布局设置contentSize：内容区域的宽度。-
wideSize：宽屏内容区域的宽度。"layout": { "contentSize": "640px", "wideSize": "1200px" }这些设置会影响区块的对齐方式和宽度。
-
blocks：区块默认设置你可以为特定的区块设置默认样式和行为。例如，你可以设置段落的默认字体大小、颜色、行高等等。
"blocks": { "core/paragraph": { "typography": { "fontSize": "normal", "lineHeight": "1.6" }, "color": { "text": "#333" } } }这个例子设置了段落的默认字体大小为normal、行高为1.6、颜色为#333。
-
spacing：间距设置padding：内边距。margin：外边距。
你可以启用或禁用这些间距设置，并定义可供选择的间距值。
-
border：边框设置color：边框颜色。radius：边框圆角。style：边框样式（例如实线、虚线）。width：边框宽度。
-
elements：元素设置你可以为特定的HTML元素设置默认样式。例如，你可以设置链接的默认颜色、字体等等。
"elements": { "link": { "color": { "text": "var(--wp--preset--color--primary)" } } }这个例子设置了链接的默认颜色为主题调色板中的primary颜色。
-
disableCustomColors：禁用自定义颜色如果设置为true，则用户无法在古腾堡编辑器中选择自定义颜色，只能使用主题预定义的颜色调色板。
-
disableCustomFontSizes：禁用自定义字体大小如果设置为true，则用户无法在古腾堡编辑器中选择自定义字体大小，只能使用主题预定义的字体大小。
-
enableCustomLineHeight：启用自定义行高如果设置为true，则用户可以在古腾堡编辑器中设置自定义行高。
-
enableCustomUnits：启用自定义单位如果设置为true，则用户可以使用自定义单位（例如em、rem、vw、vh）来设置字体大小、间距等等。
四、styles节点： 样式规则的战场
styles节点用于定义样式规则，可以覆盖默认样式，并影响网站的最终呈现效果。styles节点可以包含以下几个主要部分：
-
root：根样式根样式会应用到整个网站的根元素（通常是
<html>元素）。"styles": { "root": { "typography": { "fontSize": "16px" }, "color": { "background": "#fff", "text": "#333" } } }这个例子设置了网站的默认字体大小为16px、背景颜色为白色、文本颜色为#333。
-
blocks：区块样式你可以为特定的区块设置样式。例如，你可以设置段落的背景颜色、边框、间距等等。
"styles": { "blocks": { "core/paragraph": { "color": { "text": "#666" }, "spacing": { "padding": { "top": "1em", "bottom": "1em" } } } } }这个例子设置了段落的文本颜色为#666、上下内边距为1em。
-
elements：元素样式你可以为特定的HTML元素设置样式。例如，你可以设置链接的颜色、字体等等。
"styles": { "elements": { "link": { "color": { "text": "var(--wp--preset--color--primary)" }, ":hover": { "color": "var(--wp--preset--color--secondary)" } } } }这个例子设置了链接的默认颜色为主题调色板中的primary颜色，悬停颜色为secondary颜色。
五、templateParts、patterns、customTemplates： 高级用法
-
templateParts：模板部件模板部件是一些可以重复使用的HTML代码片段，例如页眉、页脚、侧边栏等等。你可以使用
templateParts来定义这些模板部件，然后在不同的页面中使用它们。 -
patterns：区块模式区块模式是一组预先配置好的区块集合，用户可以直接插入到页面中，节省时间和精力。你可以使用
patterns来定义这些区块模式，例如文章列表、图片画廊、联系表单等等。 -
customTemplates：自定义模板自定义模板允许开发者创建特定的页面模板，例如博客文章模板、产品详情页模板等等。自定义模板可以实现更加灵活的页面布局和内容展示。
六、实战演练： 打造一个简单的theme.json主题
咱们来创建一个简单的theme.json主题，让大家对theme.json有一个更直观的认识。
-
创建主题文件夹： 在
wp-content/themes目录下创建一个新的主题文件夹，例如my-theme。 -
创建
theme.json文件： 在my-theme文件夹下创建一个名为theme.json的文件，并添加以下内容：
{
"version": 2,
"settings": {
"color": {
"palette": [
{
"slug": "primary",
"color": "#007bff",
"name": "Primary"
},
{
"slug": "secondary",
"color": "#6c757d",
"name": "Secondary"
}
]
},
"typography": {
"fontFamilies": [
{
"slug": "system-font",
"fontFamily": "-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Oxygen-Sans, Ubuntu, Cantarell, "Helvetica Neue", sans-serif",
"name": "System Font"
}
]
}
},
"styles": {
"elements": {
"link": {
"color": {
"text": "var(--wp--preset--color--primary)"
}
}
}
}
}- 创建
index.php文件： 在my-theme文件夹下创建一个名为index.php的文件，并添加以下内容：
<!DOCTYPE html>
<html <?php language_attributes(); ?>>
<head>
<meta charset="<?php bloginfo( 'charset' ); ?>">
<meta name="viewport" content="width=device-width, initial-scale=1">
<link rel="profile" href="http://gmpg.org/xfn/11">
<?php wp_head(); ?>
</head>
<body <?php body_class(); ?>>
<div id="page" class="site">
<a class="skip-link screen-reader-text" href="#content"><?php esc_html_e( 'Skip to content', 'my-theme' ); ?></a>
<header id="masthead" class="site-header">
<div class="site-branding">
<?php
if ( is_front_page() && is_home() ) : ?>
<h1 class="site-title"><a href="<?php echo esc_url( home_url( '/' ) ); ?>" rel="home"><?php bloginfo( 'name' ); ?></a></h1>
<?php else : ?>
<p class="site-title"><a href="<?php echo esc_url( home_url( '/' ) ); ?>" rel="home"><?php bloginfo( 'name' ); ?></a></p>
<?php
endif;
$description = get_bloginfo( 'description', 'display' );
if ( $description || is_customize_preview() ) : ?>
<p class="site-description"><?php echo $description; /* WPCS: xss ok. */ ?></p>
<?php
endif;
?>
</div><!-- .site-branding -->
<nav id="site-navigation" class="main-navigation">
<?php
wp_nav_menu( array(
'theme_location' => 'menu-1',
'menu_id' => 'primary-menu',
) );
?>
</nav><!-- #site-navigation -->
</header><!-- #masthead -->
<div id="content" class="site-content">
<div id="primary" class="content-area">
<main id="main" class="site-main">
<?php
if ( have_posts() ) :
if ( is_home() && ! is_front_page() ) : ?>
<header>
<h1 class="page-title screen-reader-text"><?php single_post_title(); ?></h1>
</header>
<?php
endif;
/* Start the Loop */
while ( have_posts() ) : the_post();
get_template_part( 'template-parts/content', get_post_type() );
endwhile;
the_posts_navigation();
else :
get_template_part( 'template-parts/content', 'none' );
endif;
?>
</main><!-- #main -->
</div><!-- #primary -->
<?php get_sidebar(); ?>
</div><!-- #content -->
<footer id="colophon" class="site-footer">
<div class="site-info">
<a href="<?php echo esc_url( __( 'https://wordpress.org/', 'my-theme' ) ); ?>"><?php printf( esc_html__( 'Proudly powered by %s', 'my-theme' ), 'WordPress' ); ?></a>
<span class="sep"> | </span>
<?php printf( esc_html__( 'Theme: %1$s by %2$s.', 'my-theme' ), 'my-theme', '<a href="http://underscores.me/" rel="designer">Underscores.me</a>' ); ?>
</div><!-- .site-info -->
</footer><!-- #colophon -->
</div><!-- #page -->
<?php wp_footer(); ?>
</body>
</html>- 创建
style.css文件： 在my-theme文件夹下创建一个名为style.css的文件，并添加以下内容：
/*
Theme Name: My Theme
Author: Your Name
*/- 启用主题： 在WordPress后台启用
My Theme主题。
现在，你就可以在古腾堡编辑器中使用theme.json中定义的颜色和字体了。链接的颜色也会变成主题调色板中的primary颜色。
七、高级技巧： 善用CSS变量
theme.json允许你使用CSS变量来引用主题设置。例如，你可以使用var(--wp--preset--color--primary)来引用主题调色板中的primary颜色。这样，当你在theme.json中修改primary颜色时，所有引用该颜色的地方都会自动更新。
例如，在styles节点中，你可以这样设置链接的颜色：
"styles": {
"elements": {
"link": {
"color": {
"text": "var(--wp--preset--color--primary)"
},
":hover": {
"color": "var(--wp--preset--color--secondary)"
}
}
}
}八、总结： theme.json，值得拥有！
theme.json是WordPress主题开发中一个非常重要的文件，它可以让你更加灵活地控制主题的样式和全局设置。掌握theme.json，就等于掌握了WordPress主题开发的未来。希望今天的讲座能帮助大家更好地理解和使用theme.json。
各位，下次再见！