轻提示 toast

反馈与浮层组件。三层同源：无头内核给出解剖与状态机，Vue 组件与自定义元素只是它的两层外壳，行为完全一致。

示例

基础用法

单独一条通知：title 与 description 没写插槽内容时由 props 兜底；duration 给 0 即不自动消失

草稿已保存

内容已同步到云端

<script setup lang="ts">
import { ref } from "vue";
import {
  XhButton,
  XhToastCloseTrigger,
  XhToastDescription,
  XhToastRoot,
  XhToastTitle,
} from "@xihan-ui/vue";

// 关掉之后换一个 key 重新挂一条，方便反复看
const seq = ref(0);
</script>

<template>
  <div style="display: grid; gap: 12px; justify-items: start">
    <XhToastRoot
      :key="seq"
      title="草稿已保存"
      description="内容已同步到云端"
      :duration="0"
      :translations="{ close: '关闭' }"
    >
      <XhToastTitle />
      <XhToastDescription />
      <XhToastCloseTrigger>✕</XhToastCloseTrigger>
    </XhToastRoot>
    <XhButton size="sm" variant="outline" @click="seq++">再挂一条</XhButton>
  </div>
</template>

语气

type 落成 data-type，皮肤据此换色条；error 走 alert + assertive，loading 表示事情还没完、不自动消失

草稿已保存

内容已同步到云端

发布成功

文档已对所有人可见

配额即将用尽

本月还剩 8% 额度

同步失败

网络中断，稍后自动重试

正在上传

已完成 42%

<script setup lang="ts">
import { XhToastDescription, XhToastRoot, XhToastTitle } from "@xihan-ui/vue";

const items = [
  { type: "info", title: "草稿已保存", description: "内容已同步到云端" },
  { type: "success", title: "发布成功", description: "文档已对所有人可见" },
  { type: "warning", title: "配额即将用尽", description: "本月还剩 8% 额度" },
  { type: "error", title: "同步失败", description: "网络中断，稍后自动重试" },
  { type: "loading", title: "正在上传", description: "已完成 42%" },
] as const;
</script>

<template>
  <div style="display: grid; gap: 12px; justify-items: start">
    <XhToastRoot
      v-for="item in items"
      :key="item.type"
      :type="item.type"
      :title="item.title"
      :description="item.description"
      :duration="0"
      :closable="false"
    >
      <XhToastTitle />
      <XhToastDescription />
    </XhToastRoot>
  </div>
</template>

计时与暂停

duration 走完自动退场；指针停在卡片上或焦点进到卡片里都会把计时按住，离开才接着走剩下那一段

6 秒后自动收走

把鼠标停在这张卡片上，计时会被按住

状态：visible · 计时在走

<script setup lang="ts">
import { ref } from "vue";
import {
  XhButton,
  XhToastCloseTrigger,
  XhToastDescription,
  XhToastRoot,
  XhToastTitle,
} from "@xihan-ui/vue";

const seq = ref(0);
</script>

<template>
  <div style="display: grid; gap: 12px; justify-items: start">
    <XhToastRoot
      :key="seq"
      v-slot="{ status, paused }"
      title="6 秒后自动收走"
      description="把鼠标停在这张卡片上，计时会被按住"
      :duration="6000"
      :translations="{ close: '关闭' }"
    >
      <XhToastTitle />
      <XhToastDescription />
      <span style="font-size: 12px; opacity: 0.75">
        状态：{{ status }} · {{ paused ? "计时已按住" : "计时在走" }}
      </span>
      <XhToastCloseTrigger>✕</XhToastCloseTrigger>
    </XhToastRoot>
    <XhButton size="sm" variant="outline" @click="seq++">重新计时</XhButton>
  </div>
</template>

操作按钮

action-trigger 按下时先发 action 事件，再让这条进入退场；closable 决定还要不要那颗叉

已删除 1 个文件

30 秒内可以撤销

（还没点）

<script setup lang="ts">
import { ref } from "vue";
import {
  XhButton,
  XhToastActionTrigger,
  XhToastCloseTrigger,
  XhToastDescription,
  XhToastRoot,
  XhToastTitle,
} from "@xihan-ui/vue";

const seq = ref(0);
const log = ref("（还没点）");

function onAction(details: { id: string }): void {
  log.value = `撤销了：${details.id}`;
}
</script>

<template>
  <div style="display: grid; gap: 12px; justify-items: start">
    <XhToastRoot
      :key="seq"
      id="toast-demo-action"
      title="已删除 1 个文件"
      description="30 秒内可以撤销"
      :duration="0"
      :translations="{ close: '关闭' }"
      @action="onAction"
    >
      <XhToastTitle />
      <XhToastDescription />
      <div style="display: flex; align-items: center; gap: 8px">
        <XhToastActionTrigger>撤销</XhToastActionTrigger>
        <XhToastCloseTrigger>✕</XhToastCloseTrigger>
      </div>
    </XhToastRoot>
    <div style="display: flex; align-items: center; gap: 12px">
      <XhButton size="sm" variant="outline" @click="seq++">再挂一条</XhButton>
      <span>{{ log }}</span>
    </div>
  </div>
</template>

图标与自定义排版

卡片里排什么由作者定：图标与标题排成一行，标题、描述两个部件都接受插槽内容

✓

发布成功

文档已对所有人可见

!

配额即将用尽

本月还剩 8% 额度

✕

同步失败

网络中断，稍后自动重试

<script setup lang="ts">
import {
  XhToastDescription,
  XhToastRoot,
  XhToastTitle,
} from "@xihan-ui/vue";

const items = [
  {
    type: "success",
    glyph: "✓",
    title: "发布成功",
    description: "文档已对所有人可见",
  },
  {
    type: "warning",
    glyph: "!",
    title: "配额即将用尽",
    description: "本月还剩 8% 额度",
  },
  {
    type: "error",
    glyph: "✕",
    title: "同步失败",
    description: "网络中断，稍后自动重试",
  },
] as const;

// 图标只是装饰，读屏念标题就够了
const glyphStyle = {
  display: "grid",
  placeItems: "center",
  flex: "none",
  inlineSize: "20px",
  blockSize: "20px",
  borderRadius: "999px",
  background: "var(--xh-bg-muted)",
  fontSize: "12px",
  lineHeight: "1",
};
</script>

<template>
  <div style="display: grid; gap: 12px; justify-items: start">
    <XhToastRoot
      v-for="item in items"
      :key="item.type"
      :type="item.type"
      :duration="0"
      :closable="false"
    >
      <div style="display: flex; align-items: center; gap: 8px">
        <span aria-hidden="true" :style="glyphStyle">{{ item.glyph }}</span>
        <XhToastTitle>{{ item.title }}</XhToastTitle>
      </div>
      <XhToastDescription>{{ item.description }}</XhToastDescription>
    </XhToastRoot>
  </div>
</template>

产物

层	值
自定义元素	<xh-toast>
Vue 组件	XhToastActionTrigger XhToastCloseTrigger XhToastDescription XhToastRoot XhToastTitle
组合式函数	useToast
状态机	toastMachine
皮肤	@xihan-ui/styles/toast.css

解剖

部件名即 data-part 属性值，也是皮肤的选择器。加粗的是必备部件，不渲染它组件不工作（Web Components 适配器会在诊断通道上报 wc.missing-part）。

data-scope="toast"：root · title · description · action-trigger · close-trigger

Props

属性	类型	必填	说明
id	string		队列身份。toaster 用它做 create/update/dismiss 的寻址键。
title	string		标题文本；作者没在 title 部件里写内容时由适配器填入。
description	string		补充说明；作者没在 description 部件里写内容时由适配器填入。
type	ToastType		语气，默认 info。error 走 alert + assertive，loading 不自动消失。
duration	number		停留毫秒，默认 5000。<=0 或非有限数即不自动消失。
removeDelay	number		退场窗口毫秒，默认 200：进入 dismissing 后停留这么久再转 unmounted，留给退场动画。
closable	boolean		是否显示可用的关闭按钮，默认 true。
pauseOnPageIdle	boolean		页面切到后台时暂停计时，默认 false。由 toaster 统一下发。
translations	Partial<ToastTranslations>
onStatusChange	(details: ToastStatusChangeDetails) => void		生命周期落位时通知：dismissing 与 unmounted 各一次。宿主据此把条目移出队列。
onAction	(details: ToastActionDetails) => void		操作按钮被按下。

状态机

状态：visible · visible.running · visible.paused · dismissing · unmounted

事件：TOAST.DISMISS · TOAST.ACTION · TOAST.PAUSE · TOAST.RESUME · TOAST.RESET · after.duration · after.removeDelay

判据：isLastPauseSource

connect API

useToast 产出的对象。getXxxProps() 铺到对应部件的宿主元素上，其余是可读状态与操作入口。

成员	类型	说明
id	string
status	ToastStatus
type	ToastType
title	string | undefined
description	string | undefined
paused	boolean	计时被按住中。样式层据此暂停进度条动画。
closable	boolean
remaining	number	剩余毫秒；不自动消失时为 Infinity。
dismiss	() => void
pause	() => void
resume	() => void
getRootProps	() => T['element']
getTitleProps	() => T['element']
getDescriptionProps	() => T['element']
getActionTriggerProps	() => T['button']
getCloseTriggerProps	() => T['button']

键盘

规格出处：W3C APG

按键	生效条件	行为
Enter / Space	focus 在 close-trigger 上且 closable	立即进入 dismissing，走完 removeDelay 后转 unmounted
Enter / Space	focus 在 action-trigger 上	触发 onAction 并进入 dismissing