RangeControls 用于从一系列增量值中进行选择。

一个音量 RangeControl

设计指南

结构

RangeControl 可以包含以下元素：

  1. Rail（滑轨）：滑轨代表滑块的全部表面积，从用户可选择的最小值到最大值。对于从左到右（LTR）的语言，最小值显示在最左侧，最大值显示在最右侧。对于从右到左（RTL）的语言，此方向相反，最小值显示在最右侧，最大值显示在最左侧。
  2. Track（轨道）：轨道代表从最小值到当前选中值的滑轨部分。
  3. Thumb（滑块手柄）：滑块手柄沿轨道滑动，通过其位置显示选中的值。
  4. Value entry field（数值输入框）：数值输入框显示当前选中的具体数值。
  5. Icon（图标）（可选）：可以在滑块之前或之后显示图标。
  6. Tick mark（刻度标记）（可选）：刻度标记代表用户可以移动滑块到的预定值。

类型

连续滑块

连续滑块允许用户在一个主观范围内选择一个值。它们不显示选中的数值。在显示/编辑数值不重要时使用，例如音量。

离散滑块

离散滑块可以通过引用其数值输入框来调整到特定值。在需要显示/编辑数值时使用，例如文本大小。

可能的选择可以通过使用刻度标记来组织，滑块手柄会吸附到这些刻度标记上（或者输入值会四舍五入到这些刻度标记上）。

行为

  • Click and drag（点击并拖拽）：通过点击滑块手柄并拖拽来控制滑块。
  • Click jump（点击跳转）：通过点击轨道来控制滑块。
  • Click and arrow（点击并使用方向键）：通过点击滑块手柄，然后使用方向键移动它来控制滑块。
  • Tab and arrow（Tab 键并使用方向键）：通过使用 Tab 键选择所需滑块的滑块手柄，然后使用方向键移动它来控制滑块。
  • Value entry field（数值输入框）：离散滑块具有数值输入框。输入文本后，滑块位置会自动更新以反映新值。
  • Tick marks（刻度标记）（可选）离散滑块可以在滑块轨道上使用均匀分布的刻度标记，并且滑块手柄会吸附到它们。每个刻度标记应以用户可察觉的增量改变设置。

用法

RangeControls 沿轨道反映一系列值，用户可以从中选择一个单一值。它们非常适合调整音量、透明度或文本大小等设置。

RangeControls 可以在轨道的两端带有反映一系列值的图标。

即时效果

使用 RangeControls 进行的更改是即时的，允许用户进行调整直到找到他们的偏好。它们不应与提供反馈有延迟的设置配对。

一个需要保存操作的 RangeControl

不要
如果效果不是即时的，请不要使用 RangeControls。

当前状态

RangeControls 反映它们所控制设置的当前状态。

值

范围控制

一个具有可编辑数值的 RangeControl

Editable numeric values（可编辑数值）：可编辑数值允许用户设置 RangeControl 的确切值。设置值后，滑块手柄位置会立即更新以匹配新值。

一个只有两个值的 RangeControl

不要
RangeControls 仅应用于从一系列值中选择（例如，如果只有 2 个值，请不要使用 RangeControl）。

范围控制

不要
RangeControls 应提供用户可供选择的所有范围（例如，不要禁用 RangeControl 的一部分）。

开发指南

用法

渲染 RangeControl 以从一系列增量值中进行选择。

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

const MyRangeControl = () => {
    const [ columns, setColumns ] = useState( 2 );

    return (
        <RangeControl
            label="Columns"
            value={ columns }
            onChange={ ( value ) => setColumns( value ) }
            min={ 2 }
            max={ 10 }
        />
    );
};

Props

组件接受的 props 集合将在下面指定。
未包含在此集合中的 props 将应用于输入元素。

afterIcon: string|Function|Component|null

如果添加了此属性，将在滑块之后渲染一个 Icon component，其图标等于 afterIcon。

有关 IconType 的更多信息，请参阅 Icon component。

  • Required: No
  • Platform: Web

allowReset: boolean

如果此属性为 true，则渲染一个重置滑块的按钮。

  • Required: No
  • Default: false
  • Platform: Web | Mobile

beforeIcon: string|Function|Component|null

如果添加了此属性，将在滑块之前渲染一个 Icon component，其图标等于 beforeIcon。

有关 IconType 的更多信息，请参阅 Icon component。

  • Required: No
  • Platform: Web

color: CSSProperties[‘color’]

RangeControl 包装器的 CSS 颜色字符串。

  • Required: No
  • Platform: Web

currentInput: number

当 value 当前为 undefined 时用作回退的当前输入。

  • Required: No
  • Platform: Web

disabled: boolean

禁用 input，防止应用新值。

  • Required: No
  • Platform: Web

help: string|Element

如果添加了此属性，将使用 help 属性作为内容生成帮助文本。

  • Required: No
  • Platform: Web

hideLabelFromVision: boolean

控制标签是否仅对屏幕阅读器可见。

  • Required: No

icon: string

要在滑块旁边及其容器标题上方显示的图标。

  • Required: No
  • Platform: Mobile

initialPosition: number

滑块起始位置，在未传递 value 时使用。initialPosition 将被限制在提供的 min 和 max prop 值之间。

  • Required: No
  • Platform: Web | Mobile

isShiftStepEnabled: boolean

作为 prop 传递给 NumberControl 组件，仅当 withInputField 为 true 时适用。如果为 true，当数字输入获得焦点时，按下 UP 或 DOWN 以及 SHIFT 键将使值更改 shiftStep 的值。

  • Required: No

label: string

如果添加了此属性，将使用 label 属性作为内容生成标签。

  • Required: No
  • Platform: Web | Mobile

marks: Array|boolean

渲染 step 刻度的视觉表示。可以通过 Array 提供自定义刻度指示器。

示例：

const marks = [
    {
        value: 0,
        label: '0',
    },
    {
        value: 1,
        label: '1',
    },
    {
        value: 8,
        label: '8',
    },
    {
        value: 10,
        label: '10',
    },
];

const MyRangeControl() {
    return ( <RangeControl marks={ marks } min={ 0 } max={ 10 } step={ 1 } /> )
}
  • Required: No
  • Platform: Web

onBlur: FocusEventHandler< HTMLInputElement >

当 RangeControl 输入失去焦点时的回调。

  • Required: No
  • Platform: Web

onChange: ( value?: number ) => void

接收新值的函数。除非发生重置（由 allowReset 启用），否则该值将小于 max 且大于 min。在这种情况下，该值将是 resetFallbackValue 的值（如果已指定），否则为 undefined。

  • Required: No
  • Platform: Web | Mobile

onFocus: FocusEventHandler< HTMLInputElement >

当 RangeControl 输入获得焦点时的回调。

  • Required: No
  • Platform: Web

onMouseLeave: MouseEventHandler< HTMLInputElement >

当鼠标退出 RangeControl 时的回调。

  • Required: No
  • Platform: Web

onMouseMove: MouseEventHandler< HTMLInputElement >

当鼠标在 RangeControl 内移动时的回调函数。

  • 是否必需：否
  • 平台：Web

min: number

允许的 value 最小值。

  • 是否必需：否
  • 默认值：0
  • 平台：Web | Mobile

max: number

允许的 value 最大值。

  • 是否必需：否
  • 默认值：100
  • 平台：Web | Mobile

railColor: CSSProperties[ ‘color’ ]

用于自定义轨道元素背景的 CSS 颜色字符串。

  • 是否必需：否
  • 平台：Web

renderTooltipContent: ( value ) => value

一种自定义渲染的数值 UI 的方法。示例：

const customTooltipContent = value => `${value}%`

const MyRangeControl() {
    return (<RangeControl renderTooltipContent={ customTooltipContent } />)
}
  • 是否必需：否
  • 平台：Web

resetFallbackValue: number

如果点击重置按钮（由 allowReset 启用），则恢复到的值。

  • 是否必需：否
  • 平台：Web

separatorType: ‘none’ | ‘fullWidth’ | ‘topFullWidth’

定义控件行下方/上方的分隔线是否应禁用或全宽显示。默认情况下，它位于下方，且不包含下划线以覆盖控件图标。

  • 是否必需：否
  • 平台：Mobile

shiftStep: number

作为属性传递给 NumberControl 组件，仅当 withInputField 和 isShiftStepEnabled 均为 true 且数字输入框处于焦点状态时适用。它是 step 的乘数。

  • 是否必需：否

showTooltip: boolean

强制显示或隐藏提示框 UI。当 step 设置为特殊字符串值 any 时，此值会被覆盖为 false。

  • 是否必需：否
  • 平台：Web

step: number | ‘any’

value 变化的最小幅度。它在验证中也是一个因素，因为 value 必须是 step 的倍数（偏移量为 min）才有效。接受特殊字符串值 any，该值会取消验证约束，并将 withInputField 和 showTooltip 属性覆盖为 false。

  • 是否必需：否
  • 平台：Web

trackColor: CSSProperties[ ‘color’ ]

用于自定义轨道元素背景的 CSS 颜色字符串。

  • 是否必需：否
  • 平台：Web

type: string

定义在移动端的底部工作表中，值选择是显示步进器控件还是滑块控件。要使用步进器，请将 type 值设置为 stepper。如果未提供选项，则默认为滑块。

  • 是否必需：否
  • 平台：Mobile

value: number

范围滑块的当前值。

  • 是否必需：否
  • 平台：Web | Mobile

withInputField: boolean

确定是否在 RangeControl 旁边渲染 input 数字字段。当 step 设置为特殊字符串值 any 时，此值会被覆盖为 false。

  • 是否必需：否
  • 平台：Web

相关组件

  • 要在文本字段中收集数值输入，请使用 TextControl 组件。