WordPress 主题 spacing 设置完全指南

发布于2023年10月2日2026年7月30日作者:XQcms

网页设计里，间距处理往往考验功底。margin、padding、gap 这几个属性怎么配，直接关系到页面节奏感是否舒服。WordPress 通过 theme.json 里的 settings.spacing 对象，把这些控制权交到了主题开发者手上。

本文把官方文档里那套东西掰开揉碎，不讲虚的，直接告诉你每个配置项是干嘛的、怎么用、什么场景下该开该关。读完你就能在自己的主题里把间距这块整明白。

一、spacing 配置项速览

theme.json 里跟间距相关的配置都挂在 settings.spacing 下面，核心就这几个：

配置项	作用	默认值
`blockGap`	开关”块间距”控制，同时控制是否输出 WP 自带的间距样式	`null`
`margin`	开关”外边距”控制	`false`
`padding`	开关”内边距”控制	`false`
`customSpacingSize`	是否允许用户手动输入自定义数值	`true`
`spacingScale`	定义一套自动生成的间距档位	7 档递增
`spacingSizes`	手动定义每一档间距的具体数值	`[]`
`units`	允许使用的 CSS 单位列表	一堆

默认的 theme.json 长这样：

json

{
  "version": 2,
  "settings": {
    "spacing": {
      "blockGap": null,
      "customSpacingSize": true,
      "margin": false,
      "padding": false,
      "spacingScale": {
        "operator": "*",
        "increment": 1.5,
        "steps": 7,
        "mediumStep": 1.5,
        "unit": "rem"
      },
      "spacingSizes": [],
      "units": ["px", "em", "rem", "vh", "vw", "%"]
    }
  }
}

下面逐个拆解。

二、功能开关：要不要给用户这些控制选项

blockGap：块间距

“块间距”就是页面里块跟块之间的空隙。普通流式布局里用 margin-top 实现，flex 或 grid 布局里用 gap。

blockGap 这个值有点绕，三个取值三种行为：

`blockGap`	编辑器里显示控制？	WP 自动输出间距样式？
`null`	不显示	不输出
`true`	显示	输出
`false`	不显示	输出

注意 null 和 false 的区别：前者连样式都不给你生成，后者只是隐藏了界面控制但样式照样有。

json

{
  "version": 2,
  "settings": {
    "spacing": {
      "blockGap": true
    }
  }
}

开启后，支持这个特性的区块（比如”文章列表”区块）在侧边栏就会出现 Block Spacing 下拉菜单。

WP 输出的样式大概是这个意思（每个容器会生成的 class）：

css

.wp-container-17 > * {
  margin-block-start: var(--wp--preset--spacing--plus-4);
  margin-block-end: 0;
}

如果你把 blockGap 设成 null，这段 CSS 压根不会出现，你得自己写样式补上。

margin 和 padding

这俩简单多了，默认都是关的。想开就设 true：

json

{
  "version": 2,
  "settings": {
    "spacing": {
      "margin": true,
      "padding": true
    }
  }
}

开了之后，支持的区块在侧边栏就能调外边距和内边距了。

三、限制用户输入：防手抖

customSpacingSize：关掉”自定义数值”

默认情况下，用户选了某个间距控件后，既可以从预设里选，也可以自己输入任意数值。

如果你不希望用户乱填破坏设计一致性，把 customSpacingSize 设成 false：

json

{
  "version": 2,
  "settings": {
    "spacing": {
      "customSpacingSize": false
    }
  }
}

这样用户就只能从你预设的档位里选，没法自己瞎填。

units：限定可用单位

如果允许自定义输入，那用户用什么单位你也能管。units 数组里列出来的就是允许使用的单位：

json

{
  "version": 2,
  "settings": {
    "spacing": {
      "units": ["px", "rem", "em", "%"]
    }
  }
}

WP 官方允许的单位有这些：px、%、em、rem、vw、vh、vmin、vmax、ch、ex、cm、mm、in、pc、pt。挑你需要的放进去就行。

四、间距预设：两套方案

WP 会把你定义的间距预设生成 CSS 自定义属性（var(--wp--preset--spacing--xxx)），在编辑器和前端都能用。

预设定义有两种方式，二选一就行。

方案一：spacingScale（自动生成档位）

用一组规则自动算出一串间距值。配置项有这些：

operator：递进方式，"+" 加法或 "*" 乘法，默认 "*"
increment：步长数值，默认 1.5
steps：总档数，默认 7
mediumStep：中间档的数值，默认 1.5
unit：单位，默认 "rem"

举个例子，7 档、每档加 0.25rem：

json

{
  "version": 2,
  "settings": {
    "spacing": {
      "spacingScale": {
        "operator": "+",
        "increment": 0.25,
        "steps": 7,
        "mediumStep": 1,
        "unit": "rem"
      }
    }
  }
}

生成的结果：

CSS 变量	值	界面标签
`--wp--preset--spacing--20`	0.25rem	2X-Small
`--wp--preset--spacing--30`	0.5rem	X-Small
`--wp--preset--spacing--40`	0.75rem	Small
`--wp--preset--spacing--50`	1rem	Medium
`--wp--preset--spacing--60`	1.25rem	Large
`--wp--preset--spacing--70`	1.5rem	X-Large
`--wp--preset--spacing--80`	1.75rem	2X-Large

注意：中间值永远落在 --wp--preset--spacing--50 上。如果 steps 超过 10，低于 --10 的档位不会生成，因为 50 是中间基准点。

想关掉这套自动生成的，把 steps 设成 0：

json

{
  "version": 2,
  "settings": {
    "spacing": {
      "spacingScale": {
        "steps": 0
      }
    }
  }
}

方案二：spacingSizes（手动定义每一档）

想要精确控制每个档位的名称和数值，用这个。每个档位有三个字段：

name：显示名
size：数值（支持 clamp() 等函数）
slug：变量后缀

示例：5 档，每档 0.25rem 递增：

json

{
  "version": 2,
  "settings": {
    "spacing": {
      "spacingSizes": [
        {
          "name": "小",
          "size": "0.25rem",
          "slug": "xs"
        },
        {
          "name": "小",
          "size": "0.5rem",
          "slug": "sm"
        },
        {
          "name": "中",
          "size": "0.75rem",
          "slug": "md"
        },
        {
          "name": "大",
          "size": "1rem",
          "slug": "lg"
        },
        {
          "name": "大",
          "size": "1.25rem",
          "slug": "xl"
        }
      ]
    }
  }
}

生成的变量就是 --wp--preset--spacing--xs、--wp--preset--spacing--sm…… 以此类推。

流体间距（响应式）

想搞响应式间距？用 spacingSizes 配合 clamp() 就行：

json

{
  "version": 2,
  "settings": {
    "spacing": {
      "spacingSizes": [
        {
          "name": "基础间距",
          "size": "clamp(1rem, 2vw + 0.5rem, 2rem)",
          "slug": "base"
        }
      ]
    }
  }
}

这样间距会随着视口宽度平滑变化，移动端和桌面端自动适配。

五、编辑器里的呈现逻辑

间距预设少于等于 7 档时，编辑器里显示为滑块，拖动选择很直观。超过 7 档则变成下拉菜单。

所以如果你定义了 8 个以上的间距档位，用户就得从下拉列表里选了。设计时可以把常用档位控制在 7 个以内提升操作体验。

六、几个实际场景

场景一：输出干净样式，不让用户调间距

json

"spacing": {
  "blockGap": null,
  "margin": false,
  "padding": false
}

blockGap 用 null 让 WP 完全不输出间距样式，你自己在 CSS 里控制所有间距。

场景二：给设计师预留自由度

json

"spacing": {
  "blockGap": true,
  "margin": true,
  "padding": true,
  "customSpacingSize": true,
  "spacingScale": {
    "steps": 0
  },
  "spacingSizes": [
    { "name": "小", "size": "0.5rem", "slug": "s" },
    { "name": "中", "size": "1rem", "slug": "m" },
    { "name": "大", "size": "2rem", "slug": "l" }
  ]
}

提供 3 档常用预设，同时允许用户自己输入任意值。

场景三：严格限制用户选择

json

"spacing": {
  "blockGap": true,
  "margin": true,
  "padding": false,
  "customSpacingSize": false,
  "spacingSizes": [
    { "name": "紧凑", "size": "0.5rem", "slug": "tight" },
    { "name": "舒适", "size": "1rem", "slug": "comfortable" },
    { "name": "宽松", "size": "2rem", "slug": "relaxed" }
  ],
  "units": ["rem"]
}

只给 3 个预设选项，只能选不能改，单位限死 rem。

总结

间距配置在 theme.json 的 settings.spacing 下一共就管这几件事：

开什么功能——blockGap、margin、padding 决定用户能调哪些间距属性
给什么选项——spacingScale 或 spacingSizes 定义预设档位，customSpacingSize 决定能否自己输入
用什么单位——units 限定可选单位

把这套东西理清楚，你的主题在间距控制上就站稳了。剩下的就是根据你的设计稿定一套合理的数值，让用户用得顺手，页面看着舒服。