WordPress 主题颜色配置完全指南

发布于 作者:

在 WordPress 主题开发中，颜色配置不仅仅是调色板的选择，更涉及到用户权限控制、预设管理以及编辑器体验的定制。theme.json 文件中的 settings.color 属性是控制这一切的核心枢纽——它能让你决定用户能否自由取色、是否显示默认色板、以及如何注册专属于你主题的配色方案。

对于初学者来说，理解这些配置项之间的关系至关重要。比如，”关闭自定义颜色”和”关闭默认调色板”会产生完全不同的编辑体验；注册调色板时使用的 slug 字段会直接生成对应的 CSS 类名。本文将从实际开发角度出发，逐层拆解每个配置项的作用和典型使用场景，帮助你快速掌握 WordPress 主题颜色配置的核心知识。

一、颜色配置概览

theme.json 中的颜色配置位于 settings.color 路径下。一个典型的配置结构如下：

json

{
  "version": 2,
  "settings": {
    "color": {
      "background": true,
      "text": true,
      "link": true,
      "custom": true,
      "customGradient": true,
      "customDuotone": true,
      "defaultPalette": true,
      "defaultGradients": true,
      "defaultDuotone": true,
      "palette": [],
      "gradients": [],
      "duotone": []
    }
  }
}

字段说明：

字段类型作用
background / text / link布尔值是否在编辑器中显示对应的颜色控制选项
custom / customGradient / customDuotone布尔值是否允许用户创建自定义颜色/渐变/双色调
defaultPalette / defaultGradients / defaultDuotone布尔值是否显示 WordPress 自带的预设
palette / gradients / duotone数组注册主题自有的预设

下面逐一展开说明。

二、控制编辑器的颜色选项

在区块编辑器的右侧面板中，支持颜色的区块通常会显示”文本”、”背景”和”链接”三个颜色选择器。你可以通过以下配置决定哪些显示：

json

{
  "version": 2,
  "settings": {
    "color": {
      "background": true,   // 显示背景色选择器
      "text": true,         // 显示文本色选择器
      "link": true          // 显示链接色选择器
    }
  }
}

三个选项默认都是开启的。如果想让用户只能改文字颜色而不能改背景，可以这样设置：

json

{
  "version": 2,
  "settings": {
    "color": {
      "background": false,
      "text": true,
      "link": true
    }
  }
}

注意： 部分三方区块可能提供额外的颜色控制项，这些不在 theme.json 的管理范围内。

三、用户自定义权限控制

你可以决定用户是否能自由创造颜色、渐变或双色调滤镜。以下三项默认全部开启：

json

{
  "version": 2,
  "settings": {
    "color": {
      "custom": true,           // 允许自定义颜色
      "customGradient": true,   // 允许自定义渐变
      "customDuotone": true     // 允许自定义双色调
    }
  }
}

关闭自定义颜色（用户只能从预设色板中选择）：

json

{
  "version": 2,
  "settings": {
    "color": {
      "custom": false
    }
  }
}

关闭自定义渐变：

json

{
  "version": 2,
  "settings": {
    "color": {
      "customGradient": false
    }
  }
}

关闭自定义双色调：

json

{
  "version": 2,
  "settings": {
    "color": {
      "customDuotone": false
    }
  }
}

四、WordPress 默认预设

WordPress 内置了三类预设：调色板、渐变和双色调滤镜。默认都是启用的，但如果你希望主题的视觉风格更加统一，通常建议关闭它们。

json

{
  "version": 2,
  "settings": {
    "color": {
      "defaultPalette": true,    // 显示 WP 默认色板
      "defaultGradients": true,  // 显示 WP 默认渐变
      "defaultDuotone": true     // 显示 WP 默认双色调
    }
  }
}

关闭默认调色板：

json

{
  "version": 2,
  "settings": {
    "color": {
      "defaultPalette": false
    }
  }
}

注意： 即使关闭了这些预设，WordPress 仍然会在前端生成对应的 CSS 变量。这是为了保证兼容性——当用户切换到其他主题时，之前选中的颜色不会丢失。

五、注册主题自有预设

这是主题开发中常用的功能。通过注册自己的预设，你可以控制用户在编辑器中能看到哪些颜色选项。

5.1 自定义调色板

json

{
  "version": 2,
  "settings": {
    "color": {
      "palette": [
        {
          "color": "#f8f9fa",
          "name": "基底",
          "slug": "base"
        },
        {
          "color": "#212529",
          "name": "对比色",
          "slug": "contrast"
        },
        {
          "color": "#0d6efd",
          "name": "主色",
          "slug": "primary"
        },
        {
          "color": "#6c757d",
          "name": "辅助色",
          "slug": "secondary"
        }
      ]
    }
  }
}

每个颜色对象包含三个属性：

  • color：合法的 CSS 颜色值（十六进制、rgb、hsl 等）
  • name：显示给用户看的标签，支持多语言翻译
  • slug：机器识别的标识符，用于生成 CSS 变量和类名

自动生成的 CSS 变量：

text

--wp--preset--color--base
--wp--preset--color--contrast
--wp--preset--color--primary
--wp--preset--color--secondary

自动生成的 CSS 类：

  • 文字颜色：.has-base-color、.has-primary-color
  • 背景颜色：.has-base-background-color、.has-primary-background-color

注意： base 和 contrast 这两个 slug 是社区事实标准（由 Twenty Twenty-Three 主题确立），推荐用于背景色和文字色，以便与其他主题和插件保持兼容。

5.2 自定义渐变

json

{
  "version": 2,
  "settings": {
    "color": {
      "gradients": [
        {
          "gradient": "linear-gradient(135deg, #667eea 0%, #764ba2 100%)",
          "name": "星空紫",
          "slug": "star-purple"
        },
        {
          "gradient": "linear-gradient(135deg, #f093fb 0%, #f5576c 100%)",
          "name": "玫瑰粉",
          "slug": "rose-pink"
        },
        {
          "gradient": "radial-gradient(circle at 10% 20%, #90f7ec 0%, #32ccbc 90%)",
          "name": "海洋绿",
          "slug": "ocean-green"
        }
      ]
    }
  }
}

自动生成的 CSS 变量：

text

--wp--preset--gradient--star-purple
--wp--preset--gradient--rose-pink
--wp--preset--gradient--ocean-green

5.3 自定义双色调滤镜

双色调滤镜通常用于图片区块，通过两种颜色对图片进行着色处理。

json

{
  "version": 2,
  "settings": {
    "color": {
      "duotone": [
        {
          "colors": ["#2b0b3d", "#f7c948"],
          "name": "暗夜金",
          "slug": "night-gold"
        },
        {
          "colors": ["#0a1628", "#4facfe"],
          "name": "深海蓝",
          "slug": "deep-blue"
        },
        {
          "colors": ["#5c2a2a", "#f5a3a3"],
          "name": "复古红",
          "slug": "vintage-red"
        }
      ]
    }
  }
}

注意： 双色调目前不支持 CSS 变量引用，只能使用具体的颜色值（十六进制、rgb 等）。WordPress 核心团队已有计划在未来解决这个问题。

六、综合配置示例

以下是一个完整的颜色配置示例，关闭了 WordPress 默认预设，开启了用户自定义，并注册了主题自己的颜色方案：

json

{
  "version": 2,
  "settings": {
    "color": {
      "background": true,
      "text": true,
      "link": true,
      "custom": true,
      "customGradient": true,
      "customDuotone": false,
      "defaultPalette": false,
      "defaultGradients": false,
      "defaultDuotone": false,
      "palette": [
        {
          "color": "#fcfcfc",
          "name": "基底",
          "slug": "base"
        },
        {
          "color": "#1a1a2e",
          "name": "对比色",
          "slug": "contrast"
        },
        {
          "color": "#e94560",
          "name": "强调色",
          "slug": "accent"
        }
      ],
      "gradients": [
        {
          "gradient": "linear-gradient(135deg, #1a1a2e 0%, #16213e 100%)",
          "name": "深空",
          "slug": "dark-sky"
        }
      ],
      "duotone": []
    }
  }
}

七、总结

配置类别关键字段常用场景
编辑器控制background、text、link限制用户可调整的颜色类型
自定义权限custom、customGradient、customDuotone强制用户使用预设，保持设计一致性
默认预设defaultPalette、defaultGradients、defaultDuotone移除 WordPress 自带颜色，突出主题特色
主题预设palette、gradients、duotone注册主题专属配色方案

掌握 theme.json 中的颜色配置，是 WordPress 主题开发从入门到进阶的关键一步。建议你在实际主题中反复尝试不同组合，观察编辑器界面的变化，从而加深理解。