云策 WordPress 开发者社区

块编辑器开发文档

WithConstrainedTabbing

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

概述

withConstrainedTabbing 是一个 React 高阶组件，用于在组件内限制 Tab 键的键盘导航，常用于模态对话框等需要提升可访问性的 UI 场景。建议仅在已实现其他方式（如 Escape 键或“关闭”按钮）退出限制时使用。

关键要点

  • withConstrainedTabbing 是一个高阶组件，用于约束 Tab 键导航，增强可访问性。
  • 适用于模态对话框等 UI 组件，确保键盘焦点保持在组件内部。
  • 使用时必须提供退出限制的机制，例如 Escape 键或特定 UI 控件。

代码示例

import { useState } from 'react';
import {
    withConstrainedTabbing,
    TextControl,
    Button,
} from '@wordpress/components';

const ConstrainedTabbing = withConstrainedTabbing(
    ( { children } ) => children
);

const MyComponentWithConstrainedTabbing = () => {
    const [ isConstrainedTabbing, setIsConstrainedTabbing ] = useState( false );
    let form = (
        <form>
            <TextControl
                __next40pxDefaultSize
                label="Input 1"
                onChange={ () => {} }
            />
            <TextControl
                __next40pxDefaultSize
                label="Input 2"
                onChange={ () => {} }
            />
        </form>
    );
    if ( isConstrainedTabbing ) {
        form = <ConstrainedTabbing>{ form }</ConstrainedTabbing>;
    }

    const toggleConstrain = () => {
        setIsConstrainedTabbing( ( state ) => ! state );
    };

    return (
        <div>
            { form }
            <Button variant="secondary" onClick={ toggleConstrain }>
                { isConstrainedTabbing ? 'Disable' : 'Enable' } constrain
                tabbing
            </Button>
        </div>
    );
};

注意事项

确保在使用 withConstrainedTabbing 时，组件提供了明确的退出方式，以避免键盘焦点被永久限制。

📄 原文内容

withConstrainedTabbing is a React higher-order component adding the ability to constrain keyboard navigation with the Tab key within a component. For accessibility reasons, some UI components need to constrain Tab navigation, for example modal dialogs or similar UI. Use of this component is recommended only in cases where a way to navigate away from the wrapped component is implemented by other means, usually by pressing the Escape key or using a specific UI control, e.g. a “Close” button.

Usage

Wrap your original component with withConstrainedTabbing.

import { useState } from 'react';
import {
    withConstrainedTabbing,
    TextControl,
    Button,
} from '@wordpress/components';

const ConstrainedTabbing = withConstrainedTabbing(
    ( { children } ) => children
);

const MyComponentWithConstrainedTabbing = () => {
    const [ isConstrainedTabbing, setIsConstrainedTabbing ] = useState( false );
    let form = (
        <form>
            <TextControl
                __next40pxDefaultSize
                label="Input 1"
                onChange={ () => {} }
            />
            <TextControl
                __next40pxDefaultSize
                label="Input 2"
                onChange={ () => {} }
            />
        </form>
    );
    if ( isConstrainedTabbing ) {
        form = <ConstrainedTabbing>{ form }</ConstrainedTabbing>;
    }

    const toggleConstrain = () => {
        setIsConstrainedTabbing( ( state ) => ! state );
    };

    return (
        <div>
            { form }
            <Button variant="secondary" onClick={ toggleConstrain }>
                { isConstrainedTabbing ? 'Disable' : 'Enable' } constrain
                tabbing
            </Button>
        </div>
    );
};