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 classwp-block-image img src... alt width200px / figcaptionShort image caption./figcaption /figure左浮动图片的标记div classwp-block-image figure classalignleft img src... alt width200px / figcaptionShort 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 主题中PrimarySecondary这类动态变化的颜色无法用程序描述但即便如此仍建议为默认值提供有意义的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 PatternsWordPress 内置了一批区块模式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 也使用 iframeWordPress 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-alignwide] { max-width: 1080px; } /* Width of full-wide blocks */ .wp-block[data-alignfull] { max-width: none; }可以用这些编辑器宽度与主题中的宽度匹配支持%、px等任意 CSS 宽度单位。延伸阅读Applying Styles with Stylesheets。响应式嵌入内容Responsive Embeds嵌入类区块embed blocks会自动应用样式以反映 iframe 中嵌入内容的比例aspect ratio。带有响应式比例的块结构类似figure classwp-embed-aspect-16-9 wp-has-aspect-ratio.../figure要让内容随比例缩放body元素需要wp-embed-responsive类。这个类默认不会添加需要主题显式启用responsive-embedsadd_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 Toolsappearance-tools用于一次性启用下列 Global Styles 设置backgroundbackgroundImage、backgroundSize、gradientbordercolor、radius、style、widthcolorlink、heading、button、captionspacingblockGap、margin、paddingtypographylineHeight、textColumnsdimensionsaspectRatio、height、minHeight、minWidth、widthpositionstickyadd_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.phpcurrent_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特性经典主题可按需组合特性调用作用带倾向性块样式add_theme_support( wp-block-styles )启用 blockquote 色条等意见化样式宽/通栏对齐add_theme_support( align-wide )启用alignwide/alignfull自定义调色板add_theme_support( editor-color-palette, [...] )覆盖默认颜色自定义渐变预设add_theme_support( editor-gradient-presets, [...] )覆盖默认渐变自定义字号add_theme_support( editor-font-sizes, [...] )覆盖默认字号关闭自定义字号/颜色/渐变add_theme_support( disable-custom-* )锁定预设选择关闭布局样式add_theme_support( disable-layout-styles )自行提供结构样式WP 6.1自定义行高/间距/单位add_theme_support( custom-line-height / custom-spacing / custom-units, [...] )开启高级尺寸工具退出默认区块模式remove_theme_support( core-block-patterns )自带模式集编辑器样式add_theme_support( editor-styles )add_editor_style()作用域化编辑器样式响应式嵌入add_theme_support( responsive-embeds )按比例缩放 iframe 嵌入链接颜色/外观工具/边框add_theme_support( link-color / appearance-tools / border )启用对应 Global Styles 设置基于块的模板部件add_theme_support( block-template-parts )非块主题启用模板部件编辑一个关键取舍贯穿始终经典主题无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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考