UI 视觉设计 / 系统课时

处理 Dialog 层级与键盘交互

处理 Dialog 层级与键盘交互

Figma 里的 Dialog 往往只标了卡片和遮罩,React 落地时还要让背景不可操作、键盘焦点留在弹窗内,并在关闭后回到触发位置。这里用原生 dialog 实现昵称编辑框,完整处理初始焦点、取消、保存与键盘验收。

学习目标

  • 将 Figma 的遮罩与卡片层级映射到浏览器模态顶层。
  • 实现初始焦点、Tab 循环、Esc 关闭和焦点回退。
  • 验证取消不提交、保存才更新数据的交互契约。

将设计层级映射到浏览器顶层

先在 Figma 约定页面、遮罩、卡片三层;在 React 中用原生 <dialog> 的 showModal() 打开。浏览器会把弹窗及其 ::backdrop 放进 top layer,并使弹窗外的页面内容不可交互,无须猜测 z-index: 9999 能否压过其他组件。

设计层 React 对应 可核对的规范
页面内容 弹窗打开期间由浏览器视为 inert 无法点击或通过 Tab 聚焦
遮罩 Scrim dialog::backdrop 深蓝灰 rgba(15, 23, 42, 0.56)
Dialog 卡片 <dialog className="edit-dialog"> 最大宽度 420px,内边距 24px,圆角 12px

不要用 open 属性或 show() 冒充模态:它们不会提供与 showModal() 相同的背景禁用行为。原生机制可对照 MDN 的 showModal 说明。

确定焦点与关闭规则

这个例子是带草稿的编辑弹窗,打开时焦点进入“昵称”输入框;按 Esc 或“取消”只丢弃本次草稿,“保存”才提交。为避免误触,点击遮罩不关闭。关闭后焦点回到“编辑昵称”按钮,键盘用户才能继续原来的操作位置。

用户操作 预期行为
点击或按 Enter 打开 焦点定位在“昵称”输入框
Tab / Shift+Tab 只遍历弹窗中的可聚焦控件;禁用的按钮会被跳过
Esc 或“取消” 关闭弹窗,不写入昵称
“保存” 非空时写入昵称并关闭弹窗
点击遮罩 保持弹窗打开
弹窗关闭 焦点返回触发按钮

Dialog 顶层结构与键盘焦点闭环

在 React 中实现可运行弹窗

示例适用于 React 18+、TypeScript 以及支持原生 showModal() 的现代浏览器,不依赖弹窗库。先创建 Vite 的 React TypeScript 工程:

bash
npm create vite@latest dialog-keyboard-demo -- --template react-ts
cd dialog-keyboard-demo
npm install

预期结果:生成包含 src/App.tsx、src/App.css 的工程,依赖安装成功。

将 src/App.tsx 替换为下面的完整组件:

tsx
import { useRef, useState } from "react";
import "./App.css";

export default function App() {
  const dialogRef = useRef<HTMLDialogElement>(null);
  const inputRef = useRef<HTMLInputElement>(null);
  const triggerRef = useRef<HTMLButtonElement>(null);
  const [name, setName] = useState("小林");
  const [draft, setDraft] = useState("小林");

  function openDialog() {
    const dialog = dialogRef.current;
    if (!dialog || dialog.open) return;
    // 每次打开都从已保存值创建草稿,取消不会提交修改。
    setDraft(name);
    dialog.showModal();
    inputRef.current?.focus();
  }

  function closeDialog() {
    dialogRef.current?.close();
  }

  function saveDialog() {
    const nextName = draft.trim();
    if (!nextName) return;
    setName(nextName);
    closeDialog();
  }

  // 原生 close 事件同时覆盖 Esc、取消和保存三种关闭路径。
  return (
    <main>
      <p>当前昵称:{name}</p>
      <button ref={triggerRef} type="button" onClick={openDialog}>
        编辑昵称
      </button>
      <dialog
        ref={dialogRef}
        className="edit-dialog"
        aria-labelledby="dialog-title"
        aria-describedby="dialog-desc"
        onClose={() => triggerRef.current?.focus()}
      >
        <h2 id="dialog-title">编辑昵称</h2>
        <p id="dialog-desc">只有保存后才会更新昵称。</p>
        <label htmlFor="nickname">昵称</label>
        <input
          id="nickname"
          ref={inputRef}
          value={draft}
          onChange={(event) => setDraft(event.target.value)}
        />
        <div className="dialog-actions">
          <button type="button" onClick={closeDialog}>取消</button>
          <button type="button" disabled={!draft.trim()} onClick={saveDialog}>
            保存
          </button>
        </div>
      </dialog>
    </main>
  );
}

预期结果:页面默认显示“当前昵称:小林”;点击“编辑昵称”后弹窗打开,焦点进入输入框。aria-labelledby 与 aria-describedby 分别关联可见标题和简短说明。

将 src/App.css 替换为以下样式:

css
body {
  font-family: system-ui, sans-serif;
}

button, input {
  font: inherit;
}

.edit-dialog {
  box-sizing: border-box;
  width: min(420px, calc(100vw - 32px));
  padding: 24px;
  border: 0;
  border-radius: 12px;
  box-shadow: 0 20px 60px rgba(15, 23, 42, 0.22);
}

/* 只给原生顶层遮罩着色,不额外创建覆盖全屏的 div。 */
.edit-dialog::backdrop {
  background: rgba(15, 23, 42, 0.56);
}

.edit-dialog input {
  box-sizing: border-box;
  width: 100%;
  margin-top: 8px;
  padding: 10px;
}

.dialog-actions {
  display: flex;
  justify-content: flex-end;
  gap: 12px;
  margin-top: 24px;
}

:focus-visible {
  outline: 3px solid #2563eb;
  outline-offset: 2px;
}

预期结果:弹窗宽度最多 420px,窄屏保留左右各 16px 的空间;遮罩覆盖背景,键盘聚焦控件时出现 3px 蓝色轮廓。

启动开发服务器:

bash
npm run dev

预期结果:终端显示本地访问地址,例如 http://localhost:<PORT>/;<PORT> 表示实际端口,可能随环境变化。

用键盘验收关闭与焦点回退

  1. 通过 Tab 聚焦“编辑昵称”,按 Enter 打开;焦点应自动进入“昵称”输入框,背景按钮无法被聚焦。
  2. 连续按 Tab,应在输入框、“取消”、“保存”之间循环;Shift+Tab 反向移动。把输入清空后,“保存”禁用且不再进入 Tab 顺序。
  3. 输入“测试用户”后按 Esc;弹窗关闭,焦点回到“编辑昵称”,页面仍显示“当前昵称:小林”。再次打开时,草稿恢复为“小林”。
  4. 打开弹窗并点击遮罩,弹窗应保持打开;点击“取消”则关闭且不修改昵称。
  5. 输入“测试用户”并点击“保存”;页面更新为“当前昵称:测试用户”,焦点回到触发按钮。

对于删除确认等不可逆操作,应把初始焦点改到“取消”等低风险动作;具体原则可参照 W3C 模态对话框模式。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

处理 Dialog 层级与键盘交互

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通