Gutenberg Global Styles Filters 深入指南通过 wp_theme_json_data_* 过滤器定制 theme.json 数据【免费下载链接】gutenbergThe Block Editor project for WordPress and beyond. Plugin is available from the official repository.项目地址: https://gitcode.com/GitHub_Trending/gu/gutenbergGlobal Styles Filters 是 WordPress 6.1 起为 Gutenberg 引入的一组服务端过滤器它们分别挂在theme.json数据的四个数据层default、blocks、theme、user上让插件与主题作者可以在数据合并之前对每一层的配置进行精准的读取与改写。本文将围绕 global-styles-filters.md 所定义的核心 API结合 Gutenberg 仓库中WP_Theme_JSON_Data与WP_Theme_JSON_Resolver的真实实现讲解四个过滤器的定位、update_with()的工作原理、完整可运行的示例代码以及数据合并优先级等关键细节。读完本文你将能够独立写出向任意数据层注入自定义设置、覆盖调色板、禁用样式控件等功能的过滤器并理解这些改动在 Global Styles 数据流水线中的确切生效位置。一、Global Styles 的四层数据模型在深入过滤器之前先要理解theme.json数据在整个系统中的分层结构。Gutenberg 将站点的全局样式与设置数据划分为四个来源origin并按优先级从低到高依次合并defaultWordPress 核心提供的默认数据blocks各个已注册块自身声明的数据主要来自块注册时的supports[__experimentalStyle]theme当前激活主题的theme.jsonuser用户在站点编辑器里保存的自定义全局样式。这一优先级顺序在 class-wp-theme-json-resolver-gutenberg.php 的get_merged_data()方法中有明确体现方法依次把get_core_data()、get_block_data()、get_theme_data()、get_user_data()合并进同一个WP_Theme_JSON实例后一层会覆盖前一层。注释原文也直接说明The customs has higher priority than the themes, the themes higher than blocks, and blocks higher than defaults.四个wp_theme_json_data_*过滤器正是分别挂在这四个取数方法上它们在各层数据被合并进最终结果之前执行过滤器数据层源码触发位置wp_theme_json_data_defaultdefaultWordPress 核心默认值get_core_data()wp_theme_json_data_blocksblocks各块注册的样式数据get_block_data()wp_theme_json_data_themetheme当前主题的 theme.jsonget_theme_data()wp_theme_json_data_useruser用户保存的全局样式get_user_data()每个过滤器都接收一个WP_Theme_JSON_Data实例作为唯一参数回调需要返回该实例通常是调用update_with()之后的同一个实例过滤后的数据随后被用于后续合并。二、WP_Theme_JSON_Data 与 update_with() 的工作原理过滤器回调拿到的对象是WP_Theme_JSON_Data在 Gutenberg 仓库中对应 class-wp-theme-json-data-gutenberg.php 的WP_Theme_JSON_Data_Gutenberg类。这个类是一个轻量封装构造函数接收原始数据数组与 origin 标识内部将其包装成一个WP_Theme_JSON实例update_with( $new_data )把传入的theme.json结构的数据与当前数据合并。从源码可以看到其实现是把新数据构造成另一个WP_Theme_JSON实例再调用merge()方法public function update_with( $new_data ) { $this-theme_json-merge( new WP_Theme_JSON_Gutenberg( $new_data, $this-origin ) ); return $this; }注意它返回的是$this也就是原实例本身因此可以放心地在过滤器回调里return $theme_json-update_with( $new_data );。get_data()/get_theme_json()分别返回合并后的原始数组与WP_Theme_JSON对象供上层取用。底层merge()方法位于 class-wp-theme-json-gutenberg.php核心是array_replace_recursive()——这意味着新数据会与既有数据在叶子节点层面逐级合并而不是整体替换只声明color时settings下的typography等其他设置依然保留。关于 version 字段文档特别强调update_with()传入的新数据必须声明所使用的theme.json的version这样即使新数据版本与当前运行时版本不同也能被正确迁移。在 Gutenberg 仓库中最新 schema 常量定义为LATEST_SCHEMA 3见 class-wp-theme-json-gutenberg.php而文档示例使用的是version 2——这恰恰展示了该机制的用途旧版本数据会被自动迁移到当前运行时版本。三、完整示例注入调色板并禁用文字颜色 UI原文档给出的示例是在 theme 层注入一套全新的调色板同时关闭文字颜色控件。下面是完整的、可直接放进主题functions.php或插件中的代码function wpdocs_filter_theme_json_theme( $theme_json ){ $new_data array( version 2, settings array( color array( text false, // 关闭文字颜色设置 UI palette array( /* New palette */ array( slug foreground, color black, name __( Foreground, theme-domain ), ), array( slug background, color white, name __( Background, theme-domain ), ), ), ), ), ); return $theme_json-update_with( $new_data ); } add_filter( wp_theme_json_data_theme, wpdocs_filter_theme_json_theme );关键点拆解text false是settings.color下的布尔开关用于在编辑器界面隐藏文字颜色控件与theme.json中settings.color.text的语义一致palette数组中的每个色板项包含slug唯一标识用于生成 CSS 变量名、color色值和name展示名称建议用__()包裹以便国际化挂钩wp_theme_json_data_theme因为挂在这一层这些设置会覆盖块层与默认层中同名数据但会被用户层用户在站点编辑器中手动修改的样式覆盖。这种在主题层补充数据的模式特别适合插件为所有使用该插件的站点统一注入预设而不必修改主题文件。四、其他数据层的实战用法4.1 default 层调整 WordPress 核心默认值function wpdocs_filter_theme_json_default( $theme_json ){ $new_data array( version 3, settings array( layout array( contentSize 720px, wideSize 1200px, ), ), ); return $theme_json-update_with( $new_data ); } add_filter( wp_theme_json_data_default, wpdocs_filter_theme_json_default );default 层的数据源头是 WordPress 核心的默认配置。在 Gutenberg 仓库中核心默认数据来自 lib/theme.json读取后即触发wp_theme_json_data_default过滤器见 get_core_data()。由于该层优先级最低这里注入的值只作为兜底可被主题、用户层覆盖。4.2 blocks 层按块类型注入样式数据blocks 层的数据由各块注册时声明的supports[__experimentalStyle]汇总而成见 get_block_data()。在这一层挂钩可以按块名称补充或修正样式function wpdocs_filter_theme_json_blocks( $theme_json ){ $new_data array( version 3, styles array( blocks array( core/paragraph array( typography array( fontSize 18px, ), ), ), ), ); return $theme_json-update_with( $new_data ); } add_filter( wp_theme_json_data_blocks, wpdocs_filter_theme_json_blocks );4.3 user 层覆盖用户已保存的全局样式user 层的数据来自wp_global_styles自定义文章类型中保存的内容。仓库源码在解析该数据时做了两项重要检查见 get_user_data()先json_decode文章内容若解码失败会触发错误并仍执行过滤器但传入空数据校验数据中isGlobalStylesUserThemeJSON标志必须为true这是防止未转义、不安全内容进入全局样式的安全机制。挂钩示例例如强制所有文章标题使用统一的颜色function wpdocs_filter_theme_json_user( $theme_json ){ $new_data array( version 3, styles array( elements array( h2 array( color array( text #1e1e1e, ), ), ), ), ); return $theme_json-update_with( $new_data ); } add_filter( wp_theme_json_data_user, wpdocs_filter_theme_json_user );注意user 层优先级最高在这一层做的修改不会被主题覆盖因此通常只用于必须强制生效的场景需要谨慎使用。五、进阶模式与注意事项5.1 基于条件的动态注入过滤器回调并不局限于静态数组。你可以结合当前上下文如当前站点、当前用户、激活的插件等动态生成数据function wpdocs_filter_theme_json_theme( $theme_json ){ $new_data array( version 3 ); if ( function_exists( is_woocommerce ) ) { $new_data[settings][color][palette][] array( slug brand, color #96588a, name __( Brand, theme-domain ), ); } return $theme_json-update_with( $new_data ); } add_filter( wp_theme_json_data_theme, wpdocs_filter_theme_json_theme );5.2 版本迁移与缓存版本迁移无论你写version 2还是version 3数据最终都会迁移到当前运行时版本。建议直接使用当前 Gutenberg 仓库的LATEST_SCHEMA3以减少不必要的迁移开销同时保留兼容旧版本的写法也完全合法结果缓存每一层的数据解析结果都会被静态缓存static::$core、static::$theme、static::$blocks、static::$user。若在请求中途动态注册了块或修改了主题可调用 clean_cached_data() 清空缓存以重新计算正常情况下无需手动干预。5.3 仓库中的测试佐证Gutenberg 仓库的 PHPUnit 测试直接使用了这些过滤器与update_with()block-style-variations-test.php在测试中通过wp_theme_json_data_theme过滤器调用update_with()注入数据随后验证块样式变体的解析结果block-visibility-test.php用同样的模式注入设置后断言块可见性相关逻辑class-wp-theme-json-resolver-test.php明确断言wp_theme_json_data_theme过滤器确实被调用过。这些测试既是过滤器用法的第二份官方示例也验证了在 theme 层通过update_with()注入数据这一模式在真实数据流水线中的行为。六、总结wp_theme_json_data_default、wp_theme_json_data_blocks、wp_theme_json_data_theme、wp_theme_json_data_user四个过滤器构成了 Gutenberg 服务端定制 Global Styles 数据的完整入口。它们的核心使用范式高度统一接收WP_Theme_JSON_Data实例 → 构造带version声明的theme.json结构数组 → 调用update_with()合并 → 返回实例。在此基础上理解四层数据的来源与合并优先级default → blocks → theme → user后者覆盖前者就能准确判断你的修改会在哪个环节生效、会被谁覆盖从而写出行为可预期、边界清晰的全局样式扩展代码。【免费下载链接】gutenbergThe Block Editor project for WordPress and beyond. Plugin is available from the official repository.项目地址: https://gitcode.com/GitHub_Trending/gu/gutenberg创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考