将 theme.json 扩展到自定义文章类型和插件输出：实用指南

摘要

许多 WordPress 开发者构建自定义文章类型或输出内容（例如推荐、作品集）的插件。然而，theme.json（全局样式的核心配置）通常会忽略这些自定义元素，导致设计不连贯。本文将指导您注册自定义文章类型以继承 theme.json 样式，覆盖特定块的设置，并将插件输出与核心设计标记连接起来。您将获得分步说明、如样式化“团队成员”CPT 的真实示例，以及关于性能和第三方冲突的注意事项。最后，您将确保任何自定义内容与您编辑器定义的设计系统匹配。

您是否曾构建过自定义文章类型或集成过第三方插件，却发现其输出完全忽略了您在 theme.json 中精心配置的优美设计系统？您并不孤单。默认情况下，theme.json 仅适用于核心 WordPress 块和已注册的块样式，使自定义文章类型和插件生成的内容自行其是。这通常会导致内联 CSS、重复的字体系列或破坏用户体验的不匹配调色板。但有一种更好的方法：您可以扩展 theme.json 以覆盖这些自定义元素，确保在您的整个站点上实现一致、可维护的设计系统。在本指南中，我们将介绍实现这一目标的四个实用步骤，并附有代码示例和真实世界的注意事项。

理解 theme.json 范围

在深入之前，关键是要理解 theme.json 是一个块主题概念。它定义了全局样式、设置（如调色板和字体大小）以及块特定样式，适用于块编辑器和前端。然而，它的范围有限：它仅控制那些通过 register_block_type 或较旧的 add_theme_support 明确声明支持 theme.json 属性的块。通过 register_post_type 创建的自定义文章类型不会自动继承这些样式，除非它们是用块构建的或显式设置了样式。

步骤 1：注册支持块编辑器的自定义文章类型

第一步是确保您的自定义文章类型使用块编辑器。在调用 register_post_type 时，设置 'show_in_rest' => true 并在 supports 数组中包含 'editor'。这为该文章类型启用了块编辑器，使作者能够使用 theme.json 中的块级样式。例如，这是一个“团队成员”CPT：

function create_team_member_cpt() {
    $args = array(
        'public' => true,
        'show_in_rest' => true,
        'supports' => array( 'title', 'editor', 'thumbnail', 'custom-fields' ),
        'show_in_menu' => true,
        'labels' => array(
            'name' => '团队成员',
            'singular_name' => '团队成员',
        ),
        'rewrite' => array( 'slug' => 'team' ),
    );
    register_post_type( 'team_member', $args );
}
add_action( 'init', 'create_team_member_cpt' );

现在，当您编辑团队成员文章时，您将看到块编辑器，并应用了您主题的全局样式到核心块，如段落、标题和图像。这本身通常就能解决大多数样式问题。如果您需要更精细的控制，请继续下一步。有关使用 theme.json 构建块主题的深入讨论，请参阅如何使用 theme.json 构建自定义 WordPress 块主题。

步骤 2：通过 theme.json 添加自定义块样式

有时，您希望将特定样式应用于自定义文章类型内容的所有实例——例如，为整个文章添加背景颜色或特殊内边距。您可以定位 core/post-content 或将您的内容包裹在自定义组块中，并通过 theme.json 设置其样式。将以下内容添加到您的 theme.json 文件的 styles 对象中：

{
  "styles": {
    "blocks": {
      "core/post-content": {
        "css": "background-color: var(--wp--preset--color--light); padding: 2rem;"
      }
    }
  }
}

这会将浅色背景和内边距应用于所有文章的内容区域，包括您的团队成员 CPT。您还可以在 settings.blocks 内定义块特定的变体，以在编辑器中提供样式选项。

步骤 3：为插件输出使用 theme.json 自定义属性

插件通常通过短代码、小工具或自定义块输出内容。要一致地设置这些内容的样式，请利用 theme.json 生成的 CSS 自定义属性。例如，如果您的主题将主色定义为 --wp--preset--color--primary，您可以在插件的 CSS 中使用它：

.my-plugin-button {
    background-color: var(--wp--preset--color--primary);
    font-size: var(--wp--preset--font-size--medium);
}

这确保当站点管理员更改 theme.json 中的调色板时，您的插件按钮会自动更新。为了使这更稳健，请始终使用预设的 CSS 变量，而不是硬编码值。此外，如果您的插件注册了自己的块，您可以通过在 JavaScript 中使用 useSetting 或在 PHP 渲染中传递 $attributes 来继承 theme.json 设置，如掌握 WordPress 动态块中所述。

步骤 4：处理动态块

对于输出动态内容（例如推荐滑块）的自定义块，您需要使用块编辑器支持注册该块，并明确将其与 theme.json 关联。在 PHP 中，使用带有包含 'render_callback' 的 $args 的 register_block_type，并确保您的块的 block.json 文件设置 'supports' => array( 'color' => true, 'typography' => true )。然后，在您的渲染回调中，您可以通过 wp_get_global_styles() 访问全局样式并应用它们。例如：

function render_testimonial_block( $attributes, $content ) {
    $styles = wp_get_global_styles();
    $color = $styles['elements']['link']['color']['text'] ?? '#000';
    return '<div style="color: ' . esc_attr( $color ) . ';">' . $content . '</div>';
}

这种方法确保您的自定义块尊重主题的设计标记。有关块注册的更多信息，请参阅构建健壮的 WordPress 插件。

注意事项

虽然扩展 theme.json 很强大，但要警惕以下陷阱：

1. 性能：在 theme.json 中添加太多自定义样式会使文件臃肿并增加 CSS 解析时间。坚持使用全局设置，并谨慎使用块特定样式。
2. 插件冲突：某些插件会重置或覆盖 theme.json 设置。始终使用最少的插件集进行测试，并考虑挂钩到 after_setup_theme 以重新应用您的自定义设置。
3. 经典主题：如果您的主题不使用块编辑器（即经典主题），theme.json 的效果有限。考虑迁移到块主题或使用 wp_enqueue_global_styles 函数加载样式。
4. 浏览器缓存：由于缓存，theme.json 的更改可能不会立即显示。清除浏览器缓存，并为您的样式表使用版本控制。

结论

现在，您已拥有清晰的路线图，使自定义文章类型和插件输出与您的 theme.json 设计系统良好协作。关键在于使用块编辑器支持注册您的 CPT，定义文章内容块的特定样式，在插件输出中使用 CSS 自定义属性，以及使用适当的 theme.json 集成注册您的自定义块。这种方法消除了不一致性，减少了维护工作，并赋予站点管理员从单一真实来源控制外观和感觉的能力。立即开始实施这些步骤，为您的 WordPress 项目带来一致性。