云策 WordPress 开发者社区

块编辑器开发文档

ToggleControl

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

概述

ToggleControl 是 WordPress 组件库中的一个 React 组件，用于生成切换开关用户界面，常用于控制布尔状态设置。它支持标签、帮助文本、禁用状态等属性，便于在 Gutenberg 编辑器或自定义块中集成。

关键要点

  • ToggleControl 用于创建切换开关 UI，基于 React 状态管理布尔值。
  • 支持 props 包括 label（标签）、help（帮助文本）、checked（选中状态）、disabled（禁用状态）、onChange（变化回调函数）和 className（自定义类名）。
  • help 属性可以是字符串、元素或函数，允许动态生成帮助文本。
  • checked 属性控制开关状态，未传递时组件为不受控状态，初始值为 false。

代码示例

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

const MyToggleControl = () => {
    const [ hasFixedBackground, setHasFixedBackground ] = useState( false );

    return (
        <ToggleControl
            label="Fixed Background"
            help={
                hasFixedBackground
                    ? 'Has fixed background.'
                    : 'No fixed background.'
            }
            checked={ hasFixedBackground }
            onChange={ (newValue) => {
                setHasFixedBackground( newValue );
            } }
        />
    );
};

注意事项

  • ToggleControl 是受控组件，需通过 checked 和 onChange 管理状态；若未传递 checked，则作为不受控组件处理。
  • 使用 help 属性时，可传入函数根据 checked 参数动态返回文本，增强用户体验。
  • className 属性会添加到包装 div 的类中，默认包含 components-base-control 和 components-toggle-control。
📄 原文内容

ToggleControl is used to generate a toggle user interface.

Usage

Render a user interface to change fixed background setting.

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

const MyToggleControl = () => {
    const [ hasFixedBackground, setHasFixedBackground ] = useState( false );

    return (
        <ToggleControl
            label="Fixed Background"
            help={
                hasFixedBackground
                    ? 'Has fixed background.'
                    : 'No fixed background.'
            }
            checked={ hasFixedBackground }
            onChange={ (newValue) => {
                setHasFixedBackground( newValue );
            } }
        />
    );
};

Props

The component accepts the following props:

label

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

  • Type: String
  • Required: No

help

If this property is added, a help text will be generated using help property as the content.
For controlled components the help prop can also be a function which will return a help text
dynamically depending on the boolean checked parameter.

  • Type: String|Element|Function
  • Required: No

checked

If checked is true the toggle will be checked. If checked is false the toggle will be unchecked.
If no value is passed the toggle will be an uncontrolled component with unchecked initial value.

  • Type: Boolean
  • Required: No

disabled

If disabled is true the toggle will be disabled and apply the appropriate styles.

  • Type: Boolean
  • Required: No

onChange

A function that receives the checked state (boolean) as input.

  • Type: function
  • Required: No

className

The class that will be added with components-base-control and components-toggle-control to the classes of the wrapper div. If no className is passed only components-base-control and components-toggle-control are used.

  • Type: String
  • Required: No