云策 WordPress 开发者社区

块编辑器开发文档

BoxControl

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

概述

BoxControl 是一个 WordPress 组件，允许用户设置上、右、下、左四个方向的值，常用于处理如内边距或外边距等 CSS 属性。它提供灵活的配置选项，包括预设、单位控制和轴拆分功能。

关键要点

  • BoxControl 用于输入上、右、下、左四个方向的数值，支持 CSS 单位（如 px、%）。
  • 组件提供多种 Props，如 __next40pxDefaultSize、allowReset、sides、splitOnAxis 等，以定制行为和外观。
  • 可通过 onChange 回调函数处理值变化，并支持预设值和重置功能。
  • 适用于 React 环境，需从 @wordpress/components 导入。

代码示例

import { useState } from 'react';
import { BoxControl } from '@wordpress/components';

function Example() {
  const [ values, setValues ] = useState( {
    top: '50px',
    left: '10%',
    right: '10%',
    bottom: '50px',
  } );

  return (
    <BoxControl
      __next40pxDefaultSize
      values={ values }
      onChange={ setValues }
    />
  );
};

注意事项

  • 使用 presets 时，必须提供 presetKey 以应用预设值。
  • sides 属性可限制可控制的方向，例如仅允许水平或垂直调整。
  • splitOnAxis 设置为 true 时，在未链接状态下可使用垂直和水平控制替代单独方向调整。
📄 原文内容

See the WordPress Storybook for more detailed, interactive documentation.

A control that lets users set values for top, right, bottom, and left. Can be
used as an input control for values like padding or margin.

import { useState } from 'react';
import { BoxControl } from '@wordpress/components';

function Example() {
  const [ values, setValues ] = useState( {
    top: '50px',
    left: '10%',
    right: '10%',
    bottom: '50px',
  } );

  return (
    <BoxControl
      __next40pxDefaultSize
      values={ values }
      onChange={ setValues }
    />
  );
};

Props

__next40pxDefaultSize

  • Type: boolean
  • Required: No
  • Default: false

Start opting into the larger default height that will become the default size in a future version.

allowReset

  • Type: boolean
  • Required: No
  • Default: true

If this property is true, a button to reset the box control is rendered.

id

  • Type: string
  • Required: No

The id to use as a base for the unique HTML id attribute of the control.

inputProps

  • Type: UnitControlPassthroughProps
  • Required: No
  • Default: {<br />
    min: 0,<br />
    }

Props for the internal UnitControl components.

label

  • Type: string
  • Required: No
  • Default: __( 'Box Control' )

Heading label for the control.

onChange

  • Type: (next: BoxControlValue) => void
  • Required: No
  • Default: () => {}

A callback function when an input value changes.

presets

  • Type: Preset[]
  • Required: No

Available presets to pick from.

presetKey

  • Type: string
  • Required: No

The key of the preset to apply.
If you provide a list of presets, you must provide a preset key to use.
The format of preset selected values is going to be var:preset|${ presetKey }|${ presetSlug }

resetValues

  • Type: BoxControlValue
  • Required: No
  • Default: {<br />
    top: undefined,<br />
    right: undefined,<br />
    bottom: undefined,<br />
    left: undefined,<br />
    }

The top, right, bottom, and left box dimension values to use when the control is reset.

sides

  • Type: readonly (keyof BoxControlValue | "horizontal" | "vertical")[]
  • Required: No

Collection of sides to allow control of. If omitted or empty, all sides will be available.

Allowed values are “top”, “right”, “bottom”, “left”, “vertical”, and “horizontal”.

splitOnAxis

  • Type: boolean
  • Required: No
  • Default: false

If this property is true, when the box control is unlinked, vertical and horizontal controls
can be used instead of updating individual sides.

units

  • Type: WPUnitControlUnit[]
  • Required: No
  • Default: CSS_UNITS

Available units to select from.

values

  • Type: BoxControlValue
  • Required: No

The current values of the control, expressed as an object of top, right, bottom, and left values.