云策 WordPress 开发者社区

块编辑器开发文档

NumberControl

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

概述

NumberControl 是一个增强的 HTML input[type="number"] 组件，用于在 WordPress 中处理数字输入。该组件目前处于实验阶段，可能发生重大变更。

关键要点

  • NumberControl 提供拖拽、键盘快捷键和自定义步进控制等功能，增强用户体验。
  • 支持多种配置选项，如 dragDirection、spinControls、isShiftStepEnabled 等，以灵活调整行为。
  • onChange 回调函数接收新值和额外事件信息，需注意验证输入值的有效性。

代码示例

import { __experimentalNumberControl as NumberControl } from '@wordpress/components';

const Example = () => {
    const [ value, setValue ] = useState( 10 );

    return (
        <NumberControl
            __next40pxDefaultSize
            isShiftStepEnabled={ true }
            onChange={ setValue }
            shiftStep={ 10 }
            value={ value }
        />
    );
};

注意事项

  • 该组件为实验性功能，API 可能不稳定，使用时需谨慎。
  • onChange 回调中的值可能无效，建议通过 event.target?.validity.valid 进行验证。
  • step 属性可设置为 "any" 以绕过验证约束，步进时默认增量为 1。
📄 原文内容
This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.

NumberControl is an enhanced HTML input[type="number"] element.

Usage

import { __experimentalNumberControl as NumberControl } from '@wordpress/components';

const Example = () => {
    const [ value, setValue ] = useState( 10 );

    return (
        <NumberControl
            __next40pxDefaultSize
            isShiftStepEnabled={ true }
            onChange={ setValue }
            shiftStep={ 10 }
            value={ value }
        />
    );
};

Props

dragDirection

Determines the drag axis to increment/decrement the value.
Directions: n | e | s | w

  • Type: String
  • Required: No
  • Default: n

dragThreshold

If isDragEnabled is true, this controls the amount of px to have been dragged before the value changes.

  • Type: Number
  • Required: No
  • Default: 10

spinControls

The type of spin controls to display. These are buttons that allow the user to
quickly increment and decrement the number.

  • ‘none’ – Do not show spin controls.
  • ‘native’ – Use browser’s native HTML input controls.
  • ‘custom’ – Use plus and minus icon buttons.
    • Type: String
    • Required: No
    • Default: 'native'

isDragEnabled

If true, enables mouse drag gesture to increment/decrement the number value. Holding SHIFT while dragging will increase the value by the shiftStep.

  • Type: Boolean
  • Required: No

isShiftStepEnabled

If true, pressing UP or DOWN along with the SHIFT key will increment the value by the shiftStep value.

  • Type: Boolean
  • Required: No
  • Default: true

label

If this property is added, a label will be generated using label property as the content.

  • Type: String
  • Required: No

labelPosition

The position of the label (top, side, bottom, or edge).

  • Type: String
  • Required: No

max

The maximum value allowed.

  • Type: Number
  • Required: No
  • Default: Infinity

min

The minimum value allowed.

  • Type: Number
  • Required: No
  • Default: -Infinity

onChange

Callback fired whenever the value of the input changes.

The callback receives two arguments:

  1. newValue: the new value of the input
  2. extra: an object containing, under the event key, the original browser event.

Note that the value received as the first argument of the callback is not guaranteed to be a valid value (e.g. it could be outside of the range defined by the [min, max] props, or it could not match the step). In order to check the value’s validity, check the event.target?.validity.valid property from the callback’s second argument.

  • Type: (newValue, extra) => void
  • Required: No

required

If true enforces a valid number within the control’s min/max range. If false allows an empty string as a valid value.

  • Type: Boolean
  • Required: No
  • Default: false

shiftStep

Amount to increment by when the SHIFT key is held down. This shift value is a multiplier to the step value. For example, if the step value is 5, and shiftStep is 10, each jump would increment/decrement by 50.

  • Type: Number
  • Required: No
  • Default: 10

step

Amount by which the value is changed when incrementing/decrementing. It is also a factor in validation as value must be a multiple of step (offset by min, if specified) to be valid. Accepts the special string value any that voids the validation constraint and causes stepping actions to increment/decrement by 1.

  • Type: Number | "any"
  • Required: No
  • Default: 1

__next40pxDefaultSize

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

  • Type: Boolean
  • Required: No
  • Default: false