模态对话框

本词条尚无可操作示例；插画为编辑示意，应用到产品时仍须验证焦点管理与键盘可达性。

{
  "states": [
    "closed",
    "open",
    "confirmed",
    "dismissed"
  ],
  "a11y": [
    "容器使用 dialog 角色并标记为模态，有可访问的标题",
    "打开时焦点进入对话框，关闭时焦点回到触发元素",
    "Escape 与显式关闭控件都能关闭"
  ],
  "motion": "遮罩与出现动画可省略；减弱动态偏好下直接显示"
}

{
  "id": "modal-dialog",
  "type": "interaction",
  "name": {
    "zh": "模态对话框",
    "en": "Modal Dialog"
  },
  "aliases": [
    "模态窗口",
    "弹窗",
    "模态框",
    "modal"
  ],
  "granularity": "component",
  "intents": [
    "confirm-action",
    "focus-task"
  ],
  "tags": [
    "对话框",
    "确认",
    "打断",
    "焦点",
    "遮罩"
  ],
  "definition": "覆盖在主内容之上的对话框，它使系统进入一种特殊模式：在用户明确处理该对话框之前，主内容被禁用、不可交互。",
  "boundary": "不是所有弹出层都是模态：非模态对话框、气泡提示与渐进披露的展开都允许用户继续操作页面。判断标准是页面其余部分是否在对话框关闭前保持惰性；只要背景仍可点击或可获得焦点，就不应称为模态。",
  "signature": [
    "对话框外的内容被遮罩且不可操作",
    "打开时焦点进入对话框，Tab 只在其内部循环",
    "有明确的关闭途径，关闭后焦点回到触发处"
  ],
  "when": [
    "需要在不可逆操作前阻止关键错误",
    "继续用户自己发起的流程必须先取得一项必要信息",
    "需要把复杂流程切成必须逐步完成的小步骤"
  ],
  "when_not": [
    "内容与用户当前目标无关，例如订阅推广或非必要提示",
    "用户需要参考对话框外的信息才能作出决定",
    "任务可以在原位或旁路完成而不必打断"
  ],
  "tradeoff": "换来用户注意力的集中与错误预防，代价是打断当前任务；与目标无关的打断会被视为骚扰并削弱信任。",
  "comparison": {
    "focus": "让用户先处理一件事再继续",
    "mechanism": "遮罩并禁用主内容，把交互限制在对话框内",
    "cost": "打断任务流，并需承担焦点管理与退出路径的实现责任"
  },
  "sources": [
    {
      "id": "nng-modal-nonmodal",
      "title": "NN/g · Modal & Nonmodal Dialogs: When (& When Not) to Use Them",
      "url": "https://www.nngroup.com/articles/modal-nonmodal-dialog/",
      "claim": "模态对话框覆盖主内容并使系统进入需要用户先行交互的特殊模式；适用于防止关键错误与获取继续流程所需的信息，与用户目标无关的模态会被视为骚扰并削弱信任。",
      "checkedAt": "2026-09-15",
      "archive": {
        "lookupUrl": "https://web.archive.org/web/20260915*/https://www.nngroup.com/articles/modal-nonmodal-dialog/",
        "status": "unconfirmed",
        "checkedAt": "2026-09-15T18:05:14.105Z",
        "error": "status-request-failed",
        "jobId": "spn2-42b9d1bde63dee38bec054ca6b77099df0a12208"
      }
    },
    {
      "id": "apg-dialog-modal",
      "title": "WAI-ARIA APG · Dialog (Modal) Pattern",
      "url": "https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/",
      "claim": "模态对话框之下的窗口是惰性的；打开时焦点移入对话框，Tab 在其内部循环，Escape 关闭，关闭后焦点返回触发元素；容器使用 dialog 角色并设置 aria-modal。",
      "checkedAt": "2026-09-15",
      "archive": {
        "lookupUrl": "https://web.archive.org/web/20260915*/https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/",
        "status": "available",
        "checkedAt": "2026-09-15T18:05:58.794Z",
        "jobId": "spn2-399060bd1635b97ac2d04c6443f46faf4dc5b8ed",
        "url": "https://web.archive.org/web/20260915180710/https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/",
        "timestamp": "20260915180710"
      }
    },
    {
      "id": "mdn-dialog",
      "title": "MDN · <dialog>: The Dialog element",
      "url": "https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dialog",
      "claim": "以 showModal() 打开的对话框使页面其余部分惰性并可用 Esc 关闭，而 show() 打开的非模态对话框不会；应提供显式的关闭按钮。",
      "checkedAt": "2026-09-15",
      "archive": {
        "lookupUrl": "https://web.archive.org/web/20260915*/https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dialog",
        "status": "available",
        "checkedAt": "2026-09-15T18:05:59.233Z",
        "jobId": "spn2-b4866376b185c337617d6b9f564715f6bc7d624c",
        "url": "https://web.archive.org/web/20260915180623/https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/dialog",
        "timestamp": "20260915180623"
      }
    }
  ],
  "relations": [
    {
      "target": "progressive-disclosure",
      "kind": "related",
      "condition": "只是展开次要内容而不必阻断页面",
      "reason": "渐进披露允许用户继续操作页面，模态则要求先处理再继续；不要因为内容是次要的就把它做成模态。",
      "basis": "editorial"
    },
    {
      "target": "inline-edit",
      "kind": "alternative",
      "condition": "修改短字段且周边内容是有用的参照",
      "reason": "原位编辑保留上下文，而模态会遮住用户可能需要参考的信息。",
      "basis": "editorial"
    },
    {
      "target": "confirmshaming",
      "kind": "misused_as",
      "condition": "用带羞辱意味的拒绝文案阻拦用户离开",
      "reason": "模态的阻断力不应被用来施压；拒绝选项必须与确认选项同样清楚、中性。",
      "basis": "editorial"
    }
  ],
  "rules": [
    {
      "when": "对话框打开",
      "instruction": "把焦点移入对话框，并把 Tab 循环限制在其内部；关闭后把焦点送回触发元素。",
      "strength": "must",
      "basis": "editorial"
    },
    {
      "when": "用户想放弃当前对话框",
      "instruction": "提供显式的关闭或取消控件，并支持 Escape 关闭。",
      "strength": "must",
      "basis": "editorial"
    },
    {
      "when": "对话框内已有未提交的输入",
      "instruction": "点击遮罩不应无提示地丢弃输入；先确认或改为仅按钮关闭。",
      "strength": "recommend",
      "basis": "editorial"
    }
  ],
  "behavior": {
    "states": [
      "closed",
      "open",
      "confirmed",
      "dismissed"
    ],
    "a11y": [
      "容器使用 dialog 角色并标记为模态，有可访问的标题",
      "打开时焦点进入对话框，关闭时焦点回到触发元素",
      "Escape 与显式关闭控件都能关闭"
    ],
    "motion": "遮罩与出现动画可省略；减弱动态偏好下直接显示"
  },
  "demo": null,
  "version": "0.1.0",
  "editorialStatus": "drafted",
  "requirements": [],
  "demoCapabilities": [],
  "implementationNote": "本词条尚无可操作示例；插画为编辑示意，应用到产品时仍须验证焦点管理与键盘可达性。",
  "image": {
    "src": "/images/modal-dialog.webp",
    "alt": "虚构的 FIELDNOTES 应用界面被遮罩压暗，中央是一张带标题、一行正文、主次两个按钮和关闭控件的对话框卡片。"
  },
  "searchTerms": [
    "dialog",
    "confirmation",
    "interruption",
    "focus",
    "overlay"
  ]
}