警告提示 alert

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

示例

基础用法

各部件按需摆放，标题与描述都是可选的

部署已排队

构建完成后会自动发布。

<script setup lang="ts">
import { XhAlertDescription, XhAlertRoot, XhAlertTitle } from "@xihan-ui/vue";
</script>

<template>
  <div style="width: 100%; display: grid; gap: 12px">
    <XhAlertRoot>
      <XhAlertTitle>部署已排队</XhAlertTitle>
      <XhAlertDescription>构建完成后会自动发布。</XhAlertDescription>
    </XhAlertRoot>
  </div>
</template>

语气

tone 只改配色，语义仍由内容与 role 决定

保存成功

配额即将用尽

发布失败

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

<template>
  <div style="width: 100%; display: grid; gap: 12px">
    <XhAlertRoot tone="success"><XhAlertTitle>保存成功</XhAlertTitle></XhAlertRoot>
    <XhAlertRoot tone="warning"><XhAlertTitle>配额即将用尽</XhAlertTitle></XhAlertRoot>
    <XhAlertRoot tone="danger"><XhAlertTitle>发布失败</XhAlertTitle></XhAlertRoot>
  </div>
</template>

可关闭

closable 开启后才渲染关闭按钮；open 受控时由宿主决定去留

点右侧关闭

<script setup lang="ts">
import { ref } from "vue";
import {
  XhAlertCloseTrigger,
  XhAlertRoot,
  XhAlertTitle,
  XhButton,
} from "@xihan-ui/vue";

const open = ref(true);
</script>

<template>
  <div style="width: 100%; display: grid; gap: 12px">
    <XhAlertRoot v-model:open="open" closable>
      <XhAlertTitle>点右侧关闭</XhAlertTitle>
      <XhAlertCloseTrigger>×</XhAlertCloseTrigger>
    </XhAlertRoot>
    <XhButton v-if="!open" size="sm" @click="open = true">再显示一次</XhButton>
  </div>
</template>

图标

icon 部件排在标题前面，颜色取当前语气的强调色；内容由作者塞，字形与内联 svg 都行

✓

发布完成

三个节点都已切到新版本。

发布失败

第 2 个节点健康检查未通过。

<script setup lang="ts">
import {
  XhAlertDescription,
  XhAlertIcon,
  XhAlertRoot,
  XhAlertTitle,
} from "@xihan-ui/vue";
</script>

<template>
  <div style="width: 100%; display: grid; gap: 12px">
    <!-- 一个字形就够：图标是纯装饰，读屏不会念它 -->
    <XhAlertRoot tone="success">
      <XhAlertIcon>✓</XhAlertIcon>
      <XhAlertTitle>发布完成</XhAlertTitle>
      <XhAlertDescription>三个节点都已切到新版本。</XhAlertDescription>
    </XhAlertRoot>

    <!-- 内联 svg 同样能塞进来，描边取 currentColor 就跟着语气走 -->
    <XhAlertRoot tone="danger">
      <XhAlertIcon>
        <svg
          viewBox="0 0 24 24"
          width="16"
          height="16"
          fill="none"
          stroke="currentColor"
          stroke-width="2"
          stroke-linecap="round"
          stroke-linejoin="round"
        >
          <path d="M12 3.5L21.5 20H2.5Z" />
          <path d="M12 9.5v4" />
          <path d="M12 16.5v.5" />
        </svg>
      </XhAlertIcon>
      <XhAlertTitle>发布失败</XhAlertTitle>
      <XhAlertDescription>第 2 个节点健康检查未通过。</XhAlertDescription>
    </XhAlertRoot>
  </div>
</template>

自定义外观

描边、底色、标题色、圆角各是一个组件令牌；描边槽位换成透明就只剩淡底，尺寸不变

无描边

底色与内边距都还在。

无底色

剩一圈线，衬在页面本来的底色上。

自定配色

底色、描边、标题色、圆角各占一个槽位。

<script setup lang="ts">
import { XhAlertDescription, XhAlertRoot, XhAlertTitle } from "@xihan-ui/vue";
</script>

<template>
  <div style="width: 100%; display: grid; gap: 12px">
    <!-- 只留淡底：描边换成透明，边框盒还在，不会因为掉了一圈线而跳动 -->
    <XhAlertRoot tone="info" style="--xh-alert-border: transparent">
      <XhAlertTitle>无描边</XhAlertTitle>
      <XhAlertDescription>底色与内边距都还在。</XhAlertDescription>
    </XhAlertRoot>

    <!-- 只留描边：底色换成透明 -->
    <XhAlertRoot tone="warning" style="--xh-alert-bg: transparent">
      <XhAlertTitle>无底色</XhAlertTitle>
      <XhAlertDescription>剩一圈线，衬在页面本来的底色上。</XhAlertDescription>
    </XhAlertRoot>

    <!-- 语气表以外的配色逐个实例给，圆角也是一个槽位 -->
    <XhAlertRoot
      style="
        --xh-alert-bg: #f4f0ff;
        --xh-alert-border: #c4b5fd;
        --xh-alert-title-fg: #5b21b6;
        --xh-alert-radius: var(--xh-radius-none);
      "
    >
      <XhAlertTitle>自定配色</XhAlertTitle>
      <XhAlertDescription>底色、描边、标题色、圆角各占一个槽位。</XhAlertDescription>
    </XhAlertRoot>
  </div>
</template>

产物

层	值
自定义元素	<xh-alert>
Vue 组件	XhAlertCloseTrigger XhAlertDescription XhAlertIcon XhAlertRoot XhAlertTitle
状态机	alertMachine
皮肤	@xihan-ui/styles/alert.css

解剖

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

data-scope="alert"：root · icon · title · description · close-trigger

Props

属性	类型	必填	说明
tone	Tone		语气：brand / neutral / success / warning / danger / info，决定用哪族颜色，默认 info。 danger / warning 走 role="alert"，其余走 role="status"。
closable	boolean		关闭按钮是否可用，默认 true。false 时该按钮同时被禁用与收起。
open	boolean		受控显隐；缺省该 prop 即非受控。
defaultOpen	boolean		非受控初始显隐，默认显示。
onOpenChange	(details: AlertOpenChangeDetails) => void		open 变化意图回调；受控时是唯一出口，非受控随内部转移一并通知。
translations	Partial<AlertTranslations>

状态机

状态：open · closed

事件：OPEN · CLOSE · CONTROLLED.OPEN · CONTROLLED.CLOSE

判据：isOpenControlled

connect API

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

成员	类型	说明
open	boolean
tone	string
closable	boolean
setOpen	(next: boolean) => void
getRootProps	() => T['element']
getIconProps	() => T['element']
getTitleProps	() => T['element']
getDescriptionProps	() => T['element']
getCloseTriggerProps	() => T['button']

键盘

规格出处：W3C APG

按键	生效条件	行为
Enter / Space	focus 在 close-trigger 上且 closable	收起提示并通知 open=false