Gutenberg 主题支持（Theme Support）完整指南：add_theme_support 配置详解与源码解析

Gutenberg 主题支持（Theme Support）完整指南：add_theme_support 配置详解与源码解析

【免费下载链接】gutenbergThe Block Editor project for WordPress and beyond. Plugin is available from the official repository.项目地址: https://gitcode.com/GitHub_Trending/gu/gutenberg

导读

本文基于 Gutenberg 官方文档 docs/how-to-guides/themes/theme-support.md，系统讲解主题如何通过add_theme_support()启用和定制区块编辑器的各项增强特性——包括颜色/渐变/字号调色板、宽对齐、响应式嵌入、行高与自定义单位、编辑器样式、间距控制、外观工具（Appearance Tools）与块模板部件等。读完本文，你将掌握每个主题支持特性的作用、配置参数、CSS 类生成规则，以及它们与theme.json、源码实现之间的对应关系，能够为经典主题（Classic Theme）精确配置出与区块编辑器深度协同的主题体验。

概述：区块带来新的主题概念

Gutenberg 的新区块在所有主题中提供基线支持（baseline support），无需任何改动即可正常渲染；在此基础上，主题可以选择启用（opt-in）增强特性，也可以扩展和定制这些能力。构建主题时需要理解以下几个新概念：

• 编辑器颜色调色板（Editor Color Palette）：编辑器提供默认颜色集，主题可注册自己的颜色，并可选择将用户锁定在预定义调色板内。
• 编辑器字号调色板（Editor Text Size Palette）：同理，主题可注册自定义字号集合并锁定选择范围。
• 响应式嵌入（Responsive Embeds）：必须由主题显式启用。
• 前端与编辑器样式（Frontend & Editor Styles）：为了获得最佳效果，主题作者需要确保 Core 样式表现良好并选择启用，或编写自己的样式。
• 区块工具（Block Tools）：主题可选择启用行高（line height）、自定义单位（custom units）等工具。
• 核心区块模式（Core Block Patterns）：主题可以选择退出默认区块模式。

默认情况下，区块自带样式，保证主题无需任何改动即可获得基本支持；同时区块还提供一批可选的、带倾向性的样式（opinionated styles）。主题可以追加/覆盖这些样式，也可以完全不加样式、完全依赖区块自带样式。

某些高级区块特性之所以要求主题主动启用，是因为区块自身很难为这些特性提供样式——它们往往需要主题在架构上做出配合才能工作良好。启用方式是在主题的functions.php中调用add_theme_support，例如：

function mytheme_setup_theme_supported_features() { add_theme_support( 'editor-color-palette', array( array( 'name' => esc_attr__( 'strong magenta', 'themeLangDomain' ), 'slug' => 'strong-magenta', 'color' => '#a156b4', ), array( 'name' => esc_attr__( 'light grayish magenta', 'themeLangDomain' ), 'slug' => 'light-grayish-magenta', 'color' => '#d0a5db', ), array( 'name' => esc_attr__( 'very light gray', 'themeLangDomain' ), 'slug' => 'very-light-gray', 'color' => '#eee', ), array( 'name' => esc_attr__( 'very dark gray', 'themeLangDomain' ), 'slug' => 'very-dark-gray', 'color' => '#444', ), ) ); } add_action( 'after_setup_theme', 'mytheme_setup_theme_supported_features' );

需要注意：这些add_theme_support调用需要挂在after_setup_theme钩子上执行，这是 WordPress 主题初始化约定的一部分。

从源码看，主题支持数据最终会被转换并合并进全局样式体系。在 lib/class-wp-theme-json-resolver-gutenberg.php 中，WP_Theme_JSON_Gutenberg::get_from_editor_settings( get_classic_theme_supports_block_editor_settings() )会把主题支持数据转成theme.json的形状，再与theme.json内容合并，且theme.json中声明的预设与设置优先于通过 theme supports 声明的值——这解释了"经典主题用函数、块主题用 theme.json"的边界。

默认块样式（Default Block Styles）与带倾向性样式

默认结构样式

Core 区块自带默认的结构性样式（structural styles），在编辑器与前端默认都会加载。典型例子是 Columns（列）区块的 CSS：如果没有这些规则，区块布局会完全崩溃、根本不呈现任何列。

带倾向性的块样式（Opinionated Block Styles）

区块编辑器允许主题为前端选择启用更"带倾向性"的样式，经典例子是引用（blockquote）左侧的默认色条。经典主题想启用这些样式，只需声明wp-block-styles支持：

add_theme_support( 'wp-block-styles' );

这些样式的来源是 packages/block-library/src/theme.scss，它通过@use聚合了各区块的独立theme.scss（如quote、pullquote、gallery、image、separator、table等 14 个子文件）。例如 packages/block-library/src/quote/theme.scss 中定义了.wp-block-quote的border-left: 0.25em solid currentColor等规则。

启用wp-block-styles后，PHP 端会执行对应的样式替换逻辑。在 lib/blocks.php 中可以看到：当current_theme_supports( 'wp-block-styles' )为真时，插件会注销 Core 的块样式，改为加载build/styles/block-library/$block_name/theme{$suffix}.css（即区块的 theme 样式文件），从而实现"主题启用后自动切换为带倾向性样式"的行为。

块主题与 theme.json 建议：对于块主题（Block Theme）或提供theme.json的主题，不推荐使用wp-block-styles。为了确保全局样式规则与块样式之间不产生冲突，应把想要的块样式直接写进主题的theme.json文件中。

宽对齐（Wide Alignment）

图片等区块可以通过在包裹元素上添加alignwide或alignfull类名来实现"宽"或"通栏"对齐。主题启用该特性：

add_theme_support( 'align-wide' );

启用后编辑器才会向前端输出宽/通栏对齐的标记，主题再配合相应的 CSS 完成布局。关于add_theme_support()的通用细节可参考 WordPress 开发者文档。

宽对齐与浮动元素（Wide Alignments and Floats）

同时容纳宽图片、侧边栏、居中列和浮动元素且保持响应式是出了名的难题。区块编辑器会为浮动图片额外添加标记来简化样式处理。

带标题（caption）的图片标记：

<figure class="wp-block-image"> <img src="..." alt="" width="200px" /> <figcaption>Short image caption.</figcaption> </figure>

左浮动图片的标记：

<div class="wp-block-image"> <figure class="alignleft"> <img src="..." alt="" width="200px" /> <figcaption>Short image caption.</figcaption> </figure> </div>

注意两者的结构差异：浮动图片外层多了一个div.wp-block-image包裹，alignleft类名落在内部的figure上。这种包裹结构让主题可以同时控制外层（配合宽度）与内层（浮动 + 有界的标题宽度），是"侧边栏 + 宽图片 + 有界标题浮动元素"响应式布局得以实现的关键。

区块颜色调色板（Block Color Palettes）

不同区块都有定制颜色的能力。编辑器提供默认调色板，主题可以覆盖并提供自己的调色板：

add_theme_support( 'editor-color-palette', array( array( 'name' => esc_attr__( 'strong magenta', 'themeLangDomain' ), 'slug' => 'strong-magenta', 'color' => '#a156b4', ), array( 'name' => esc_attr__( 'light grayish magenta', 'themeLangDomain' ), 'slug' => 'light-grayish-magenta', 'color' => '#d0a5db', ), array( 'name' => esc_attr__( 'very light gray', 'themeLangDomain' ), 'slug' => 'very-light-gray', 'color' => '#eee', ), array( 'name' => esc_attr__( 'very dark gray', 'themeLangDomain' ), 'slug' => 'very-dark-gray', 'color' => '#444', ), ) );

三个字段的含义：

• name：人类可读的标签（如上所示），显示在 tooltip 中，向用户传达颜色的含义。对依赖屏幕阅读器或难以感知颜色的用户尤为重要。
• slug：颜色的唯一标识符，用于生成区块编辑器颜色调色板所使用的 CSS 类。
• color：指定颜色的十六进制色值。

颜色按声明顺序显示在调色板中，数量不限。像 Twenty Nineteen 主题中"Primary""Secondary"这类动态变化的颜色无法用程序描述，但即便如此，仍建议为默认值提供有意义的name。

主题负责创建在不同上下文中应用颜色的类。Core 区块使用 "color"、"background-color" 和 "border-color" 三种上下文。类名的构建规则是：追加has-前缀 + 使用 kebab case 的 slug + 上下文名。例如：

.has-strong-magenta-color { color: #a156b4; } .has-strong-magenta-background-color { background-color: #a156b4; } .has-strong-magenta-border-color { border-color: #a156b4; }

WordPress 5.9 起的重要变化：要覆盖 Core 定义的颜色值，没有theme.json的主题必须通过 CSS 自定义属性（Custom Properties）设置，而不是提供类。命名规则为--wp--preset--color--<slug>：

:root { --wp--preset--color--cyan-bluish-gray: <new_value>; --wp--preset--color--pale-pink: <new_value>; }

从源码看，当经典主题未提供theme.json时，一旦声明了自定义调色板，默认调色板默认会被关闭（除非显式声明default-color-palette支持）；该逻辑位于 lib/class-wp-theme-json-resolver-gutenberg.php：

$theme_support_data['settings']['color']['defaultPalette'] = ! isset( $theme_support_data['settings']['color']['palette'] ) || current_theme_supports( 'default-color-palette' );

同理还有default-gradient-presets、default-font-sizes、default-spacing-sizes等对应开关——它们都只在经典主题没有theme.json时生效。

区块渐变预设（Block Gradient Presets）

区块可以从预定义渐变列表中选择。编辑器提供默认渐变预设，主题可以覆盖并提供自己的：

add_theme_support( 'editor-gradient-presets', array( array( 'name' => esc_attr__( 'Vivid cyan blue to vivid purple', 'themeLangDomain' ), 'gradient' => 'linear-gradient(135deg,rgba(6,147,227,1) 0%,rgb(155,81,224) 100%)', 'slug' => 'vivid-cyan-blue-to-vivid-purple' ), array( 'name' => esc_attr__( 'Vivid green cyan to vivid cyan blue', 'themeLangDomain' ), 'gradient' => 'linear-gradient(135deg,rgba(0,208,132,1) 0%,rgba(6,147,227,1) 100%)', 'slug' => 'vivid-green-cyan-to-vivid-cyan-blue', ), array( 'name' => esc_attr__( 'Light green cyan to vivid green cyan', 'themeLangDomain' ), 'gradient' => 'linear-gradient(135deg,rgb(122,220,180) 0%,rgb(0,208,130) 100%)', 'slug' => 'light-green-cyan-to-vivid-green-cyan', ), array( 'name' => esc_attr__( 'Luminous vivid amber to luminous vivid orange', 'themeLangDomain' ), 'gradient' => 'linear-gradient(135deg,rgba(252,185,0,1) 0%,rgba(255,105,0,1) 100%)', 'slug' => 'luminous-vivid-amber-to-luminous-vivid-orange', ), array( 'name' => esc_attr__( 'Luminous vivid orange to vivid red', 'themeLangDomain' ), 'gradient' => 'linear-gradient(135deg,rgba(255,105,0,1) 0%,rgb(207,46,46) 100%)', 'slug' => 'luminous-vivid-orange-to-vivid-red', ), ) );

字段含义：

• name：人类可读标签，显示在 tooltip 中；对依赖辅助技术的用户尤为重要。
• gradient：应用于区块background-image的 CSS 渐变值，合法渐变类型的细节可参考 MDN 的 CSS 渐变文档。
• slug：渐变的唯一标识符，用于生成区块编辑器使用的 CSS 类。

主题负责创建应用渐变的类。例如应用 "Vivid cyan blue to vivid purple" 需要实现：

.has-vivid-cyan-blue-to-vivid-purple-gradient-background { background: linear-gradient( 135deg, rgba( 6, 147, 227, 1 ) 0%, rgb( 155, 81, 224 ) 100% ); }

WordPress 5.9 起，覆盖 Core 渐变值同样改用 CSS 自定义属性，命名规则为--wp--preset--gradient--<slug>：

:root { --wp--preset--gradient--vivid-cyan-blue-to-vivid-purple: <new_value>; --wp--preset--gradient--light-green-cyan-to-vivid-green-cyan: <new_value>; }

区块字号（Block Font Sizes）

段落等区块允许用户配置字号。区块提供默认字号集，主题可以覆盖并提供自己的：

add_theme_support( 'editor-font-sizes', array( array( 'name' => esc_attr__( 'Small', 'themeLangDomain' ), 'size' => 12, 'slug' => 'small' ), array( 'name' => esc_attr__( 'Regular', 'themeLangDomain' ), 'size' => 16, 'slug' => 'regular' ), array( 'name' => esc_attr__( 'Large', 'themeLangDomain' ), 'size' => 36, 'slug' => 'large' ), array( 'name' => esc_attr__( 'Huge', 'themeLangDomain' ), 'size' => 50, 'slug' => 'huge' ) ) );

字号按主题提供的顺序渲染在字号选择器中。主题负责创建应用正确字号的类，类名规则为：has-前缀 + kebab case 的 slug +-font-size后缀。例如 regular 字号：

.has-regular-font-size { font-size: 16px; }

注意：slugdefault和custom是保留字，主题不能使用。

WordPress 5.9 起，覆盖 Core 字号值改用 CSS 自定义属性，命名规则为--wp--preset--font-size--<slug>：

:root { --wp--preset--font-size--small: <new_value>; --wp--preset--font-size--large: <new_value>; }

关闭自定义能力：字号、颜色与渐变

关闭自定义字号

add_theme_support( 'disable-custom-font-sizes' );

设置后，用户将被限制在编辑器默认字号或editor-font-sizes提供的字号范围内。

关闭调色板中的自定义颜色

默认情况下，颜色调色板允许用户选择与编辑器/主题默认颜色不同的自定义颜色。主题可以关闭：

add_theme_support( 'disable-custom-colors' );

该标记确保用户只能从主题提供的editor-color-palette（或主题未提供时编辑器默认颜色）中选择颜色。

关闭自定义渐变

add_theme_support( 'disable-custom-gradients' );

设置后，用户将被限制在编辑器默认渐变或editor-gradient-presets提供的渐变范围内。

这些禁用开关与编辑器设置 API 一一对应：在 lib/experimental/class-wp-rest-block-editor-settings-controller.php 中可以找到disableCustomColors、disableCustomFontSizes、disableCustomGradients、disableLayoutStyles等布尔型 REST 设置项，它们最终通过 REST API 下发到编辑器前端，驱动选择器 UI 的可用性。

关闭基础布局样式（Disabling Base Layout Styles）

注意：自 WordPress 6.1 起可用。

主题可以选择退出为 Core 区块（包括 Group、Columns、Buttons、Social Icons）生成的默认结构布局样式：

add_theme_support( 'disable-layout-styles' );

使用该特性意味着主题承诺自行提供结构样式，否则 Core 区块会在编辑器与站点前端都显示异常。

源码中该开关在两个层面生效：

• 布局样式生成层面：lib/block-supports/layout.php 在输出布局样式前检查current_theme_supports( 'disable-layout-styles' )——只有未退出时才计算blockGap等布局 CSS；基于属性的布局类名（Attribute-based Layout classnames）则始终输出。
• 全局样式层面：lib/class-wp-theme-json-gutenberg.php 同样检查该主题支持。

需要定制blockGap样式或区块间距的主题，可参考 Global Settings & Styles 文档 中关于 blockGap 的章节。

自定义行高与自定义单位

自定义行高

段落、标题等区块支持自定义行高，主题通过以下代码启用：

add_theme_support( 'custom-line-height' );

对应 REST 设置项为enableCustomLineHeight（见 class-wp-rest-block-editor-settings-controller.php）。

自定义单位

除像素外，用户还可以使用其他单位定义尺寸、内边距等。可用单位包括：px、em、rem、vh、vw。主题可以关闭该特性：

add_theme_support( 'custom-units', array() );

也可以过滤允许的单位列表：

add_theme_support( 'custom-units', 'rem', 'em' );

关闭默认区块模式（Core Block Patterns）

WordPress 内置了一批区块模式（patterns）。主题可以退出内置模式并自带一组：

remove_theme_support( 'core-block-patterns' );

注意这里使用的是remove_theme_support()，与其它特性的add_theme_support()方向相反。

编辑器样式（Editor Styles）

区块编辑器支持主题的编辑器样式（editor styles），但工作方式与经典编辑器略有不同：

• 经典编辑器中，编辑器样式表被直接、原样加载进 WYSIWYG 编辑器的 iframe。
• 区块编辑器在 Site Editor 中使用 iframe，自 Gutenberg 23.6 起 Post Editor 也使用 iframe；WordPress Core 7.1 之前的版本在某些配置下仍可回退到非 iframe 的 Post Editor。
• 为了让编辑器样式在所有这些上下文中都限定作用于内容区域，WordPress 会有选择地重写或调整某些 CSS 选择器，这也能让区块变体预览（block variation previews）使用你的编辑器样式。

例如，如果你在编辑器样式中写了body { ... }，它会被重写为.editor-styles-wrapper { ... }。这也意味着你不应该直接针对任何编辑器类名编写样式。

由于工作方式不同，除了add_editor_style函数外，还需要额外添加：

add_theme_support( 'editor-styles' );

你通常不需要大幅修改编辑器样式；大多数主题加上面这段代码，就能在经典编辑器与区块编辑器中获得相近的效果。

入队编辑器样式

使用add_editor_style函数在编辑器屏幕中加载 CSS。经典编辑器只需这一个函数；区块编辑器需要先add_theme_support( 'editor-styles' )再入队：

add_editor_style( 'style-editor.css' );

在functions.php中加入这段代码，会把style-editor.css加入编辑器要加载的样式队列。

基础配色

可以像样式化普通网页一样样式化编辑器。例如把背景色与文字色改为蓝色系：

/* Add this to your `style-editor.css` file */ body { background-color: #d3ebf3; color: #00005d; }

改变编辑器宽度

在style-editor.css中加入以下 CSS 即可调整编辑器主列宽度：

/* Main column width */ .wp-block { max-width: 720px; } /* Width of "wide" blocks */ .wp-block[data-align='wide'] { max-width: 1080px; } /* Width of "full-wide" blocks */ .wp-block[data-align='full'] { max-width: none; }

可以用这些编辑器宽度与主题中的宽度匹配，支持%、px等任意 CSS 宽度单位。

延伸阅读：Applying Styles with Stylesheets。

响应式嵌入内容（Responsive Embeds）

嵌入类区块（embed blocks）会自动应用样式，以反映 iframe 中嵌入内容的比例（aspect ratio）。带有响应式比例的块结构类似：

<figure class="wp-embed-aspect-16-9 wp-has-aspect-ratio">...</figure>

要让内容随比例缩放，<body>元素需要wp-embed-responsive类。这个类默认不会添加，需要主题显式启用responsive-embeds：

add_theme_support( 'responsive-embeds' );

其实现位于 packages/block-library/src/embed/style.scss：.wp-embed-responsive .wp-has-aspect-ratio通过::before伪元素设置padding-top占位比例，并让iframe绝对定位铺满容器；同时为21-9、18-9、16-9、4-3、1-1等各比例分别计算padding-top百分比（如 16-9 为56.25%）。这就是"响应式嵌入必须 opt-in"的根本原因——主题启用后，body才会挂上触发这些规则的类。

间距控制（Spacing Control）

部分区块支持内边距（padding）控制。该功能默认关闭，需要主题声明支持：

add_theme_support( 'custom-spacing' );

对应 REST 设置项为enableCustomSpacing（见 class-wp-rest-block-editor-settings-controller.php）。

链接颜色控制（Link Color Control）

链接颜色支持自 WordPress 5.8 起稳定。默认关闭，主题可通过theme.json文件启用：

{ "settings": { "color": { "link": true } } }

附带说明：在 Gutenberg 插件激活时，旧的遗留写法add_theme_support( 'experimental-link-color' )也能生效，但当 Gutenberg 插件的最低 WordPress 版本要求升到 5.9 后该回退会被移除。事实上在 lib/class-wp-theme-json-resolver-gutenberg.php 中，experimental-link-color已触发_doing_it_wrong提示，并被引导改用link-color。

用户设置某个区块的链接颜色后，会新增如下样式：

.wp-elements-<uuid> a { color: <link-color> !important; }

其中：

• <uuid>是随机数；
• <link-color>要么是var(--wp--preset--color--slug)（用户选择了预设值），要么是原始颜色值（用户选择了自定义值）。

该区块会被附加.wp-elements-<uuid>类。这种"带随机 UUID 的作用域类"设计，确保了不同区块的链接颜色互不污染，是!important场景下仍能保持样式隔离的关键。

外观工具（Appearance Tools）

appearance-tools用于一次性启用下列 Global Styles 设置：

• background：backgroundImage、backgroundSize、gradient
• border：color、radius、style、width
• color：link、heading、button、caption
• spacing：blockGap、margin、padding
• typography：lineHeight、textColumns
• dimensions：aspectRatio、height、minHeight、minWidth、width
• position：sticky

add_theme_support( 'appearance-tools' );

源码层面，该开关被映射为settings.appearanceTools = true（见 lib/class-wp-theme-json-resolver-gutenberg.php），再由 Global Styles 引擎展开为上述各项设置。

边框（Border）

一次性启用全部边框设置：

add_theme_support( 'border' );

在 lib/class-wp-theme-json-resolver-gutenberg.php 中，border支持会把settings.border下的color、radius、style、width全部置为true。

链接颜色（Link Color）

通过 theme support 方式启用链接颜色设置（等价于上文 theme.json 中的"color": { "link": true }）：

add_theme_support( 'link-color' );

源码同样位于 lib/class-wp-theme-json-resolver-gutenberg.php：current_theme_supports( 'link-color' )为真时，settings.color.link被设为true。

基于块的模板部件（Block Based Template Parts）

基于块的模板部件允许管理员使用区块编辑站点的部分区域。默认关闭，需要主题声明支持：

add_theme_support( 'block-template-parts' );

该特性仅对非块主题（non block based themes）有意义——块主题本就通过站点编辑器原生支持基于块的模板部件。独立的模板部件编辑器不允许编辑者新建或删除模板部件，因为主题需要在 PHP 模板中手动引入该模板部件。更详细的内容可参考主题手册中块模板与模板部件的相关章节。

小结：主题支持特性的选择路径

汇总本文介绍的全部theme support特性，经典主题可按需组合：

一个关键取舍贯穿始终：经典主题（无theme.json）通过functions.php中的add_theme_support配置这些特性；块主题或提供theme.json的主题则应优先在theme.json中声明。前者的支持数据会被WP_Theme_JSON解析器转换为内部设置（并默认关闭对应的默认预设），后者的声明优先级更高、且不会与全局样式产生冲突。理解这套双轨机制，是配置任何 WordPress 主题与 Gutenberg 协同工作的基础。

【免费下载链接】gutenbergThe Block Editor project for WordPress and beyond. Plugin is available from the official repository.项目地址: https://gitcode.com/GitHub_Trending/gu/gutenberg