文本省略 ellipsis

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

示例

基础用法

一行放不下就收成省略号；有没有被裁如实报出来

容器宽度 240px

订单 2024-0731-8842 已由杭州仓发出，预计明日 18:00 前送达，签收前请当面核对包装。

此刻 整段都放得下

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

const width = ref(240);
const overflowing = ref(false);
const text =
  "订单 2024-0731-8842 已由杭州仓发出，预计明日 18:00 前送达，签收前请当面核对包装。";
</script>

<template>
  <div style="display: grid; gap: 12px; inline-size: 100%">
    <label style="display: flex; align-items: center; gap: 8px">
      容器宽度
      <input v-model.number="width" type="range" min="120" max="640" step="20" />
      {{ width }}px
    </label>

    <!-- 盒子越窄裁得越多。量测跟着容器尺寸走，拖动过程中结论一直是准的 -->
    <div :style="{ inlineSize: `${width}px`, maxInlineSize: '100%' }">
      <XhEllipsis @overflow-change="overflowing = $event.overflowing">
        {{ text }}
      </XhEllipsis>
    </div>

    <p style="margin: 0; color: var(--xh-fg-muted)">
      此刻 {{ overflowing ? "被裁掉了一截" : "整段都放得下" }}
    </p>
  </div>
</template>

行数

lines 为 1 走单行省略，大于 1 按行数裁，末行收省略号

夹几行 2

这条商品说明写得很长：材质为 100% 长绒棉，机洗需用中性洗涤剂，不可漂白，低温熨烫，深浅色分开洗涤，首次下水建议单独清洗以免染色。

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

const lines = ref(2);
const text =
  "这条商品说明写得很长：材质为 100% 长绒棉，机洗需用中性洗涤剂，不可漂白，" +
  "低温熨烫，深浅色分开洗涤，首次下水建议单独清洗以免染色。";
</script>

<template>
  <div style="display: grid; gap: 12px; inline-size: 100%; max-inline-size: 420px">
    <label style="display: flex; align-items: center; gap: 8px">
      夹几行
      <input v-model.number="lines" type="range" min="1" max="5" step="1" />
      {{ lines }}
    </label>

    <!-- 换行数就是换了一把尺，组件会自己重量一次，不必手动触发 -->
    <XhEllipsis :lines="lines">{{ text }}</XhEllipsis>
  </div>
</template>

点击展开

expandable 让整块文字变成一颗按钮，Enter / Space 也按得动

这次更新把导出改成了后台任务：点导出后先落一条记录，处理完再推通知，中途关掉页面也不影响；文件保留 7 天，过期由清理任务回收。

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

const expanded = ref(false);
const text =
  "这次更新把导出改成了后台任务：点导出后先落一条记录，处理完再推通知，" +
  "中途关掉页面也不影响；文件保留 7 天，过期由清理任务回收。";
</script>

<template>
  <div style="display: grid; gap: 12px; inline-size: 100%; max-inline-size: 420px">
    <!-- v-model:expanded 走受控：状态在外面，组件只发意图 -->
    <XhEllipsis v-model:expanded="expanded" :lines="2" expandable>
      {{ text }}
    </XhEllipsis>

    <button type="button" style="justify-self: start" @click="expanded = !expanded">
      {{ expanded ? "收回去" : "在外面展开" }}
    </button>
  </div>
</template>

溢出才提示

上面套 Tooltip 按 overflow-change 开关，下面用 tooltip 交给平台的原生提示

容器宽度 200px

配送地址：浙江省杭州市余杭区文一西路 969 号 3 号楼 12 层 1203 室

<script setup lang="ts">
import { ref } from "vue";
import {
  XhEllipsis,
  XhTooltipContent,
  XhTooltipPositioner,
  XhTooltipRoot,
  XhTooltipTrigger,
} from "@xihan-ui/vue";

const width = ref(200);
const overflowing = ref(false);
const text = "配送地址：浙江省杭州市余杭区文一西路 969 号 3 号楼 12 层 1203 室";

// 触发器本身是按钮，这里让它按普通文字那样铺满一行
const asText = {
  display: "block",
  inlineSize: "100%",
  padding: "0",
  border: "0",
  background: "none",
  font: "inherit",
  color: "inherit",
  textAlign: "start",
  cursor: "default",
};
</script>

<template>
  <div style="display: grid; gap: 16px; inline-size: 100%">
    <label style="display: flex; align-items: center; gap: 8px">
      容器宽度
      <input v-model.number="width" type="range" min="120" max="560" step="20" />
      {{ width }}px
    </label>

    <!-- 组件只报「被裁了没有」，浮层归 Tooltip；没被裁时把提示整个关掉 -->
    <div :style="{ inlineSize: `${width}px`, maxInlineSize: '100%' }">
      <XhTooltipRoot :disabled="!overflowing">
        <XhTooltipTrigger :style="asText">
          <XhEllipsis @overflow-change="overflowing = $event.overflowing">
            {{ text }}
          </XhEllipsis>
        </XhTooltipTrigger>
        <XhTooltipPositioner>
          <XhTooltipContent>{{ text }}</XhTooltipContent>
        </XhTooltipPositioner>
      </XhTooltipRoot>
    </div>

    <!-- 不想要浮层就开 tooltip：被裁时整段文字写进 title，交给平台自己的提示 -->
    <div :style="{ inlineSize: `${width}px`, maxInlineSize: '100%' }">
      <XhEllipsis tooltip>{{ text }}</XhEllipsis>
    </div>
  </div>
</template>

产物

层	值
自定义元素	<xh-ellipsis>
Vue 组件	XhEllipsis
组合式函数	useEllipsis
状态机	ellipsisMachine
皮肤	@xihan-ui/styles/ellipsis.css

解剖

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

data-scope="ellipsis"：root

Props

属性	类型	必填	说明
lines	number		夹几行，1 为单行，默认 1。
expandable	boolean		点一下铺开全文。
expanded	boolean		受控展开；缺省即非受控。
defaultExpanded	boolean		非受控时的初始展开态。
tooltip	boolean		真被裁掉了才把整段文字交给平台的原生提示。
onExpandedChange	(details: EllipsisExpandedChangeDetails) => void		expanded 变化意图回调；受控时是唯一出口，非受控随内部转移一并通知。
onOverflowChange	(details: EllipsisOverflowChangeDetails) => void		量出来的溢出结论翻面时回调。

状态机

状态：collapsed · expanded

事件：MEASURE · TOGGLE · CONTROLLED.EXPAND · CONTROLLED.COLLAPSE

判据：isExpandedControlled

connect API

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

成员	类型	说明
expanded	boolean	此刻是不是铺开了全文。
overflowing	boolean	夹住的那一版有没有被裁掉内容。作者据此决定要不要套一层提示。
setExpanded	(next: boolean) => void	程序化展开 / 收回，与点一下走同一条路。
measure	() => void	手动重量一次：字体到位、外层换了布局这类观察器看不见的变化，由作者补一枪。
getRootProps	() => T['element']

键盘

规格出处：W3C APG

按键	生效条件	行为
Enter / Space	expandable，焦点在 root 上	铺开全文 / 收回夹住的那一版；Space 拦掉翻页的默认动作
Tab / Shift+Tab	expandable	停到这块文字上；不可展开时它不带 tabindex，不在 Tab 序列里