反馈与浮层

反馈类按惯例处理。浮层是全系统唯一允许有"面"的地方，这个例外是论证出来的，不是图方便。

提示块

每一级都同时有颜色和文字标签。标签不是装饰—— 它是让级别在无色觉条件下依然可感知的东西。

说明

中性补充信息。

建议

推荐的做法。

注意

需要留心的边界情况。

危险

会造成不可逆后果。

行内提示

存储空间不足。剩余不到 10%；清理不需要的文件后再继续。

连接已断开。检查网络后重新提交。

导出已完成。文件已保存到所选位置。

本示例不自动重连；产品若承诺自动重连，必须实际实现该流程并播报状态。

通知

aria-live="polite"——不是 assertive。一条通知永远没有紧急到需要打断读者。

查看代码 · Source

<div class="wx-cluster">
  <button class="wx-btn" type="button" onclick="wxToast('已复制到剪贴板')">普通</button>
  <button class="wx-btn" type="button" onclick="wxToast('草稿已保存', {level:'success', label:'已保存'})">成功</button>
  <button class="wx-btn" type="button" onclick="wxToast('磁盘空间不足', {level:'warn', label:'警告'})">警告</button>
  <button class="wx-btn" type="button" onclick="wxToast('提交失败，请重试', {level:'danger', label:'失败'})">失败</button>
</div>

wxToast("草稿已保存", { level: "success", label: "已保存", ms: 5000 });

已保存草稿已保存到本机。

查看代码 · Source

<div class="doc-toast-example">
  <div class="wx-toast wx-toast--success"><span class="wx-toast__label">已保存</span><span>草稿已保存到本机。</span></div>
</div>

进度与量度

没有不确定态。不确定进度条是一个永不停止的循环动画，也就是换了形状的 spinner。无 value 时渲染成一根静止的线，由旁边的文字说明正在发生什么。

导出中64%

磁盘用量

查看代码 · Source

<div class="wx-progress-field">
  <div class="wx-progress-field__row"><span>导出中</span><span class="wx-progress-field__value">64%</span></div>
  <progress class="wx-progress" value="64" max="100" aria-label="导出进度"></progress>
</div>
<p style="margin-block-start:var(--space-6)">磁盘用量
  <meter class="wx-meter" value="0.82" high="0.8" aria-label="磁盘用量 82%"></meter></p>

何时使用、何时不用与 API

组件	何时使用 · 不用	契约（ARIA / 脚本）
`wx-note / wx-alert`	持续说明、上下文状态；瞬时操作结果用 toast。	alert 先有状态标题；只有阻塞继续时才给明确恢复路径，文字与颜色同时出现；不可逆风险用 danger。
`wx-toast`	短暂、非阻塞结果；需要确认或读长文的消息改 dialog / note。	稳定 `aria-live="polite" aria-atomic="true"` region；由 `overlay.js` 的 `wxToast()` 追加消息。
`wx-progress / wx-meter`	可量化进度、已知量度；未知等待写文字，不做 spinner。	原生 `progress/meter` 加可访问名；无 value 不伪造进度。
`wx-empty / wx-result`	无内容、完成/失败页面；不要用装饰插画填空。	标题先说明状态，动作是可命名 button/link。
`wx-modal / wx-drawer`	必须中断的确认、临时上下文；普通详情不要浮层。	原生 `dialog`、`aria-labelledby`；`overlay.js` 负责开关和焦点归还。
`wx-tooltip / wx-popover`	补充提示、可操作的小面板；任何关键信息不可只放 tooltip。	tooltip 用 `role="tooltip"` + `aria-describedby`；popover 用原生 `details`。
`wx-popconfirm`	就近、短说明的危险确认；复杂或多步决策改用 dialog。	原生 `details` 负责开合；采用者只在明确确认后执行动作。

空态与结果

还没有内容

纯文字说明加一个命名动作，不用插图。

查看条目列表

浮层

对话框和抽屉建在原生 <dialog> 上：焦点陷阱、Esc、inert 背景全部来自平台。toast 则进入稳定的 aria-live 区域，不夺走焦点。脚本只补平台没给的两件事——关闭后把焦点还给触发按钮，和向稳定区域追加 toast。

查看代码 · Source

<div class="wx-cluster">
  <button class="wx-btn" type="button" data-wx-open="#d-modal">对话框</button>
  <button class="wx-btn" type="button" data-wx-open="#d-drawer">抽屉</button>
</div>
<dialog class="wx-modal" id="d-modal" aria-labelledby="dm-t">
  <h3 class="wx-modal__title" id="dm-t">确认操作</h3>
  <div class="wx-modal__body"><p>按 Esc 或点击遮罩都可以关闭，焦点会回到刚才那个按钮。</p></div>
  <div class="wx-modal__actions">
    <button class="wx-btn" type="button" data-wx-close>取消</button>
    <button class="wx-btn wx-btn--primary" type="button" data-wx-close>确认</button>
  </div>
</dialog>
<dialog class="wx-drawer" id="d-drawer" aria-labelledby="dd-t">
  <div class="wx-drawer__header">
    <h3 id="dd-t">筛选</h3>
    <button class="wx-btn wx-btn--text" type="button" data-wx-close>关闭</button>
  </div>
  <p>抽屉从行末边缘进入，只在一条边上有分隔线。</p>
</dialog>

确认气泡

删除、撤销等就近、后果明确的危险操作可用确认气泡；如果后果复杂、需要解释或有多个字段，改用对话框。

删除草稿

确认删除这份草稿？

删除后无法恢复。

查看代码 · Source

<details class="wx-popconfirm">
  <summary class="wx-btn wx-btn--danger">删除草稿</summary>
  <div class="wx-popconfirm__panel">
    <strong>确认删除这份草稿？</strong><p>删除后无法恢复。</p>
    <div class="wx-popover__actions"><button class="wx-btn wx-btn--text" type="button" onclick="this.closest('details').open = false">取消</button><button class="wx-btn wx-btn--danger" type="button" onclick="this.closest('details').open = false; wxToast('草稿已删除（示例）', { level: 'success', label: '已删除' })">确认删除</button></div>
  </div>
</details>

为什么浮层可以有"面"

一个不像独立层的浮层不是克制，是可用性缺陷——读者无法判断什么可以关闭、什么是页面本身。仲裁第一层（基本可用性）和第三层（反馈按惯例）指向同一个方向。但"需要分离"只授权分离本身：发丝线边缘 + 暖色遮罩就够了，阴影和渐变是另一回事。

wx-tooltip 有一条硬规则：永远不得作为信息的唯一载体。它在触屏上不可达、打印时不存在、极易被错过。读者必须知道的东西写进正文。

导出格式为 ——"导出格式"这句话本身已经完整。

需要承载可交互内容时用气泡，它建在 <details> 上因而键盘可达：

查看代码 · Source

<p>导出格式为
  <span class="wx-tooltip">
    <button class="wx-btn wx-btn--text" type="button" aria-describedby="tp">CSV</button>
    <span class="wx-tooltip__bubble" role="tooltip" id="tp">逗号分隔值，可用表格软件打开</span>
  </span>——"导出格式"这句话本身已经完整。</p>
<p style="margin-block-start:var(--space-6)">需要承载可交互内容时用气泡，它建在
  <code>&lt;details&gt;</code> 上因而键盘可达：</p>
<details class="wx-popover">
  <summary class="wx-btn">删除</summary>
  <div class="wx-popover__panel">
    <span class="wx-popover__title">确认删除？</span>
    <p>此操作不可撤销。</p>
    <div class="wx-popover__actions">
      <button class="wx-btn wx-btn--text" type="button" onclick="this.closest('details').open = false">取消</button>
      <button class="wx-btn wx-btn--danger" type="button" onclick="this.closest('details').open = false; wxToast('已删除（示例）', { level: 'success', label: '已删除' })">确认删除</button>
    </div>
  </div>
</details>

结果

wx-result 用于一次操作结束后的整页反馈：成功、失败、404、无权限。它必须给出下一步——一个只说"出错了"的页面把读者留在了死路上。这里的“回到首页”是反馈收束的安全入口，不同于着陆页把读者送往别处的导航 CTA，因此可以成为唯一的主操作。

404

这个页面不存在

链接可能已经变更，或者从一开始就写错了。

示例编号：WX-404-8B3525

回到首页查看全部组件 →

查看代码 · Source

<section class="wx-result">
  <p class="wx-result__mark">404</p>
  <h3 class="wx-result__title">这个页面不存在</h3>
  <p class="wx-result__body">链接可能已经变更，或者从一开始就写错了。</p>
  <p class="wx-result__detail">示例编号：WX-404-8B3525</p>
  <div class="wx-result__actions">
    <a class="wx-btn wx-btn--primary" href="./index.html">回到首页</a>
    <a class="wx-btn wx-btn--text" href="./components.html">查看全部组件 →</a>
  </div>
</section>

何时使用	何时不用
一次操作结束，整页只剩这一件事要说。	页面其余内容仍然有效时——那用 `wx-alert`。
404、403、500 等路由级状态。	某个字段出错时——那用 `wx-field__error` 与错误汇总。
需要读者做一个明确选择才能继续。	只是通知、不需要动作时——那用 `wx-toast`。

没有插画。状态由文字承担：一个数字、一句说明、一到两个动作。这不是省事——空状态插画是这套语言里最典型的"用装饰替代信息"。整页反馈的完整编排见结果与异常页。

反馈与浮层

提示块

行内提示

通知

进度与量度

何时使用、何时不用与 API

空态与结果

浮层

确认气泡

提示与气泡

结果

这个页面不存在