云策 WordPress 开发者社区

主题开发文档

设置参考

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

概述

本文档是 theme.json 中 settings 对象可配置属性的参考指南，涵盖外观工具、边框、颜色、自定义、尺寸、布局、灯箱、位置、阴影、间距、排版和根填充感知对齐等设置。每个设置都有详细的文档链接。

关键要点

  • settings.appearanceTools：顶级布尔属性，默认 false，控制外观工具启用。
  • settings.border：对象属性，包含 color、radius、style、width 子属性，启用 color、style 或 width 会自动启用其他两个。
  • settings.color：对象属性，支持背景、自定义颜色、双色调、渐变、调色板等子属性，用于颜色配置。
  • settings.custom：对象属性，允许定义任意自定义属性，类型灵活。
  • settings.dimensions：对象属性，包含 minHeight 子属性，默认 false。
  • settings.layout：对象属性，包含 contentSize 和 wideSize 子属性，用于布局尺寸设置。
  • settings.lightbox：对象属性，包含 allowEditing 和 enabled 子属性，仅适用于 WordPress 6.4+ 的核心 Image 块。
  • settings.position：对象属性，包含 sticky 子属性，默认 false。
  • settings.shadow：对象属性，包含 defaultPresets 和 presets 子属性，用于阴影预设管理。
  • settings.spacing：对象属性，支持块间距、自定义间距、边距、内距、间距比例和单位等子属性。
  • settings.typography：对象属性，涵盖字体大小、字体家族、字体样式、行高等排版相关设置。
  • settings.useRootPaddingAwareAlignments：顶级布尔属性，默认 false，需与 styles.spacing.padding 配合使用。

注意事项

  • settings.lightbox 仅适用于 WordPress 6.4 及以上版本的核心 Image 块。
  • settings.useRootPaddingAwareAlignments 启用时，styles.spacing.padding 必须定义为包含 top、right、bottom、left 的单独样式对象。
📄 原文内容

The document is a reference to the available settings properties that you can configure via the settings object in theme.json. Each of the settings has an in-depth guide on how to use it within the Settings documentation.

Appearance Tools

settings.appearanceTools is a top-level property with no sub-properties nested beneath it. It is documented at Settings: Appearance Tools.

Property Type Default
appearanceTools boolean false

Border

settings.border is an object that supports the nested properties listed in the below table. It is documented at Settings: Border.

Property Type Default
color boolean false
radius boolean false
style boolean false
width boolean false

Enabling any one of the color, style, or width settings will automatically enable the other two since the properties are linked together.

Color

settings.color is an object that supports the nested properties listed in the below table. It is documented at Settings: Color.

Property Type Default Props
background boolean true —
custom boolean true —
customDuotone boolean true —
customGradient boolean true —
defaultDuotone boolean true —
defaultGradients boolean true —
defaultPalette boolean true —
duotone array <object> array colors, name, slug
gradients array <object> array gradient, name, slug
link boolean false —
palette array <object> array color, name, slug
text boolean true —

Custom

settings.custom is an object that supports any number of nested custom properties, as shown in the below table. It is documented at Settings: Custom.

Property Type Default
custom.<custom> any —

Dimensions

settings.dimensions is an object that supports the nested properties listed in the below table. It is documented at Settings: Dimensions.

Property Type Default
minHeight boolean false

Layout

settings.layout is an object that supports the nested properties listed in the below table. It is documented at Settings: Layout.

Property Type Default
contentSize string ""
wideSize string ""

Lightbox

settings.lightbox is an object that supports the nested properties listed in the below table. It is documented at Settings: Lightbox.

Property Type Default
allowEditing boolean true
enabled boolean false

This setting is only available as of WordPress 6.4 and is specific to the core Image block (core/image).

Position

settings.position is an object that supports the nested properties listed in the below table. It is documented at Settings: Position.

Property Type Default
sticky boolean false

Shadow

settings.shadow is an object that supports the nested properties listed in the below table. It is documented at Settings: Shadow.

Property Type Default Props
defaultPresets boolean true
presets array <object> array name, shadow, slug

Spacing

settings.spacing is an object that supports the nested properties listed in the below table. It is documented at Settings: Spacing.

Property Type Default Props
blockGap boolean|null null —
customSpacingSize boolean true —
margin boolean false —
padding boolean false —
spacingScale object object operator, increment, steps, mediumStep, unit
spacingSizes array <object> array name, size, slug
units array <string> [ "px", "em", "rem", "vh", "vw", "%" ] —

Typography

settings.typography is an object that supports the nested properties listed in the below table. It is documented at Settings: Typography.

Property Type Default Props
customFontSize boolean true —
dropCap boolean true —
fontFamilies array <object> array fontFace, fontFamily, name, slug
fontSizes array <object> array fluid, name, size, slug
fontStyle boolean true —
fontWeight boolean true —
fluid boolean false —
letterSpacing boolean true —
lineHeight boolean false —
textColumns boolean false —
textDecoration boolean true —
textTransform boolean true —
writingMode boolean false —

Use Root Padding Aware Alignments

settings.useRootPaddingAwareAlignments is a top-level property with no sub-properties nested beneath it. It is documented at Settings: Use Root Padding Aware Alignments.

Property Type Default
useRootPaddingAwareAlignments boolean false

This setting works together with styles.spacing.padding in theme.json. If enabled, styles.spacing.padding must be an object that defines the top, right,  bottom, and left styles separately.