云策 WordPress 开发者社区

块编辑器开发文档

UnitControl

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

概述

UnitControl 是一个实验性的 WordPress 组件，允许用户设置数值和单位（如 px）。它主要用于处理带单位的数值输入，支持自定义单位列表和回调函数。

关键要点

  • UnitControl 是实验性功能，可能发生重大变更
  • 支持数值和单位输入，单位可通过下拉选择
  • 提供多种 Props 控制行为，如禁用单位选择、回车触发 onChange 等
  • 可通过 units 属性定义可用单位列表，支持默认值设置
  • value 属性可接受数字或字符串，字符串会自动推断单位
  • __next40pxDefaultSize 属性用于启用未来版本的默认高度

代码示例

import { useState } from 'react';
import { __experimentalUnitControl as UnitControl } from '@wordpress/components';

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

    const units = [
        { value: 'px', label: 'px', default: 0 },
        { value: '%', label: '%', default: 10 },
        { value: 'em', label: 'em', default: 0 },
    ];

    return (
        <UnitControl __next40pxDefaultSize onChange={ setValue } value={ value } units={ units } />
    );
};

注意事项

  • unit 属性已弃用，建议通过 value 属性提供带单位的值
  • isResetValueOnUnitChange 为 true 时，切换单位会设置为默认值，适用于避免单位变更导致剧烈变化的场景
📄 原文内容
This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.

UnitControl allows the user to set a numeric quantity as well as a unit (e.g. px).

Usage

import { useState } from 'react';
import { __experimentalUnitControl as UnitControl } from '@wordpress/components';

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

    return <UnitControl __next40pxDefaultSize onChange={ setValue } value={ value } />;
};

Props

disableUnits: boolean

If true, the unit <select> is hidden.

  • Required: No
  • Default: false

isPressEnterToChange: boolean

If true, the ENTER key press is required in order to trigger an onChange. If enabled, a change is also triggered when tabbing away (onBlur).

  • Required: No
  • Default: false

isResetValueOnUnitChange: boolean

If true, and the selected unit provides a default value, this value is set when changing units.

  • Required: No
  • Default: false

isUnitSelectTabbable: boolean

Determines if the unit <select> is tabbable.

  • Required: No
  • Default: true

label: string

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

  • Required: No

labelPosition: string

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

  • Required: No

onBlur: FocusEventHandler< HTMLInputElement | HTMLSelectElement >

Callback invoked when either the quantity or unit inputs fire the blur event.

  • Required: No

onFocus: FocusEventHandler< HTMLInputElement | HTMLSelectElement >

Callback invoked when either the quantity or unit inputs fire the focus event.

  • Required: No

onChange: UnitControlOnChangeCallback

Callback when the value changes.

  • Required: No

onUnitChange: UnitControlOnChangeCallback

Callback when the unit changes.

  • Required: No

size: string

Adjusts the size of the input.
Sizes include: default, small

  • Required: No
  • Default: default

unit: string

Deprecated: Current unit value.
Instead, provide a unit with a value through the value prop.

Example:

<UnitControl value="50%" />
  • Required: No

units: WPUnitControlUnit[]

Collection of available units.

  • Required: No

Example:

import { useState } from 'react';
import { __experimentalUnitControl as UnitControl } from '@wordpress/components';

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

    const units = [
        { value: 'px', label: 'px', default: 0 },
        { value: '%', label: '%', default: 10 },
        { value: 'em', label: 'em', default: 0 },
    ];

    return (
        <UnitControl __next40pxDefaultSize onChange={ setValue } value={ value } units={ units } />
    );
};

A default value (in the example above, 10 for %), if defined, is set as the new value when a unit changes. This is helpful in scenarios where changing a unit may cause drastic results, such as changing from px to vh.

value: number | string

Current value. If passed as a string, the current unit will be inferred from this value.
For example, a value of 50% will set the current unit to %.

Example:

<UnitControl __next40pxDefaultSize value="50%" />
  • Required: No

__next40pxDefaultSize: boolean

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

  • Required: No
  • Default: false