云策 WordPress 开发者社区

块编辑器开发文档

ToggleGroupControl

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

概述

ToggleGroupControl 是一个实验性的表单组件，用于让用户从水平分段选项中选择单一持久值，类似于单选按钮组。它适用于标签不会换行的场景，若标签较长可考虑使用 SelectControl 或 CustomSelectControl。

关键要点

  • 组件为实验性功能，可能发生重大变更，使用时需注意兼容性。
  • 用于选择单一值，若需切换视图应使用 TabPanel。
  • 通过 ToggleGroupControlOption 组件渲染选项，支持导入自 @wordpress/components。
  • 提供多种 Props 如 label、value、onChange、isBlock 等，用于自定义行为和样式。

代码示例

import {
    __experimentalToggleGroupControl as ToggleGroupControl,
    __experimentalToggleGroupControlOption as ToggleGroupControlOption,
} from '@wordpress/components';

function Example() {
    return (
        <ToggleGroupControl
            label="my label"
            value="vertical"
            isBlock
            __next40pxDefaultSize
        >
            <ToggleGroupControlOption value="horizontal" label="Horizontal" />
            <ToggleGroupControlOption value="vertical" label="Vertical" />
        </ToggleGroupControl>
    );
}

注意事项

  • 仅当选项标签确定不会换行时使用此控件，否则考虑其他组件如 SelectControl。
  • Props 如 hideLabelFromVision、isAdaptiveWidth、isDeselectable 等提供了额外配置选项，需根据需求设置。
📄 原文内容
This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.

ToggleGroupControl is a form component that lets users choose options represented in horizontal segments. To render options for this control use ToggleGroupControlOption component.

This component is intended for selecting a single persistent value from a set of options, similar to a how a radio button group would work. If you simply want a toggle to switch between views, use a TabPanel instead.

Only use this control when you know for sure the labels of items inside won’t wrap. For items with longer labels, you can consider a SelectControl or a CustomSelectControl component instead.

Usage

import {
    __experimentalToggleGroupControl as ToggleGroupControl,
    __experimentalToggleGroupControlOption as ToggleGroupControlOption,
} from '@wordpress/components';

function Example() {
    return (
        <ToggleGroupControl
            label="my label"
            value="vertical"
            isBlock
            __next40pxDefaultSize
        >
            <ToggleGroupControlOption value="horizontal" label="Horizontal" />
            <ToggleGroupControlOption value="vertical" label="Vertical" />
        </ToggleGroupControl>
    );
}

Props

help: ReactNode

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

  • Required: No

hideLabelFromVision: boolean

If true, the label will only be visible to screen readers.

  • Required: No
  • Default: false

isAdaptiveWidth: boolean

Determines if segments should be rendered with equal widths.

  • Required: No
  • Default: false

isDeselectable: boolean

Whether an option can be deselected by clicking it again.

  • Required: No
  • Default: false

isBlock: boolean

Renders ToggleGroupControl as a (CSS) block element, spanning the entire width of the available space. This is the recommended style when the options are text-based and not icons.

  • Required: No
  • Default: false

label: string

Label for the form element.

  • Required: Yes

onChange: ( value?: string | number ) => void

Callback when a segment is selected.

  • Required: No
  • Default: () => {}

value: string | number

The value of the ToggleGroupControl.

  • 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