云策 WordPress 开发者社区

钩子文档

wp_theme_json_data_theme

查看官方原文 ↗
💡 云策文档标注

概述

wp_theme_json_data_theme 是一个 WordPress 过滤器，用于修改主题提供的全局样式和设置数据。它允许开发者通过 WP_Theme_JSON_Data 类访问和更新 theme.json 文件中的配置。

关键要点

  • 过滤器名称：wp_theme_json_data_theme，用于过滤主题的全局样式和设置数据。
  • 参数：$theme_json，一个 WP_Theme_JSON_Data 类实例，用于操作底层数据。
  • 用途：常用于在 WP_Theme_JSON_Resolver::get_theme_data() 中返回主题数据前进行自定义修改。
  • 版本：自 WordPress 6.1.0 引入。

代码示例

// 替换主题颜色调色板
function wpdocs_add_replace_configuration( $theme_json ) {
    $new_data = array(
        'version'  => 3, // 必需，否则无效
        'settings' => array(
            'color' => array(
                'palette' => array(
                    array(
                        'slug'  => 'base',
                        'color' => 'white',
                        'name'  => __( 'Base', 'theme-domain' ),
                    ),
                    array(
                        'slug'  => 'contrast',
                        'color' => 'black',
                        'name'  => __( 'Contrast', 'theme-domain' ),
                    ),
                ),
            ),
        ),
    );
    return $theme_json->update_with( $new_data );
}
add_filter( 'wp_theme_json_data_theme', 'wpdocs_add_replace_configuration' );

注意事项

  • 在更新数据时，必须包含 'version' => 3，否则配置可能无效。
  • 可以使用 $theme_json->get_data() 获取当前数据，再通过 array_merge 合并新配置。
  • 支持将 theme.json 拆分为多个文件，通过过滤器动态组合数据。
📄 原文内容

Filters the data provided by the theme for global styles and settings.

Parameters

$theme_jsonWP_Theme_JSON_Data
Class to access and update the underlying data.

Source

$theme_json = apply_filters( 'wp_theme_json_data_theme', new WP_Theme_JSON_Data( $theme_json_data, 'theme' ) );

View all references View on Trac View on GitHub

Used by Description
WP_Theme_JSON_Resolver::get_theme_data()wp-includes/class-wp-theme-json-resolver.php

Returns the theme’s data.

Changelog

Version Description
6.1.0 Introduced.

User Contributed Notes

  1. Skip to note 4 content


    maximebj


    You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note

    Replace the color palette from the theme.json file:

    function wpdocs_add_replace_configuration( $theme_json )
{
    $new_data = array(
        'version'  => 3, // Mandatory, or it won’t work
        'settings' => array(
            'color' => array(
                'palette' => array(
                    array(
                        'slug'  => 'base',
                        'color' => 'white',
                        'name'  => __( 'Base', 'theme-domain' ),
                    ),
                    array(
                        'slug'  => 'contrast',
                        'color' => 'black',
                        'name'  => __( 'Contrast', 'theme-domain' ),
                    ),
                ),
            ),
        ),
    );

    return $theme_json->update_with( $new_data );
}
add_filter( 'wp_theme_json_data_theme', 'wpdocs_add_replace_configuration' );

  2. Skip to note 5 content


    maximebj


    You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note

    Add new colors to an existing palette and merge configuration:

    function wpdocs_merge_custom_configuration( $theme_json ) {
    $current_data = $theme_json->get_data();

    $new_data = array(
        'version'  => 3, // Mandatory, or it won’t work
        'settings' => array(
            'color' => array(
                'palette' => array_merge($current_data[‘settings’][‘color’][‘palette’][‘theme’], array(
                    array(
                        'slug'  => 'base',
                        'color' => 'white',
                        'name'  => __( 'Base', 'textdomain' ),
                    ),
                    array(
                        'slug'  => 'contrast',
                        'color' => 'black',
                        'name'  => __( 'Contrast', 'textdomain' ),
                    ),
                )),
            ),
        ),
    );

    return $theme_json->update_with( $new_data );
}
add_filter( 'wp_theme_json_data_theme', 'wpdocs_merge_custom_configuration' );

  3. Skip to note 6 content


    maximebj


    You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note

    Split theme.json in multiple files:

    function wpdocs_compose_theme_json( $theme_json )
{
    // Load sub files
    $theme_styles_raw   = file_get_contents( get_template_directory() . '/theme-styles.json' );
    $theme_settings_raw = file_get_contents( get_template_directory() . '/theme-settings.json' );

    // Convert JSON to array
    $theme_styles   = json_decode( $theme_styles_raw, true );
    $theme_settings = json_decode( $theme_settings_raw, true );

    // Inject data
    $new_data = [
        'version'  => 3, // Mandatory, or it won’t work
        'settings' => $theme_settings['settings'],
        'styles'   => $theme_styles['styles'],
    ];

    // Update WordPress' theme.json
    return $theme_json->update_with( $new_data );
}
add_filter( 'wp_theme_json_data_theme', 'wpdocs_compose_theme_json' );

    In theme-settings.json:

    {
    "$schema": "https://schemas.wp.org/trunk/theme.json",
    "settings": {
		    "color": {}
	  }
}