块编辑器开发文档

全局样式过滤器

💡 云策文档标注

概述

WordPress 6.1 引入了服务器端过滤器,用于挂钩到不同数据层提供的 theme.json 数据,包括默认、区块、主题和用户数据层。

关键要点

  • 提供了四个过滤器:wp_theme_json_data_default、wp_theme_json_data_blocks、wp_theme_json_data_theme 和 wp_theme_json_data_user,分别对应不同数据源。
  • 每个过滤器接收一个 WP_Theme_JSON_Data 类实例,回调函数需使用 update_with( $new_data ) 方法更新数据。
  • 新数据必须是有效的 theme.json 结构,并声明版本号以确保正确迁移到运行时版本。

代码示例

function wpdocs_filter_theme_json_theme( $theme_json ){
    $new_data = array(
        'version'  => 2,
        'settings' => array(
            'color' => array(
                'text'       => false,
                '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' );

📄 原文内容

WordPress 6.1 has introduced some server-side filters to hook into the theme.json data provided at the different data layers:

  • wp_theme_json_data_default: hooks into the default data provided by WordPress
  • wp_theme_json_data_blocks: hooks into the data provided by the blocks
  • wp_theme_json_data_theme: hooks into the data provided by the theme
  • wp_theme_json_data_user: hooks into the data provided by the user

Each filter receives an instance of the WP_Theme_JSON_Data class with the data for the respective layer. To provide new data, the filter callback needs to use the update_with( $new_data ) method, where $new_data is a valid theme.json-like structure. As with any theme.json, the new data needs to declare which version of the theme.json is using, so it can correctly be migrated to the runtime one, should it be different.

Example:

This is how to pass a new color palette for the theme and disable the text color UI:

function wpdocs_filter_theme_json_theme( $theme_json ){
    $new_data = array(
        'version'  => 2,
        'settings' => array(
            'color' => array(
                'text'       => false,
                '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' );