云策 WordPress 开发者社区

主题开发文档

使用根内边距感知对齐

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

概述

settings.useRootPaddingAwareAlignments 是 theme.json 中一个用于配置 WordPress 如何应用主题水平内边距样式的属性。它不直接关联界面选项或预设注册，而是与 styles.spacing.padding 协同工作，决定内边距是应用于根元素（如 ）还是容器块（如 Group 块）。

关键要点

  • 根内边距（root padding）通常指应用于网页根元素（如 ）的内边距，可通过 theme.json 中的 styles.spacing.padding 配置。
  • 默认情况下，WordPress 将根内边距应用于 元素；启用 settings.useRootPaddingAwareAlignments 后，内边距会转移到容器块上，以实现全宽元素拉伸到屏幕边缘的设计模式。
  • 此属性仅关注水平（左和右）内边距，垂直内边距不相关；启用时需同时设置 styles.spacing.padding 中的水平内边距值。
  • 启用后，WordPress 会生成 CSS 自定义属性（如 --wp--style--root--padding-right）和 .has-global-padding 类，应用于具有约束布局的容器块，以管理内边距和块对齐。

代码示例

{
    "version": 2,
    "settings": {
        "useRootPaddingAwareAlignments": true
    },
    "styles": {
        "spacing": {
            "padding": {
                "top": "0",
                "bottom": "0",
                "left": "2rem",
                "right": "2rem"
            }
        }
    }
}
📄 原文内容

The settings.useRootPaddingAwareAlignments property can be one of the most confusing settings in theme.json. It is not tied to an interface option. Nor is it used for registering presets. Instead, it’s for configuring where WordPress places your theme’s horizontal padding styles.

This means it works in conjunction with styles.spacing.padding in theme.json. You can find out more about general styling in the Styles documentation, but you’ll learn how this specific style works alongside this setting here.

What is root padding?

Before understanding how the settings.useRootPaddingAwareAlignments property works, you must first understand what root padding is.

Root padding is the padding that is applied to a web page’s “root” element. In the case of WordPress themes, this is the <body> element. To customize the spacing for the root element, you must target the styles.spacing.padding element in theme.json.

Take the following theme.json snippet, for example. It adds 0 for top and bottom padding and 2rem for left and right padding:

{
	"version": 2,	
	"styles": {
		"spacing": {
			"padding": {
				"top": "0",
				"bottom": "0",
				"left": "2rem",
				"right": "2rem"
			}
		}
	}
}

By default, this will add 2rem of padding on the left and right sides of the <body> (root) element.

As shown in this screenshot, there is horizontal padding at the root, and a full-width Cover block stretches until it hits that padding:

WordPress site header with a Cover block background. It has padding to the left and right of it so that it doesn't stretch the full width of the screen.

This is the CSS that WordPress outputs based on the above theme.json code:

body {
	padding-top: 0;
	padding-right: 2rem;
	padding-bottom: 0;
	padding-left: 2rem;
}

But—and this is where things can look odd to seasoned designers—when settings.useRootPaddingAwareAlignments is enabled, the “root” padding is no longer applied to the root element. It is applied to container blocks like Group. 

You’ll learn more about why this happens in the next section. The main goal right now is to understand that root padding is traditionally applied to the <body> element, and that is what most theme authors would expect.

For root padding aware alignments, WordPress is only concerned with the horizontal (left and right) padding. So the vertical (top and bottom) padding is not relevant to this documentation.

Enabling root padding aware alignments

By default, WordPress will apply root padding to the <body> element. If this makes sense for your theme’s design, you don’t need to do anything else.

But what if you want to let full-width items stretch to the edges of the screen and have padding on the root element? 

When compared to the first screenshot, notice how the Cover block stretches to edges of the screen but there is padding still applied to the nested blocks here:

WordPress site header with a Cover block background that stretches the full width of the screen.

This is a common design pattern, and there are several ways to stretch elements beyond their containers in CSS. But WordPress has a standard approach that would work with any theme.

That’s where settings.useRootPaddingAwareAlignments comes in. When this property is set to true, it puts the root padding on container elements instead of <body>. This must also be combined with a styles.spacing.padding object, particularly with horizontal padding applied.

Try this code in your theme.json:

{
	"version": 2,
	"settings": {
		"useRootPaddingAwareAlignments": true
	},	
	"styles": {
		"spacing": {
			"padding": {
				"top": "0",
				"bottom": "0",
				"left": "2rem",
				"right": "2rem"
			}
		}
	}
}

There is no right or wrong way to handle root padding. It is a situational setting where you must decide which option is best for your theme’s design.

How does this work?

It’s not particularly vital to know how WordPress handles all of this under the hood, but sometimes you might just want a deeper understanding of what’s going on.

When you enable settings.useRootPaddingAwareAlignments, as shown in the last theme.json example, WordPress will generate two new bits of CSS. The first is that it defines some CSS custom properties for the root padding:

body {
	--wp--style--root--padding-top: 0;
	--wp--style--root--padding-right: 2rem;
	--wp--style--root--padding-bottom: 0;
	--wp--style--root--padding-left: 2rem;
}

The second is that it adds a .has-global-padding class:

.has-global-padding {
	padding-right: var(--wp--style--root--padding-right);
	padding-left: var(--wp--style--root--padding-left);
}

This class is then given to container blocks with constrained layouts (for example, Group blocks with the Layout > Inner blocks use content width option enabled):

<div class="wp-block-group has-global-padding is-layout-constrained wp-block-group-is-layout-constrained">
	<!-- nested blocks... -->
</div>

Beyond that, WordPress adds inline CSS to stretch nested wide and full-width blocks beyond their parent block’s width (including the additional padding that’s added to the width).