徽标 badge

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

示例

变体

badge 没有状态机，connect 直接由 props 算属性

已发布草稿归档

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

<template>
  <XhBadge variant="solid">已发布</XhBadge>
  <XhBadge variant="subtle">草稿</XhBadge>
  <XhBadge variant="outline">归档</XhBadge>
</template>

用作状态标记

徽标不接收焦点、也不进 Tab 序列，状态语义靠文字本身表达

构建 #182运行中

构建 #181已完成

构建 #180已取消

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

const rows = [
  { name: "构建 #182", state: "运行中", variant: "solid" as const },
  { name: "构建 #181", state: "已完成", variant: "subtle" as const },
  { name: "构建 #180", state: "已取消", variant: "outline" as const },
];
</script>

<template>
  <div style="display: grid; gap: 8px">
    <div v-for="r in rows" :key="r.name" style="display: flex; align-items: center; gap: 10px">
      <span style="min-width: 90px">{{ r.name }}</span>
      <XhBadge :variant="r.variant">{{ r.state }}</XhBadge>
    </div>
  </div>
</template>

形态

variant 决定颜色怎么用：实心填底、淡色填底、只描边

solidsubtleoutline

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

const variants = ["solid", "subtle", "outline"] as const;
</script>

<template>
  <XhBadge v-for="v in variants" :key="v" :variant="v">{{ v }}</XhBadge>
</template>

语气

tone 决定用哪族颜色，与 variant 正交；这里固定 solid 形态只看语气的差别

brandneutralsuccesswarningdangerinfo

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

const tones = ["brand", "neutral", "success", "warning", "danger", "info"] as const;
</script>

<template>
  <XhBadge v-for="t in tones" :key="t" variant="solid" :tone="t">{{ t }}</XhBadge>
</template>

尺寸

size 只改内边距与字号，不写就是缺省档

小缺省大

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

<template>
  <div style="display: flex; align-items: center; gap: 8px">
    <XhBadge variant="subtle" size="sm">小</XhBadge>
    <XhBadge variant="subtle">缺省</XhBadge>
    <XhBadge variant="subtle" size="lg">大</XhBadge>
  </div>
</template>

带图元的标签

根是 inline-flex 且自带间距，图标或头像直接写进默认插槽跟文字并排

已通过 校验完成 曦 曦寒

<script setup lang="ts">
import { XhAvatarFallback, XhAvatarImage, XhAvatarRoot, XhBadge, XhIcon } from "@xihan-ui/vue";

const CheckIcon = {
  name: "check",
  viewBox: "0 0 24 24",
  attrs: {
    "fill": "none",
    "stroke": "currentColor",
    "stroke-width": "2",
    "stroke-linecap": "round",
    "stroke-linejoin": "round",
  },
  nodes: [{ tag: "path", attrs: { d: "M4 12.5L9.5 18L20 6" } }],
} as const;
</script>

<template>
  <!-- 图标取 currentColor，颜色跟着标签的语气走 -->
  <XhBadge variant="subtle" tone="success">
    <XhIcon :icon="CheckIcon" size="sm" />已通过
  </XhBadge>

  <XhBadge variant="outline" tone="info" size="lg">
    <XhIcon :icon="CheckIcon" size="sm" />校验完成
  </XhBadge>

  <!-- 头像缩到跟文字一档：直径与字号各是一个组件令牌 -->
  <XhBadge variant="outline" size="lg">
    <XhAvatarRoot
      src="/images/logo.png"
      alt="曦寒"
      style="--xh-avatar-size: 18px; --xh-avatar-font-size: 10px"
    >
      <XhAvatarImage />
      <XhAvatarFallback>曦</XhAvatarFallback>
    </XhAvatarRoot>
    曦寒
  </XhBadge>
</template>

自定义配色

不写 variant 时底色与文字色取自组件令牌；描边这一条直接写 border-color

葡萄火烈鸟 只描边

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

<template>
  <XhBadge style="--xh-badge-bg: #8a2be2; --xh-badge-fg: #ffffff">葡萄</XhBadge>

  <XhBadge style="--xh-badge-bg: #ffe4f0; --xh-badge-fg: #b3306e">火烈鸟</XhBadge>

  <!-- 底色留白、只留一圈描边 -->
  <XhBadge style="--xh-badge-bg: transparent; --xh-badge-fg: #555555; border-color: #555555">
    只描边
  </XhBadge>
</template>

挂成角标

徽标本身随文排；外层套一层定位上下文，它就落到子元素的角上。计数、圆点、0 值收起、上限截断都在宿主这一侧

5

当前 5：为 0 收起，超过 99 截成 99+

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

const count = ref(5);
const max = 99;
</script>

<template>
  <div style="display: flex; align-items: center; gap: 24px">
    <!-- 计数角标：外层给定位上下文，徽标绝对定位到右上角；偏移逐个实例写 -->
    <span style="position: relative; display: inline-flex">
      <XhButton variant="outline">消息</XhButton>
      <XhBadge
        v-if="count > 0"
        variant="solid"
        tone="danger"
        size="sm"
        style="position: absolute; inset-block-start: -6px; inset-inline-end: -8px"
      >
        {{ count > max ? max + "+" : count }}
      </XhBadge>
    </span>

    <!-- 圆点：内容留空，内边距收成 0 再给一个直径，根本来就是胶囊圆角 -->
    <span style="position: relative; display: inline-flex">
      <XhButton variant="outline">动态</XhButton>
      <XhBadge
        variant="solid"
        tone="danger"
        style="
          position: absolute;
          inset-block-start: -4px;
          inset-inline-end: -4px;
          padding: 0;
          inline-size: 8px;
          block-size: 8px;
        "
      />
    </span>
  </div>

  <div style="display: flex; align-items: center; gap: 8px">
    <XhButton size="sm" @click="count = Math.max(0, count - 1)">减一</XhButton>
    <XhButton size="sm" @click="count += 50">加五十</XhButton>
    <XhButton size="sm" variant="ghost" @click="count = 0">归零</XhButton>
    <span style="font-size: 13px">当前 {{ count }}：为 0 收起，超过 {{ max }} 截成 {{ max }}+</span>
  </div>
</template>

可关闭标签

根是 inline-flex 且自带间距，关闭件直接写进默认插槽跟文字并排；点击语义、Tab 停靠与回车触发由原生按钮自带

设计 前端 无头内核 可访问性

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

const all = ["设计", "前端", "无头内核", "可访问性"];
const tags = ref([...all]);

function remove(tag: string) {
  tags.value = tags.value.filter((t) => t !== tag);
}
</script>

<template>
  <div style="display: flex; flex-wrap: wrap; align-items: center; gap: 8px">
    <XhBadge v-for="tag in tags" :key="tag" variant="subtle" tone="brand">
      {{ tag }}
      <!-- 关闭件的名字给全，读屏念到的是「移除 前端」而不是一个叉 -->
      <button
        type="button"
        :aria-label="'移除 ' + tag"
        style="
          display: inline-flex;
          align-items: center;
          justify-content: center;
          padding: 0;
          border: 0;
          background: transparent;
          color: inherit;
          font: inherit;
          line-height: 1;
          cursor: pointer;
        "
        @click="remove(tag)"
      >
        ×
      </button>
    </XhBadge>

    <span v-if="!tags.length" style="font-size: 13px">已全部移除</span>

    <XhButton
      v-if="tags.length < all.length"
      size="sm"
      variant="ghost"
      @click="tags = [...all]"
    >
      还原
    </XhButton>
  </div>
</template>

产物

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

解剖

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

data-scope="badge"：root

Props

属性	类型	必填	说明
size	Size		尺寸：sm / md / lg
tone	Tone		语气：brand / neutral / success / warning / danger / info，决定用哪族颜色
variant	BadgeVariant

connect API

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

成员	类型	说明
getRootProps	() => T['element']

键盘

规格出处：W3C APG

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