空状态 empty-state

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

示例

基础用法

图标、标题、说明、操作四个槽都可选，只有 root 是必须的

∅

还没有任何工单

新建一条工单，或者换个筛选条件再看看。

<script setup lang="ts">
import {
  XhButton,
  XhEmptyStateAction,
  XhEmptyStateDescription,
  XhEmptyStateIcon,
  XhEmptyStateRoot,
  XhEmptyStateTitle,
} from "@xihan-ui/vue";
</script>

<template>
  <XhEmptyStateRoot style="inline-size: 100%">
    <!-- 图标是装饰性的，内容由作者塞：字形、内联 svg 都行 -->
    <XhEmptyStateIcon>∅</XhEmptyStateIcon>
    <XhEmptyStateTitle>还没有任何工单</XhEmptyStateTitle>
    <XhEmptyStateDescription>
      新建一条工单，或者换个筛选条件再看看。
    </XhEmptyStateDescription>
    <XhEmptyStateAction>
      <XhButton variant="solid">新建工单</XhButton>
      <XhButton variant="ghost">清空筛选</XhButton>
    </XhEmptyStateAction>
  </XhEmptyStateRoot>
</template>

尺寸

size 只换留白与字号，语义一点不动；不传即 md

∅

sm

塞进侧栏或卡片里的那一档。

∅

md

缺省档，列表与表格用它。

∅

lg

整页只有这一块时用它。

<script setup lang="ts">
import {
  XhEmptyStateDescription,
  XhEmptyStateIcon,
  XhEmptyStateRoot,
  XhEmptyStateTitle,
} from "@xihan-ui/vue";
</script>

<template>
  <XhEmptyStateRoot size="sm" style="inline-size: 220px">
    <XhEmptyStateIcon>∅</XhEmptyStateIcon>
    <XhEmptyStateTitle>sm</XhEmptyStateTitle>
    <XhEmptyStateDescription>塞进侧栏或卡片里的那一档。</XhEmptyStateDescription>
  </XhEmptyStateRoot>

  <XhEmptyStateRoot style="inline-size: 220px">
    <XhEmptyStateIcon>∅</XhEmptyStateIcon>
    <XhEmptyStateTitle>md</XhEmptyStateTitle>
    <XhEmptyStateDescription>缺省档，列表与表格用它。</XhEmptyStateDescription>
  </XhEmptyStateRoot>

  <XhEmptyStateRoot size="lg" style="inline-size: 220px">
    <XhEmptyStateIcon>∅</XhEmptyStateIcon>
    <XhEmptyStateTitle>lg</XhEmptyStateTitle>
    <XhEmptyStateDescription>整页只有这一块时用它。</XhEmptyStateDescription>
  </XhEmptyStateRoot>
</template>

播报方式

缺省 polite 让 root 成为活区，筛完就地播报；off 让它只是个普通容器

∅

没有匹配「曦寒」的结果

换个词，或者去掉几个筛选条件。

<script setup lang="ts">
import { ref } from "vue";
import {
  XhEmptyStateDescription,
  XhEmptyStateIcon,
  XhEmptyStateRoot,
  XhEmptyStateTitle,
} from "@xihan-ui/vue";

const keyword = ref("曦寒");
const hits = ref<string[]>([]);

function search(): void {
  // 演示用：偶数长度的关键词当作有结果
  hits.value = keyword.value.length % 2 === 0 ? ["一条命中的记录"] : [];
}
</script>

<template>
  <div style="inline-size: 100%; display: grid; gap: 12px">
    <div style="display: flex; gap: 8px">
      <input v-model="keyword" type="search" aria-label="关键词" />
      <button type="button" @click="search">搜索</button>
    </div>

    <!-- 结果换成空的那一刻，读屏会在不打断当前朗读的前提下把标题念出来 -->
    <XhEmptyStateRoot v-if="!hits.length" live="polite">
      <XhEmptyStateIcon>∅</XhEmptyStateIcon>
      <XhEmptyStateTitle>没有匹配「{{ keyword }}」的结果</XhEmptyStateTitle>
      <XhEmptyStateDescription>换个词，或者去掉几个筛选条件。</XhEmptyStateDescription>
    </XhEmptyStateRoot>
    <p v-else style="margin: 0">{{ hits[0] }}</p>
  </div>
</template>

用作结果页

同一套部件也承载 404、403 这类结果：换掉图标与文案，操作槽里放回退出口

?

404 页面不存在

地址可能敲错了，或者这条记录已经被删掉。

⊘

403 没有权限

这块内容需要更高的角色，找管理员要一下。

!

500 服务出错

请求没能处理完，稍后再试一次。

<script setup lang="ts">
import {
  XhButton,
  XhEmptyStateAction,
  XhEmptyStateDescription,
  XhEmptyStateIcon,
  XhEmptyStateRoot,
  XhEmptyStateTitle,
} from "@xihan-ui/vue";

const results = [
  {
    glyph: "?",
    title: "404 页面不存在",
    description: "地址可能敲错了，或者这条记录已经被删掉。",
    action: "回到首页",
  },
  {
    glyph: "⊘",
    title: "403 没有权限",
    description: "这块内容需要更高的角色，找管理员要一下。",
    action: "申请权限",
  },
  {
    glyph: "!",
    title: "500 服务出错",
    description: "请求没能处理完，稍后再试一次。",
    action: "重试",
  },
];
</script>

<template>
  <!-- 随页面一起出现的静态结果，不是就地更新的活区，所以关掉播报 -->
  <XhEmptyStateRoot
    v-for="r in results"
    :key="r.title"
    live="off"
    size="sm"
    style="inline-size: 240px"
  >
    <XhEmptyStateIcon>{{ r.glyph }}</XhEmptyStateIcon>
    <XhEmptyStateTitle>{{ r.title }}</XhEmptyStateTitle>
    <XhEmptyStateDescription>{{ r.description }}</XhEmptyStateDescription>
    <XhEmptyStateAction>
      <XhButton size="sm" variant="outline">{{ r.action }}</XhButton>
    </XhEmptyStateAction>
  </XhEmptyStateRoot>
</template>

按语气着色

空状态自己不带语气，图标槽里放一枚带 tone 的图标，成功、警示、出错就各是一族颜色

全部导入成功

128 条记录已入库，没有需要人工处理的行。

部分行被跳过

有 6 行缺少必填字段，这次没有导入它们。

导入没有完成

文件读到一半中断，这次改动已经整体回滚。

<script setup lang="ts">
import {
  XhButton,
  XhEmptyStateAction,
  XhEmptyStateDescription,
  XhEmptyStateIcon,
  XhEmptyStateRoot,
  XhEmptyStateTitle,
  XhIcon,
} from "@xihan-ui/vue";

const CheckCircleIcon = {
  name: "check-circle",
  viewBox: "0 0 24 24",
  attrs: {
    "fill": "none",
    "stroke": "currentColor",
    "stroke-width": "2",
    "stroke-linecap": "round",
    "stroke-linejoin": "round",
  },
  nodes: [
    { tag: "circle", attrs: { cx: "12", cy: "12", r: "9" } },
    { tag: "path", attrs: { d: "M8 12.5L11 15.5L16 9" } },
  ],
} as const;

const AlertIcon = {
  name: "alert",
  viewBox: "0 0 24 24",
  attrs: {
    "fill": "none",
    "stroke": "currentColor",
    "stroke-width": "2",
    "stroke-linecap": "round",
    "stroke-linejoin": "round",
  },
  nodes: [
    { tag: "path", attrs: { d: "M12 4L21 19H3Z" } },
    { tag: "path", attrs: { d: "M12 10V14" } },
    { tag: "path", attrs: { d: "M12 16.5V17" } },
  ],
} as const;

const CrossCircleIcon = {
  name: "cross-circle",
  viewBox: "0 0 24 24",
  attrs: {
    "fill": "none",
    "stroke": "currentColor",
    "stroke-width": "2",
    "stroke-linecap": "round",
    "stroke-linejoin": "round",
  },
  nodes: [
    { tag: "circle", attrs: { cx: "12", cy: "12", r: "9" } },
    { tag: "path", attrs: { d: "M9 9L15 15" } },
    { tag: "path", attrs: { d: "M15 9L9 15" } },
  ],
} as const;

const results = [
  {
    icon: CheckCircleIcon,
    tone: "success",
    title: "全部导入成功",
    description: "128 条记录已入库，没有需要人工处理的行。",
    action: "查看结果",
  },
  {
    icon: AlertIcon,
    tone: "warning",
    title: "部分行被跳过",
    description: "有 6 行缺少必填字段，这次没有导入它们。",
    action: "下载跳过清单",
  },
  {
    icon: CrossCircleIcon,
    tone: "danger",
    title: "导入没有完成",
    description: "文件读到一半中断，这次改动已经整体回滚。",
    action: "重新上传",
  },
];
</script>

<template>
  <!-- 图标槽收任意内容，放一枚带语气的图标，着色就落在这一处，标题与说明不动 -->
  <XhEmptyStateRoot
    v-for="r in results"
    :key="r.title"
    live="off"
    size="sm"
    style="inline-size: 240px"
  >
    <XhEmptyStateIcon>
      <XhIcon :icon="r.icon" :tone="r.tone" size="lg" />
    </XhEmptyStateIcon>
    <XhEmptyStateTitle>{{ r.title }}</XhEmptyStateTitle>
    <XhEmptyStateDescription>{{ r.description }}</XhEmptyStateDescription>
    <XhEmptyStateAction>
      <XhButton size="sm" variant="outline">{{ r.action }}</XhButton>
    </XhEmptyStateAction>
  </XhEmptyStateRoot>
</template>

产物

层	值
自定义元素	<xh-empty-state>
Vue 组件	XhEmptyStateAction XhEmptyStateDescription XhEmptyStateIcon XhEmptyStateRoot XhEmptyStateTitle
状态机	无，connect 直接由 props 算属性
皮肤	@xihan-ui/styles/empty-state.css

解剖

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

data-scope="empty-state"：root · icon · title · description · action

Props

属性	类型	必填	说明
live	EmptyStateLive		缺省 polite。
size	Size		尺寸档位，只改留白与字号，不改语义。

connect API

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

成员	类型	说明
live	EmptyStateLive	生效的播报方式，缺省补齐后的值。
getRootProps	() => T['element']
getIconProps	() => T['element']
getTitleProps	() => T['element']
getDescriptionProps	() => T['element']
getActionProps	() => T['element']

键盘

规格出处：W3C APG

无键盘交互（不接收焦点，或焦点行为完全由原生元素提供）。