Gutenberg SpacingSizesControl 间距尺寸控件全解析三种视图模式、间距预设体系与源码实现【免费下载链接】gutenbergThe Block Editor project for WordPress and beyond. Plugin is available from the official repository.项目地址: https://gitcode.com/GitHub_Trending/gu/gutenbergSpacingSizesControl导出名为__experimentalSpacingSizesControl是 Gutenberg 区块编辑器中用于调整区块间距Padding、Margin、块间距等的预设型控件。它允许用户针对不同方向上/右/下/左独立或联动修改间距值并支持 Single、Axial、Custom 三种视图模式。读完本文你将掌握该组件的完整 Props API、预设Preset值体系的底层转换原理、初始视图自动判定逻辑以及它在全局样式面板中的真实调用方式能够直接在自己的区块编辑扩展中接入这套间距控制 UI。组件概览一个控件三种视图模式SpacingSizesControl的核心设计是以预设滑杆/下拉为核心输入手段同时保留自定义数值输入的能力。它内置三种视图模式定义于 utils.js 的VIEWS常量Single单边模式一次只控制一个方向如仅top。Axial轴向模式同时控制水平left/right与垂直top/bottom两组方向由 Link sides / Unlink sides 按钮切换进入。Custom自定义模式四个方向top、right、bottom、left各自独立控制。组件默认不强制指定视图而是根据传入的values与sides自动选择初始视图详见下文初始视图判定逻辑用户也可以通过右上角的链接/取消链接按钮在 Axial 与 Custom 之间手动切换。基础用法与引入方式该组件属于wordpress/block-editor包但在当前版本中仍以实验性 API 形式导出需要__experimental前缀。导出位置见 components/index.jsexport { default as __experimentalSpacingSizesControl } from ./spacing-sizes-control;基础用法摘自 README.mdimport { __experimentalSpacingSizesControl as SpacingSizesControl } from wordpress/block-editor; import { useState } from wordpress/element; function Example() { const [ sides, setSides ] useState( { top: 0px, right: 0px, bottom: 0px, left: 0px, } ); return ( SpacingSizesControl values{ sides } onChange{ setSides } labelSides / ); }组件渲染为一个fieldset结构见 index.jsx内部由HStack头部视觉标签 链接按钮与VStack内容区组成。onChange收到的不是单个方向的值而是包含所有方向的最新对象——主组件中的handleOnChange会将新值与旧值合并const newValues { ...values, ...nextValue };。Props API 详解原文档共定义了 10 个 Props含values下表完整继承并补充了源码中的默认值与行为细节依据 README.md 与 index.jsxProps类型必填默认值说明inputPropsObject否—透传给底层输入控件的额外属性labelString是—控件标签如 Padding、Margin、Block spacingminimumCustomValueNumber否0自定义输入允许的最小值负数时允许拖动产生负值allowNegativeOnDragonChangeFunction是—值变化回调接收包含更新后全部方向值的对象onMouseOutFunction否—鼠标离开控件时回调onMouseOverFunction否—鼠标进入控件时回调showSideInLabelBoolean否true是否在控件标签中显示方向top、right 等sidesArray否ALL_SIDEStop、right、bottom、left可控制的方向列表useSelectBoolean否—是否使用下拉选择控件呈现预设值valuesObject否DEFAULT_VALUES各方向均为undefined各方向当前间距值几点源码级补充说明sides的特殊取值除了四个物理方向还支持horizontal与vertical两个轴向值。当sides恰好为[horizontal, vertical]且长度为 2 时组件会直接进入轴向模式且不显示链接/取消链接按钮见 index.jsx。这与 dimensions-panel.jsx 中的AXIAL_SIDES常量用法一致。values缺省兜底values未传入时使用DEFAULT_VALUES四个方向均为undefined组件依然能正常渲染轴向视图下滑杆定位在 0 位置。label的双重用途它既是fieldset的 legend 视觉标签也会被作为type透传给底层输入控件用于拼接 aria-label如 Top padding见 spacing-input-control.jsx。minimumCustomValue与负值在 dimensions-panel.jsx 中Margin 面板传入了minimumCustomValue{ -Infinity }允许用户为外边距设置负值该值同时驱动allowNegativeOnDrag控制滑杆拖动是否允许进入负区间。初始视图判定逻辑getInitialView 源码解析组件首次渲染时的视图由 utils.js 中的getInitialView( values, sides )决定其判定优先级如下轴向视图Axial满足任一条件支持对应轴向且top bottom、left right且至少有一个轴向值非空hasMatchingAxialValues无任何已定义值且各轴向两侧方向成对支持hasNoValuesAndBalancedSides由hasBalancedSidesSupport判断 top/bottom、left/right 是否成对出现。单边视图Single仅支持轴向方向horizontal/vertical且只有一个方向有值时返回第一个有值的方向sides只有一个方向且无值时返回该方向。兜底为 Custom 视图值比较混合例如 top 与 bottom 不一致时进入四边独立编辑。这解释了测试 index.jsdom.test.jsx 中的行为断言top: 1rem, right: 2rem, bottom: 1rem, left: 2rem默认进入轴向视图渲染 2 个 slider而top: 1rem, right: 2rem, bottom: 1.5rem, left: 2rem因垂直方向值不匹配而进入 Custom 视图4 个 slider。轴向与 Custom 视图之间通过LinkedButton切换轴向视图显示 Unlink sides取消链接点击后进入 CustomCustom 视图显示 Link sides链接点击后回到轴向。该按钮的实现见 linked-button.jsx图标分别使用link与linkOff。间距预设体系useSpacingSizes 与预设值格式SpacingSizesControl区别于普通数值输入控件的核心在于它与 Gutenberg 的间距预设spacing preset体系深度集成。预设数据的来源与合并组件通过 use-spacing-sizes.js 从编辑器设置中读取四组数据spacing.spacingSizes.custom—— 用户自定义间距预设spacing.spacingSizes.theme—— 主题定义的间距预设spacing.spacingSizes.default—— 默认间距预设spacing.defaultSpacingSizes—— 布尔开关为false时禁用默认预设集。合并规则源码可确认恒在列表首位插入{ name: __( None ), slug: 0, size: 0 }保证无间距选项始终可用按 custom → theme → default 顺序拼接若所有 slug 均以数字开头/^[0-9]/则使用Intl.Collator按数字语义排序若总数量超过RANGE_CONTROL_MAX_SIZE值为 8见 utils.js会在列表头部额外插入一个{ name: __( Default ), slug: default, size: undefined }兜底项同时触发 UI 层面的模式切换见下文。预设值的存储格式间距预设值以var:preset|spacing|slug字符串形式存储例如var:preset|spacing|40。该格式与 CSS 变量var(--wp--preset--spacing--40)一一对应转换函数集中在 utils.js函数作用isValueSpacingPreset( value )判断某值是否为间距预设格式getCustomValueFromPreset( value, spacingSizes )将预设值解析为实际尺寸值如0.5remgetPresetValueFromCustomValue( value, spacingSizes )反向操作若自定义值恰好命中某预设的size则编码为var:preset|spacing|slug格式命中失败则原样返回getSpacingPresetCssVar( value )将var:preset|spacing|40转为var(--wp--preset--spacing--40)getSliderValueFromPreset( presetValue, spacingSizes )将预设值映射为滑杆位置索引未命中返回NaN避免滑块悬停居中其中getPresetValueFromCustomValue尤其重要在轴向/单边/Custom 三种视图的createHandleOnChange中组件都会先对所有现存值做一次自定义值 → 预设值的编码再写入新方向的值从而保证相同尺寸被规范化为预设引用见 axial.jsx、separated.jsx、single.jsx。这三个函数getSpacingPresetCssVar、isValueSpacingPreset、getCustomValueFromPreset同时通过 components/index.js 作为独立工具导出供外部复用。预设数量决定交互形态底层输入控件由 spacing-input-control.jsx 承载它复用PresetInputControl的能力预设较少时≤ 8 个以 RangeControl 滑杆呈现每个预设对应一个档位预设较多时自动切换为下拉选择CustomSelectControl。这一行为有明确的测试佐证在 test/index.jsdom.test.jsx 的 Large Preset Sets 分组中模拟 15 个预设后断言页面不再出现slider而是渲染出 2 个combobox轴向视图下的垂直/水平两个下拉。同时useSelectProp 可强制使用下拉形态。自定义数值与单位支持除预设档位外用户还可以通过 Set custom value 开关切换到底层数值输入spinbutton。此时由 spacing-input-control.jsx 中的CUSTOM_VALUE_SETTINGS约束各单位的取值范围与步进单位最大值步进px3001%/vw/vh/svw/lvw/dvw/svh/lvh/dvh/vi/svi/lvi/dvi/vb/svb/lvb/dvb/vmin/svmin/lvmin/dvmin/vmax/svmax/lvmax/dvmax1001em/rm100.1可用单位列表来自编辑器设置spacing.units通过useSettings读取未配置时回退为[px, em, rem]。此外spacing-input-control还会通过useSelect读取编辑器设置中的disableCustomSpacingSizes为true时彻底禁用自定义数值输入仅保留预设档位。测试同样覆盖了minimumCustomValue对min属性的约束min10。在区块编辑器中的真实使用场景SpacingSizesControl并非孤立组件它是全局样式Global Styles面板中间距控制的主要 UI。在 dimensions-panel.jsx 中它被用于Padding内边距values{ paddingValues }、onChange{ setPaddingValues }、label{ __( Padding ) }Margin外边距额外传入minimumCustomValue{ -Infinity }以允许负值Block spacing块间距 / gap通过key{ isAxialGap ? axial-gap : single-gap }在轴向与单边形态间切换min{ 0 }。值得注意的是该面板会将本地覆盖值与继承值合并后再传给values因为预设滑杆没有 placeholder 插槽激活的档位本身即静止状态的视觉提示见 dimensions-panel.jsx 中关于paddingValues、gapRawForDisplay的注释。这为在自有扩展中接入该组件提供了正确的数据流参考传入的values应当是完整的四方向对象且优先传入预设格式的值以获得档位高亮与规范化存储的双重收益。无障碍与测试保障组件在无障碍方面做了体系化设计根元素为fieldsetlegend配合BaseControl.VisualLabel使整组控件形成可被屏幕阅读器识别的分组语义rolegroup每个方向控件的 aria-label 由方向 类型拼接生成例如轴向视图下为 Vertical padding / Horizontal padding单边模式下为 Top padding通过_x( %1$s %2$s, spacing )翻译见 spacing-input-control.jsxshowSideInLabel{ false }可隐藏标签中的方向后缀用于减少冗长标签的场景。测试覆盖同样完备test/index.jsdom.test.jsx1098 行涵盖基础渲染、轴向/自定义值变更、单边配置、预设功能、大规模预设集、边界情况undefined、空对象、部分对象、clamp()等复杂 CSS 值、非法输入、零值、附加 PropsminimumCustomValue、onMouseOver/Out、inputProps、useSelect、主题预设集成与无障碍标签test/select.browser.test.js 则针对浏览器环境下预设下拉的交互行为做补充验证。小结SpacingSizesControl是一个将预设档位选择与自由数值输入有机结合的间距控件三视图模式Single / Axial / Custom配合自动初始视图判定让不同数据形态都能获得最合适的编辑界面以var:preset|spacing|slug为核心的预设值体系保证了 UI 档位、存储值与最终 CSS 变量之间的无损双向转换而预设数量阈值8 个驱动的滑杆/下拉形态切换则为预设规模不同的主题提供了统一的交互体验。若你的自定义区块或面板需要一套与 Gutenberg 全局样式一致的间距编辑体验直接复用__experimentalSpacingSizesControl并将值按预设格式规范化存储是最贴近原生行为的接入方式。参考源码路径组件入口index.jsx工具函数与常量utils.js预设数据 Hookuse-spacing-sizes.js三种视图实现axial.jsx、separated.jsx、single.jsx底层输入控件spacing-input-control.jsx链接/取消链接按钮linked-button.jsx测试index.jsdom.test.jsx、select.browser.test.js实际调用场景dimensions-panel.jsx包级导出components/index.js【免费下载链接】gutenbergThe Block Editor project for WordPress and beyond. Plugin is available from the official repository.项目地址: https://gitcode.com/GitHub_Trending/gu/gutenberg创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Gutenberg SpacingSizesControl 间距尺寸控件全解析：三种视图模式、间距预设体系与源码实现
Gutenberg SpacingSizesControl 间距尺寸控件全解析三种视图模式、间距预设体系与源码实现【免费下载链接】gutenbergThe Block Editor project for WordPress and beyond. Plugin is available from the official repository.项目地址: https://gitcode.com/GitHub_Trending/gu/gutenbergSpacingSizesControl导出名为__experimentalSpacingSizesControl是 Gutenberg 区块编辑器中用于调整区块间距Padding、Margin、块间距等的预设型控件。它允许用户针对不同方向上/右/下/左独立或联动修改间距值并支持 Single、Axial、Custom 三种视图模式。读完本文你将掌握该组件的完整 Props API、预设Preset值体系的底层转换原理、初始视图自动判定逻辑以及它在全局样式面板中的真实调用方式能够直接在自己的区块编辑扩展中接入这套间距控制 UI。组件概览一个控件三种视图模式SpacingSizesControl的核心设计是以预设滑杆/下拉为核心输入手段同时保留自定义数值输入的能力。它内置三种视图模式定义于 utils.js 的VIEWS常量Single单边模式一次只控制一个方向如仅top。Axial轴向模式同时控制水平left/right与垂直top/bottom两组方向由 Link sides / Unlink sides 按钮切换进入。Custom自定义模式四个方向top、right、bottom、left各自独立控制。组件默认不强制指定视图而是根据传入的values与sides自动选择初始视图详见下文初始视图判定逻辑用户也可以通过右上角的链接/取消链接按钮在 Axial 与 Custom 之间手动切换。基础用法与引入方式该组件属于wordpress/block-editor包但在当前版本中仍以实验性 API 形式导出需要__experimental前缀。导出位置见 components/index.jsexport { default as __experimentalSpacingSizesControl } from ./spacing-sizes-control;基础用法摘自 README.mdimport { __experimentalSpacingSizesControl as SpacingSizesControl } from wordpress/block-editor; import { useState } from wordpress/element; function Example() { const [ sides, setSides ] useState( { top: 0px, right: 0px, bottom: 0px, left: 0px, } ); return ( SpacingSizesControl values{ sides } onChange{ setSides } labelSides / ); }组件渲染为一个fieldset结构见 index.jsx内部由HStack头部视觉标签 链接按钮与VStack内容区组成。onChange收到的不是单个方向的值而是包含所有方向的最新对象——主组件中的handleOnChange会将新值与旧值合并const newValues { ...values, ...nextValue };。Props API 详解原文档共定义了 10 个 Props含values下表完整继承并补充了源码中的默认值与行为细节依据 README.md 与 index.jsxProps类型必填默认值说明inputPropsObject否—透传给底层输入控件的额外属性labelString是—控件标签如 Padding、Margin、Block spacingminimumCustomValueNumber否0自定义输入允许的最小值负数时允许拖动产生负值allowNegativeOnDragonChangeFunction是—值变化回调接收包含更新后全部方向值的对象onMouseOutFunction否—鼠标离开控件时回调onMouseOverFunction否—鼠标进入控件时回调showSideInLabelBoolean否true是否在控件标签中显示方向top、right 等sidesArray否ALL_SIDEStop、right、bottom、left可控制的方向列表useSelectBoolean否—是否使用下拉选择控件呈现预设值valuesObject否DEFAULT_VALUES各方向均为undefined各方向当前间距值几点源码级补充说明sides的特殊取值除了四个物理方向还支持horizontal与vertical两个轴向值。当sides恰好为[horizontal, vertical]且长度为 2 时组件会直接进入轴向模式且不显示链接/取消链接按钮见 index.jsx。这与 dimensions-panel.jsx 中的AXIAL_SIDES常量用法一致。values缺省兜底values未传入时使用DEFAULT_VALUES四个方向均为undefined组件依然能正常渲染轴向视图下滑杆定位在 0 位置。label的双重用途它既是fieldset的 legend 视觉标签也会被作为type透传给底层输入控件用于拼接 aria-label如 Top padding见 spacing-input-control.jsx。minimumCustomValue与负值在 dimensions-panel.jsx 中Margin 面板传入了minimumCustomValue{ -Infinity }允许用户为外边距设置负值该值同时驱动allowNegativeOnDrag控制滑杆拖动是否允许进入负区间。初始视图判定逻辑getInitialView 源码解析组件首次渲染时的视图由 utils.js 中的getInitialView( values, sides )决定其判定优先级如下轴向视图Axial满足任一条件支持对应轴向且top bottom、left right且至少有一个轴向值非空hasMatchingAxialValues无任何已定义值且各轴向两侧方向成对支持hasNoValuesAndBalancedSides由hasBalancedSidesSupport判断 top/bottom、left/right 是否成对出现。单边视图Single仅支持轴向方向horizontal/vertical且只有一个方向有值时返回第一个有值的方向sides只有一个方向且无值时返回该方向。兜底为 Custom 视图值比较混合例如 top 与 bottom 不一致时进入四边独立编辑。这解释了测试 index.jsdom.test.jsx 中的行为断言top: 1rem, right: 2rem, bottom: 1rem, left: 2rem默认进入轴向视图渲染 2 个 slider而top: 1rem, right: 2rem, bottom: 1.5rem, left: 2rem因垂直方向值不匹配而进入 Custom 视图4 个 slider。轴向与 Custom 视图之间通过LinkedButton切换轴向视图显示 Unlink sides取消链接点击后进入 CustomCustom 视图显示 Link sides链接点击后回到轴向。该按钮的实现见 linked-button.jsx图标分别使用link与linkOff。间距预设体系useSpacingSizes 与预设值格式SpacingSizesControl区别于普通数值输入控件的核心在于它与 Gutenberg 的间距预设spacing preset体系深度集成。预设数据的来源与合并组件通过 use-spacing-sizes.js 从编辑器设置中读取四组数据spacing.spacingSizes.custom—— 用户自定义间距预设spacing.spacingSizes.theme—— 主题定义的间距预设spacing.spacingSizes.default—— 默认间距预设spacing.defaultSpacingSizes—— 布尔开关为false时禁用默认预设集。合并规则源码可确认恒在列表首位插入{ name: __( None ), slug: 0, size: 0 }保证无间距选项始终可用按 custom → theme → default 顺序拼接若所有 slug 均以数字开头/^[0-9]/则使用Intl.Collator按数字语义排序若总数量超过RANGE_CONTROL_MAX_SIZE值为 8见 utils.js会在列表头部额外插入一个{ name: __( Default ), slug: default, size: undefined }兜底项同时触发 UI 层面的模式切换见下文。预设值的存储格式间距预设值以var:preset|spacing|slug字符串形式存储例如var:preset|spacing|40。该格式与 CSS 变量var(--wp--preset--spacing--40)一一对应转换函数集中在 utils.js函数作用isValueSpacingPreset( value )判断某值是否为间距预设格式getCustomValueFromPreset( value, spacingSizes )将预设值解析为实际尺寸值如0.5remgetPresetValueFromCustomValue( value, spacingSizes )反向操作若自定义值恰好命中某预设的size则编码为var:preset|spacing|slug格式命中失败则原样返回getSpacingPresetCssVar( value )将var:preset|spacing|40转为var(--wp--preset--spacing--40)getSliderValueFromPreset( presetValue, spacingSizes )将预设值映射为滑杆位置索引未命中返回NaN避免滑块悬停居中其中getPresetValueFromCustomValue尤其重要在轴向/单边/Custom 三种视图的createHandleOnChange中组件都会先对所有现存值做一次自定义值 → 预设值的编码再写入新方向的值从而保证相同尺寸被规范化为预设引用见 axial.jsx、separated.jsx、single.jsx。这三个函数getSpacingPresetCssVar、isValueSpacingPreset、getCustomValueFromPreset同时通过 components/index.js 作为独立工具导出供外部复用。预设数量决定交互形态底层输入控件由 spacing-input-control.jsx 承载它复用PresetInputControl的能力预设较少时≤ 8 个以 RangeControl 滑杆呈现每个预设对应一个档位预设较多时自动切换为下拉选择CustomSelectControl。这一行为有明确的测试佐证在 test/index.jsdom.test.jsx 的 Large Preset Sets 分组中模拟 15 个预设后断言页面不再出现slider而是渲染出 2 个combobox轴向视图下的垂直/水平两个下拉。同时useSelectProp 可强制使用下拉形态。自定义数值与单位支持除预设档位外用户还可以通过 Set custom value 开关切换到底层数值输入spinbutton。此时由 spacing-input-control.jsx 中的CUSTOM_VALUE_SETTINGS约束各单位的取值范围与步进单位最大值步进px3001%/vw/vh/svw/lvw/dvw/svh/lvh/dvh/vi/svi/lvi/dvi/vb/svb/lvb/dvb/vmin/svmin/lvmin/dvmin/vmax/svmax/lvmax/dvmax1001em/rm100.1可用单位列表来自编辑器设置spacing.units通过useSettings读取未配置时回退为[px, em, rem]。此外spacing-input-control还会通过useSelect读取编辑器设置中的disableCustomSpacingSizes为true时彻底禁用自定义数值输入仅保留预设档位。测试同样覆盖了minimumCustomValue对min属性的约束min10。在区块编辑器中的真实使用场景SpacingSizesControl并非孤立组件它是全局样式Global Styles面板中间距控制的主要 UI。在 dimensions-panel.jsx 中它被用于Padding内边距values{ paddingValues }、onChange{ setPaddingValues }、label{ __( Padding ) }Margin外边距额外传入minimumCustomValue{ -Infinity }以允许负值Block spacing块间距 / gap通过key{ isAxialGap ? axial-gap : single-gap }在轴向与单边形态间切换min{ 0 }。值得注意的是该面板会将本地覆盖值与继承值合并后再传给values因为预设滑杆没有 placeholder 插槽激活的档位本身即静止状态的视觉提示见 dimensions-panel.jsx 中关于paddingValues、gapRawForDisplay的注释。这为在自有扩展中接入该组件提供了正确的数据流参考传入的values应当是完整的四方向对象且优先传入预设格式的值以获得档位高亮与规范化存储的双重收益。无障碍与测试保障组件在无障碍方面做了体系化设计根元素为fieldsetlegend配合BaseControl.VisualLabel使整组控件形成可被屏幕阅读器识别的分组语义rolegroup每个方向控件的 aria-label 由方向 类型拼接生成例如轴向视图下为 Vertical padding / Horizontal padding单边模式下为 Top padding通过_x( %1$s %2$s, spacing )翻译见 spacing-input-control.jsxshowSideInLabel{ false }可隐藏标签中的方向后缀用于减少冗长标签的场景。测试覆盖同样完备test/index.jsdom.test.jsx1098 行涵盖基础渲染、轴向/自定义值变更、单边配置、预设功能、大规模预设集、边界情况undefined、空对象、部分对象、clamp()等复杂 CSS 值、非法输入、零值、附加 PropsminimumCustomValue、onMouseOver/Out、inputProps、useSelect、主题预设集成与无障碍标签test/select.browser.test.js 则针对浏览器环境下预设下拉的交互行为做补充验证。小结SpacingSizesControl是一个将预设档位选择与自由数值输入有机结合的间距控件三视图模式Single / Axial / Custom配合自动初始视图判定让不同数据形态都能获得最合适的编辑界面以var:preset|spacing|slug为核心的预设值体系保证了 UI 档位、存储值与最终 CSS 变量之间的无损双向转换而预设数量阈值8 个驱动的滑杆/下拉形态切换则为预设规模不同的主题提供了统一的交互体验。若你的自定义区块或面板需要一套与 Gutenberg 全局样式一致的间距编辑体验直接复用__experimentalSpacingSizesControl并将值按预设格式规范化存储是最贴近原生行为的接入方式。参考源码路径组件入口index.jsx工具函数与常量utils.js预设数据 Hookuse-spacing-sizes.js三种视图实现axial.jsx、separated.jsx、single.jsx底层输入控件spacing-input-control.jsx链接/取消链接按钮linked-button.jsx测试index.jsdom.test.jsx、select.browser.test.js实际调用场景dimensions-panel.jsx包级导出components/index.js【免费下载链接】gutenbergThe Block Editor project for WordPress and beyond. Plugin is available from the official repository.项目地址: https://gitcode.com/GitHub_Trending/gu/gutenberg创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考