焦點陷阱

Focus Trap 元件可防止使用者的焦點逸出其子元件。

簡介

Focus Trap 是一個實用元件，在實作覆蓋層時非常有用，例如 modal 對話框，它應該在開啟時阻擋所有外部互動。

元件

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

Focus Trap 包裹著應該 удерживать 使用者焦點的 UI 元素。例如，如果焦點需要停留在選單內，則元件的結構會像這樣

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

以下示範展示了一個 <button>，它會開啟一個巢狀在 Focus Trap 內的 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 開始編輯

客製化

停用強制焦點

預設情況下，會阻擋 Focus Trap 元件外部的點擊。

您可以使用 disableEnforceFocus 屬性停用此行為。

將以下示範與元件章節中的示範進行比較—請注意，該示範會阻止您點擊其外部，而這個示範允許這樣做

<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 屬性存在時，Focus Trap 元件會自動將焦點移動到其第一個子元件。

您可以使用 disableAutoFocus 屬性停用此行為並使其延遲。當停用自動對焦時（如下面的示範所示），元件只會在使用者將焦點移動到那裡時才捕捉焦點

<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 元件將 Focus Trap 子元件的子集渲染到目前 DOM 階層外部的新「子樹」中，因此它們不再是焦點迴圈的一部分

在陷阱內使用切換

Focus Trap 元件最常見的用例是在 Modal 元件中維持焦點，該元件與開啟 modal 的元素完全分離。但是您也可以為 Focus Trap 元件的 open 屬性建立一個切換按鈕，該按鈕儲存在元件本身內部，如下面的示範所示

<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 開始編輯