焦点陷阱

焦点陷阱组件阻止用户的焦点逃离其子组件。

介绍

焦点陷阱是一个实用工具组件，在实现覆盖层（例如模态对话框）时非常有用，模态对话框应在打开时阻止其外部的所有交互。

组件

import { FocusTrap } from '@mui/base/FocusTrap';

焦点陷阱包裹着应该保持用户焦点的 UI 元素。例如，如果焦点需要保持在菜单内部，则组件的结构将如下所示

<FocusTrap>
  <Menu>
    <MenuItem>{/* item one */}</MenuItem>
    <MenuItem>{/* item two */}</MenuItem>
  </Menu>
</FocusTrap>

以下演示展示了一个<button>，它打开一个嵌套在焦点陷阱内部的Box组件。只要 Box 是打开的，用户的键盘就无法与应用程序的其他部分进行交互。按下打开按钮，然后使用 Tab 键移动焦点——请注意，焦点不会离开 Box

<button type="button" onClick={() => setOpen(true)}>
  Open
</button>
{open && (
  <FocusTrap open>
    <Box tabIndex={-1} sx={{ mt: 1, p: 1 }}>
      <label>
        First name: <input type="text" />
      </label>
      <br />
      <button type="button" onClick={() => setOpen(false)}>
        Close
      </button>
    </Box>
  </FocusTrap>
)}

<button type="button" onClick={() => setOpen(true)}>
  Open
</button>
{open && (
  <FocusTrap open>
    <Box tabIndex={-1} sx={{ mt: 1, p: 1 }}>
      <label>
        First name: <input type="text" />
      </label>
      <br />
      <button type="button" onClick={() => setOpen(false)}>
        Close
      </button>
    </Box>
  </FocusTrap>
)}

按 Enter 键开始编辑

自定义

禁用强制焦点

默认情况下，外部的点击焦点陷阱组件会被阻止。

您可以使用 disableEnforceFocus prop 禁用此行为。

比较以下演示与组件部分中的演示——请注意，该演示阻止您点击外部区域，而这个演示允许您点击外部区域

<button type="button" onClick={() => setOpen(true)}>
  Open
</button>
{open && (
  <FocusTrap disableEnforceFocus open>
    <Box tabIndex={-1} sx={{ mt: 1, p: 1 }}>
      <label>
        First name: <input type="text" />
      </label>
      <br />
      <button type="button" onClick={() => setOpen(false)}>
        Close
      </button>
    </Box>
  </FocusTrap>
)}

<button type="button" onClick={() => setOpen(true)}>
  Open
</button>
{open && (
  <FocusTrap disableEnforceFocus open>
    <Box tabIndex={-1} sx={{ mt: 1, p: 1 }}>
      <label>
        First name: <input type="text" />
      </label>
      <br />
      <button type="button" onClick={() => setOpen(false)}>
        Close
      </button>
    </Box>
  </FocusTrap>
)}

按 Enter 键开始编辑

延迟激活

默认情况下，当 open prop 存在时，焦点陷阱组件会自动将焦点移动到其第一个子元素。

您可以使用 disableAutoFocus prop 禁用此行为并使其延迟激活。当自动焦点被禁用时（如下面的演示中所示），组件仅在用户将焦点移动到那里后才捕获焦点

<button type="button" onClick={() => setOpen(true)}>
  Open
</button>
{open && (
  <FocusTrap open disableAutoFocus>
    <Box tabIndex={-1} sx={{ mt: 1, p: 1 }}>
      <label>
        First name: <input type="text" />
      </label>
      <br />
      <button type="button" onClick={() => setOpen(false)}>
        Close
      </button>
    </Box>
  </FocusTrap>
)}

<button type="button" onClick={() => setOpen(true)}>
  Open
</button>
{open && (
  <FocusTrap open disableAutoFocus>
    <Box tabIndex={-1} sx={{ mt: 1, p: 1 }}>
      <label>
        First name: <input type="text" />
      </label>
      <br />
      <button type="button" onClick={() => setOpen(false)}>
        Close
      </button>
    </Box>
  </FocusTrap>
)}

按 Enter 键开始编辑

跳出焦点循环

以下演示使用 Portal 组件将焦点陷阱子组件的子集渲染到当前 DOM 层次结构之外的新“子树”中，因此它们不再是焦点循环的一部分

在陷阱内使用切换

焦点陷阱组件最常见的用例是在模态框组件内保持焦点，该模态框组件与打开模态框的元素完全独立。但是您也可以为焦点陷阱组件的 open prop 创建一个切换按钮，该按钮存储在组件自身内部，如下面的演示所示

<FocusTrap open={open} disableRestoreFocus disableAutoFocus>
  <Stack spacing={2} sx={{ alignItems: 'center' }}>
    <button type="button" onClick={() => setOpen(!open)}>
      {open ? 'Close' : 'Open'}
    </button>
    {open && (
      <label>
        First name: <input type="text" />
      </label>
    )}
  </Stack>
</FocusTrap>

<FocusTrap open={open} disableRestoreFocus disableAutoFocus>
  <Stack spacing={2} sx={{ alignItems: 'center' }}>
    <button type="button" onClick={() => setOpen(!open)}>
      {open ? 'Close' : 'Open'}
    </button>
    {open && (
      <label>
        First name: <input type="text" />
      </label>
    )}
  </Stack>
</FocusTrap>

按 Enter 键开始编辑