主题优化：如何利用WordPress的`Theme.json`文件实现全局样式和排版控制，并集成CSS自定义属性？ - 智猿学院-前后端，数据库，人工智能，云计算等领域前沿技术讲座

利用 WordPress `theme.json` 实现全局样式和排版控制，集成 CSS 自定义属性

大家好！今天我们来深入探讨 WordPress 的 theme.json 文件，学习如何利用它实现全局样式和排版控制，并集成 CSS 自定义属性，从而构建高度可定制且易于维护的 WordPress 主题。

theme.json 是 WordPress 5.8 版本引入的一个强大的工具，它允许开发者以声明式的方式定义主题的样式和行为，而无需编写大量的 CSS 代码。通过 theme.json，我们可以控制站点的颜色、排版、布局等各个方面，并为用户提供友好的自定义选项。

`theme.json` 的基本结构

theme.json 文件位于主题的根目录下，是一个 JSON 格式的文件。其基本结构如下：

{
  "version": 2,
  "settings": {
    // 全局设置
  },
  "styles": {
    // 全局样式
  },
  "templateParts": [
      // 模板部件
  ]
}

version: 指定 theme.json 文件的版本。当前推荐使用 2。
settings: 定义主题的全局设置，例如颜色调色板、字体大小、间距单位等。这些设置将影响编辑器中的块和全局样式。
styles: 定义主题的全局样式，例如背景颜色、文本颜色、字体、排版等。这些样式将应用于整个站点。
templateParts: 定义主题的模板部件，允许你注册自定义的模板部件，以便在主题中使用。

`settings` 的详解

settings 部分允许我们定义主题的全局设置，这些设置会影响编辑器中的块和全局样式。以下是一些常用的 settings 选项：

appearanceTools: 启用或禁用高级外观工具。设置为 true 可以启用所有外观工具，或者你可以单独启用特定的工具，例如 border, color, spacing, typography。
```
"settings": {
  "appearanceTools": true
}
```

color: 定义颜色相关的设置，包括调色板、渐变、链接颜色等。

palette: 定义主题的颜色调色板。调色板是一个包含颜色对象的数组，每个颜色对象都有 name、slug 和 color 属性。name 是颜色的名称，slug 是颜色的唯一标识符，color 是颜色的十六进制值。

"settings": {
  "color": {
    "palette": [
      {
        "name": "Primary",
        "slug": "primary",
        "color": "#007bff"
      },
      {
        "name": "Secondary",
        "slug": "secondary",
        "color": "#6c757d"
      },
      {
        "name": "Success",
        "slug": "success",
        "color": "#28a745"
      },
      {
        "name": "Warning",
        "slug": "warning",
        "color": "#ffc107"
      },
      {
        "name": "Danger",
        "slug": "danger",
        "color": "#dc3545"
      },
      {
        "name": "Light",
        "slug": "light",
        "color": "#f8f9fa"
      },
      {
        "name": "Dark",
        "slug": "dark",
        "color": "#343a40"
      }
    ]
  }
}

gradients: 定义主题的渐变色。渐变色是一个包含渐变对象数组，每个渐变对象都有 name、slug 和 gradient 属性。name 是渐变色的名称，slug 是渐变色的唯一标识符，gradient 是 CSS 渐变属性的值。

"settings": {
  "color": {
    "gradients": [
      {
        "name": "Vivid cyan blue to vivid purple",
        "slug": "vivid-cyan-blue-to-vivid-purple",
        "gradient": "linear-gradient(135deg,rgba(6,147,227,1) 0%,rgb(155,81,224) 100%)"
      },
      {
        "name": "Light green cyan to vivid green cyan",
        "slug": "light-green-cyan-to-vivid-green-cyan",
        "gradient": "linear-gradient(135deg,rgb(122,220,180) 0%,rgb(0,208,130) 100%)"
      }
    ]
  }
}

link: 定义链接颜色设置。可以控制链接的默认颜色。
```
"settings": {
  "color": {
    "link": true
  }
}
```

typography: 定义排版相关的设置，包括字体大小、字体家族、字体粗细等。

fontSizes: 定义主题的字体大小。字体大小是一个包含字体大小对象的数组，每个字体大小对象都有 name、slug 和 size 属性。name 是字体大小的名称，slug 是字体大小的唯一标识符，size 是字体大小的像素值。

"settings": {
  "typography": {
    "fontSizes": [
      {
        "name": "Small",
        "slug": "small",
        "size": "12px"
      },
      {
        "name": "Normal",
        "slug": "normal",
        "size": "16px"
      },
      {
        "name": "Large",
        "slug": "large",
        "size": "20px"
      },
      {
        "name": "Extra Large",
        "slug": "extra-large",
        "size": "24px"
      }
    ]
  }
}

fontFamilies: 定义主题的字体家族。字体家族是一个包含字体家族对象的数组，每个字体家族对象都有 name、slug 和 fontFamily 属性。name 是字体家族的名称，slug 是字体家族的唯一标识符，fontFamily 是 CSS 字体家族属性的值。

"settings": {
  "typography": {
    "fontFamilies": [
      {
        "name": "System Font",
        "slug": "system-font",
        "fontFamily": "-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Oxygen-Sans, Ubuntu, Cantarell, "Helvetica Neue", sans-serif"
      },
      {
        "name": "Arial",
        "slug": "arial",
        "fontFamily": "Arial, sans-serif"
      }
    ]
  }
}

spacing: 定义间距相关的设置，例如 margin、padding 等。

units: 定义间距单位。可以设置为一个字符串数组，例如 ["px", "em", "rem", "vw", "vh"]。
```
"settings": {
  "spacing": {
    "units": ["px", "em", "rem"]
  }
}
```

spacingSizes: 定义间距尺寸，类似于字体大小，你可以预定义一些间距大小，然后在编辑器中使用。

"settings": {
    "spacing": {
        "spacingSizes": [
            {
                "size": "0",
                "slug": "0",
                "name": "0"
            },
            {
                "size": "0.25rem",
                "slug": "1",
                "name": "1"
            },
            {
                "size": "0.5rem",
                "slug": "2",
                "name": "2"
            },
            {
                "size": "1rem",
                "slug": "4",
                "name": "4"
            },
            {
                "size": "1.5rem",
                "slug": "6",
                "name": "6"
            },
            {
                "size": "2rem",
                "slug": "8",
                "name": "8"
            },
            {
                "size": "2.5rem",
                "slug": "10",
                "name": "10"
            },
            {
                "size": "3rem",
                "slug": "12",
                "name": "12"
            },
            {
                "size": "3.5rem",
                "slug": "14",
                "name": "14"
            },
            {
                "size": "4rem",
                "slug": "16",
                "name": "16"
            }
        ]
    }
}

layout: 定义布局相关的设置，例如内容宽度、宽高等。
- contentSize: 定义内容区域的宽度。
- wideSize: 定义宽体布局的宽度。
```
"settings": {
  "layout": {
    "contentSize": "640px",
    "wideSize": "1200px"
  }
}
```

border: 定义边框相关的设置，例如边框颜色、边框宽度、边框样式等。

"settings": {
  "border": {
    "color": true,
    "radius": true,
    "style": true,
    "width": true
  }
}

blocks: 允许你针对特定的块进行设置。你可以使用块的名称（例如 core/paragraph）作为键，然后在该键下定义特定于该块的设置。
```
"settings": {
  "blocks": {
    "core/paragraph": {
      "typography": {
        "fontSize": true,
        "lineHeight": true
      }
    }
  }
}
```

`styles` 的详解

styles 部分允许我们定义主题的全局样式，这些样式将应用于整个站点。以下是一些常用的 styles 选项：

elements: 定义 HTML 元素样式的集合。

link: 定义链接的样式。可以设置链接的颜色、悬停颜色、下划线等。

"styles": {
  "elements": {
    "link": {
      "color": {
        "text": "var(--wp--preset--color--primary)"
      },
      ":hover": {
        "color": {
          "text": "var(--wp--preset--color--secondary)"
        }
      }
    }
  }
}

heading: 定义标题的样式。可以设置标题的颜色、字体大小、字体粗细等。

"styles": {
  "elements": {
    "heading": {
      "color": {
        "text": "var(--wp--preset--color--dark)"
      },
      "typography": {
        "fontWeight": "bold"
      }
    }
  }
}

button: 定义按钮的样式。可以设置按钮的背景颜色、文本颜色、边框颜色等。

"styles": {
  "elements": {
    "button": {
      "color": {
        "background": "var(--wp--preset--color--primary)",
        "text": "#fff"
      },
      "border": {
        "radius": "5px"
      }
    }
  }
}

blocks: 允许你针对特定的块进行样式设置。和settings中的blocks类似，也是使用块的名称作为键，然后在该键下定义特定于该块的样式。

"styles": {
  "blocks": {
    "core/paragraph": {
      "typography": {
        "fontSize": "16px",
        "lineHeight": "1.5"
      },
      "spacing": {
        "margin": {
          "bottom": "1em"
        }
      }
    }
  }
}

global: 定义全局样式。 global 样式会应用到站点的所有元素。

"styles": {
  "global": {
    "body": {
      "background": "var(--wp--preset--color--light)",
      "color": "var(--wp--preset--color--dark)",
      "fontFamily": "var(--wp--preset--font-family--system-font)"
    }
  }
}

集成 CSS 自定义属性

theme.json 允许我们集成 CSS 自定义属性（也称为 CSS 变量），从而实现更灵活和可维护的样式控制。我们可以将颜色、字体大小、间距等值定义为 CSS 变量，然后在 theme.json 中引用这些变量。

例如，我们可以在 theme.json 中定义以下颜色调色板：

"settings": {
  "color": {
    "palette": [
      {
        "name": "Primary",
        "slug": "primary",
        "color": "#007bff"
      },
      {
        "name": "Secondary",
        "slug": "secondary",
        "color": "#6c757d"
      }
    ]
  }
}

WordPress 会自动将这些颜色值转换为 CSS 变量，变量名格式为 --wp--preset--color--{slug}。因此，我们可以使用 --wp--preset--color--primary 和 --wp--preset--color--secondary 来引用这些颜色值。

我们可以在 styles 部分使用这些 CSS 变量来设置元素的样式：

"styles": {
  "elements": {
    "link": {
      "color": {
        "text": "var(--wp--preset--color--primary)"
      },
      ":hover": {
        "color": {
          "text": "var(--wp--preset--color--secondary)"
        }
      }
    }
  }
}

除了 WordPress 自动生成的 CSS 变量外，我们还可以自定义 CSS 变量。我们可以将自定义 CSS 变量添加到 theme.json 的 settings 部分：

"settings": {
  "custom": {
    "my-custom-variable": "10px"
  }
}

WordPress 会将自定义 CSS 变量添加到 :root 选择器中，变量名格式为 --wp--custom--{key}。因此，我们可以使用 --wp--custom--my-custom-variable 来引用这个变量。

我们可以在 styles 部分使用自定义 CSS 变量来设置元素的样式：

"styles": {
  "elements": {
    "button": {
      "border": {
        "radius": "var(--wp--custom--my-custom-variable)"
      }
    }
  }
}

使用 CSS 自定义属性的好处是，我们可以轻松地更改全局样式，而无需修改大量的 CSS 代码。例如，如果我们想更改主题的主色调，只需修改 theme.json 中 primary 颜色的值，所有使用 --wp--preset--color--primary 的元素都会自动更新。

`templateParts` 的使用

templateParts 允许你定义自定义的模板部件，这些部件可以在主题的模板中使用。这使得创建可重用的主题组件变得更加容易。

{
  "templateParts": [
    {
      "name": "header",
      "title": "Header",
      "area": "header"
    },
    {
      "name": "footer",
      "title": "Footer",
      "area": "footer"
    }
  ]
}

在这个例子中，我们定义了两个模板部件：header 和 footer。name 属性指定模板部件的文件名（例如 header.html），title 属性指定模板部件的显示名称，area 属性指定模板部件的区域。

模板部件的文件必须位于主题的 parts 目录下。例如，header 模板部件的文件应该是 parts/header.html。

在主题的模板中，可以使用 template_part 函数来包含模板部件：

<?php get_template_part( 'parts/header' ); ?>

或者使用块的方式：

<!-- wp:template-part {"slug":"header","tagName":"header"} /-->

实际应用案例

下面我们来看一个实际的应用案例，假设我们要创建一个具有以下特点的主题：

主色调为蓝色
辅助色为灰色
字体大小为 16px
内容宽度为 640px

我们可以使用 theme.json 来实现这些需求：

{
  "version": 2,
  "settings": {
    "appearanceTools": true,
    "color": {
      "palette": [
        {
          "name": "Primary",
          "slug": "primary",
          "color": "#007bff"
        },
        {
          "name": "Secondary",
          "slug": "secondary",
          "color": "#6c757d"
        },
        {
          "name": "Light",
          "slug": "light",
          "color": "#f8f9fa"
        },
        {
          "name": "Dark",
          "slug": "dark",
          "color": "#343a40"
        }
      ]
    },
    "typography": {
      "fontSizes": [
        {
          "name": "Normal",
          "slug": "normal",
          "size": "16px"
        }
      ]
    },
    "layout": {
      "contentSize": "640px"
    }
  },
  "styles": {
    "global": {
      "body": {
        "background": "var(--wp--preset--color--light)",
        "color": "var(--wp--preset--color--dark)",
        "fontFamily": "-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Oxygen-Sans, Ubuntu, Cantarell, "Helvetica Neue", sans-serif",
        "fontSize": "var(--wp--preset--font-size--normal)"
      }
    },
    "elements": {
      "link": {
        "color": {
          "text": "var(--wp--preset--color--primary)"
        },
        ":hover": {
          "color": {
            "text": "var(--wp--preset--color--secondary)"
          }
        }
      }
    }
  }
}

在这个 theme.json 文件中，我们定义了颜色调色板、字体大小和内容宽度，并使用这些设置来设置全局样式和链接样式。

高级技巧

使用 !important 覆盖样式: 在某些情况下，你可能需要使用 !important 来覆盖现有的样式。可以在 theme.json 中使用 !important 关键字来强制应用样式。
```
"styles": {
  "elements": {
    "link": {
      "color": {
        "text": "red !important"
      }
    }
  }
}
```

使用过滤器修改 theme.json: WordPress 提供了 wp_theme_json_data_default 过滤器，允许你在运行时修改 theme.json 数据。这使得你可以根据不同的条件动态地修改主题的样式和设置。

add_filter( 'wp_theme_json_data_default', 'my_theme_modify_theme_json' );

function my_theme_modify_theme_json( $theme_json ) {
  $data = $theme_json->get_data();

  // 修改颜色调色板
  $data['settings']['color']['palette'][] = [
    'name'  => 'My Custom Color',
    'slug'  => 'my-custom-color',
    'color' => '#ff0000',
  ];

  $theme_json->set_data( $data );

  return $theme_json;
}

利用 theme.json 实现暗黑模式: 可以通过 CSS 媒体查询和 CSS 自定义属性，在 theme.json 文件中实现暗黑模式。

首先，定义暗黑模式下的颜色变量：

"settings": {
    "custom": {
        "color-background": "#ffffff",
        "color-text": "#000000",
        "color-background-dark": "#000000",
        "color-text-dark": "#ffffff"
    }
},
"styles": {
    "global": {
        "body": {
            "background": "var(--wp--custom--color-background)",
            "color": "var(--wp--custom--color-text)"
        }
    },
    ":root": { //  注意这里用 :root 选择器
        "@media (prefers-color-scheme: dark)": {
            "body": {
                "background": "var(--wp--custom--color-background-dark)",
                "color": "var(--wp--custom--color-text-dark)"
            }
        }
    }
}

然后，在 CSS 中使用这些变量来设置元素的样式。当用户的设备设置为暗黑模式时，媒体查询会激活，并应用暗黑模式下的样式。

总结

theme.json 是一个强大的工具，它可以帮助我们以声明式的方式定义 WordPress 主题的样式和行为。通过 theme.json，我们可以轻松地控制站点的颜色、排版、布局等各个方面，并为用户提供友好的自定义选项。学会使用 theme.json，可以显著提高主题开发效率，并降低维护成本。希望今天的分享能帮助大家更好地理解和使用 theme.json。

一些经验之谈

theme.json 文件是新一代 WordPress 主题开发的核心，掌握它可以让你更好地控制主题的样式和行为，提升开发效率。深入理解其结构和用法，灵活运用 CSS 自定义属性，并结合 WordPress 提供的过滤器，可以构建出高度可定制且易于维护的 WordPress 主题。

利用 WordPress theme.json 实现全局样式和排版控制，集成 CSS 自定义属性

theme.json 的基本结构

settings 的详解

styles 的详解