会话线程 thread

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

示例

基础用法

root 的高度由外部给定，滚动才发生在 viewport 里面；root / viewport / content 三层缺一不可

用户：这个对话区是怎么分层的？

助手：root 定框，viewport 负责滚动，content 包住全部消息。

用户：为什么一定要给高度？

助手：不给一个确定的框，内容永远不溢出，滚动与粘底都无从谈起。

用户：消息本身归谁管？

助手：归你。组件不碰数据，content 里放什么都行。

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

const messages = [
  { id: 1, role: "用户", text: "这个对话区是怎么分层的？" },
  { id: 2, role: "助手", text: "root 定框，viewport 负责滚动，content 包住全部消息。" },
  { id: 3, role: "用户", text: "为什么一定要给高度？" },
  { id: 4, role: "助手", text: "不给一个确定的框，内容永远不溢出，滚动与粘底都无从谈起。" },
  { id: 5, role: "用户", text: "消息本身归谁管？" },
  { id: 6, role: "助手", text: "归你。组件不碰数据，content 里放什么都行。" },
];
</script>

<template>
  <div style="width: 100%">
    <!-- 高度写在 root 上：viewport 撑满剩余空间，溢出部分自己滚 -->
    <XhThreadRoot style="block-size: 220px">
      <XhThreadViewport>
        <XhThreadContent>
          <p v-for="m in messages" :key="m.id" style="margin: 0">
            <strong>{{ m.role }}：</strong>{{ m.text }}
          </p>
        </XhThreadContent>
      </XhThreadViewport>
    </XhThreadRoot>
  </div>
</template>

粘底与回到底部

内容长高时自动跟到底；往上滚一下当场撒手，回到底部按钮随即露出，滚回阈值内又自动粘上

用户：粘底是按什么判的？

助手：按滚动位置离底还差多少像素，差值落在阈值内就算在底。

用户：我自己往上滚一段呢？

助手：当场撒手，此后再长多少都不跟，右下角给你一条回去的路。

用户：滚回去要不要再点一下按钮？

助手：不用，滚进阈值内的那一下自动重新粘上。

在底：是 · 粘附：是

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

const messages = ref([
  { id: 1, role: "用户", text: "粘底是按什么判的？" },
  { id: 2, role: "助手", text: "按滚动位置离底还差多少像素，差值落在阈值内就算在底。" },
  { id: 3, role: "用户", text: "我自己往上滚一段呢？" },
  { id: 4, role: "助手", text: "当场撒手，此后再长多少都不跟，右下角给你一条回去的路。" },
  { id: 5, role: "用户", text: "滚回去要不要再点一下按钮？" },
  { id: 6, role: "助手", text: "不用，滚进阈值内的那一下自动重新粘上。" },
]);

let nextId = messages.value.length;
const atBottom = ref(true);
const sticking = ref(true);

function append(): void {
  nextId += 1;
  messages.value.push({
    id: nextId,
    role: "助手",
    text: `第 ${nextId} 条 · 粘着就跟到底，撒手了就停在原处等你回来。`,
  });
}

function onStickChange(details: { atBottom: boolean; sticking: boolean }): void {
  atBottom.value = details.atBottom;
  sticking.value = details.sticking;
}
</script>

<template>
  <div style="width: 100%; display: grid; gap: 12px">
    <!-- threshold 是距底多少像素算在底，默认 64 -->
    <XhThreadRoot
      style="block-size: 220px"
      :threshold="64"
      @stick-change="onStickChange"
    >
      <XhThreadViewport>
        <XhThreadContent>
          <p v-for="m in messages" :key="m.id" style="margin: 0">
            <strong>{{ m.role }}：</strong>{{ m.text }}
          </p>
        </XhThreadContent>
      </XhThreadViewport>
      <XhThreadScrollButton>↓ 回到底部</XhThreadScrollButton>
    </XhThreadRoot>

    <div>
      <XhButton variant="solid" @click="append">追加一条消息</XhButton>
      <span style="margin-inline-start: 12px">
        在底：{{ atBottom ? "是" : "否" }} · 粘附：{{ sticking ? "是" : "否" }}
      </span>
    </div>
  </div>
</template>

运行态与播报

status 由宿主持有，组件只把它透出成 data-status；viewport 恒 aria-live="off"，播报只发生在 live-region 里

用户：帮我写一段开场白。

status：idle

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

type Status = "idle" | "submitted" | "streaming" | "error";

const messages = ref([{ id: 1, role: "用户", text: "帮我写一段开场白。" }]);
const status = ref<Status>("idle");
// 播报只写整段最终文本：中途逐字写等于让读屏把同一段话越念越长
const liveText = ref("");

let timer = 0;

function run(): void {
  window.clearTimeout(timer);
  messages.value = [{ id: 1, role: "用户", text: "帮我写一段开场白。" }];
  liveText.value = "";
  status.value = "submitted";

  timer = window.setTimeout(() => {
    status.value = "streaming";
    messages.value.push({ id: 2, role: "助手", text: "好的，正在往下写…" });

    timer = window.setTimeout(() => {
      const text = "好的，这是一段开场白：欢迎来到曦寒设计系统。";
      messages.value[1] = { id: 2, role: "助手", text };
      status.value = "idle";
      // 一轮结束时一次性写进播报区
      liveText.value = text;
    }, 1200);
  }, 600);
}
</script>

<template>
  <div style="width: 100%; display: grid; gap: 12px">
    <XhThreadRoot style="block-size: 200px" :status="status">
      <XhThreadViewport>
        <XhThreadContent>
          <p v-for="m in messages" :key="m.id" style="margin: 0">
            <strong>{{ m.role }}：</strong>{{ m.text }}
          </p>
        </XhThreadContent>
      </XhThreadViewport>
      <XhThreadLiveRegion>{{ liveText }}</XhThreadLiveRegion>
    </XhThreadRoot>

    <div>
      <XhButton variant="solid" @click="run">跑一轮</XhButton>
      <XhButton variant="outline" @click="status = 'error'">置为 error</XhButton>
      <span style="margin-inline-start: 12px">status：{{ status }}</span>
    </div>
  </div>
</template>

触底加载更多

stick-change 报到底，宿主据此去取下一页；先往上滚一段再滚回底部，取回来的消息追加在后面

第 1 条 · 先往上滚一段，再滚回底部

第 2 条 · 先往上滚一段，再滚回底部

第 3 条 · 先往上滚一段，再滚回底部

第 4 条 · 先往上滚一段，再滚回底部

第 5 条 · 先往上滚一段，再滚回底部

第 6 条 · 先往上滚一段，再滚回底部

第 7 条 · 先往上滚一段，再滚回底部

第 8 条 · 先往上滚一段，再滚回底部

已加载 8 条 · 第 1 / 3 页

<script setup lang="ts">
import { ref } from "vue";
import {
  XhThreadContent,
  XhThreadRoot,
  XhThreadScrollButton,
  XhThreadViewport,
} from "@xihan-ui/vue";

const maxPage = 3;
const messages = ref(
  Array.from({ length: 8 }, (_, i) => ({
    id: i + 1,
    text: `第 ${i + 1} 条 · 先往上滚一段，再滚回底部`,
  })),
);
const page = ref(1);
const loading = ref(false);

// 到了底、手上没在取、还有下一页，三条都满足才发起这一次加载
function onStickChange(details: { atBottom: boolean; sticking: boolean }): void {
  if (!details.atBottom || loading.value || page.value >= maxPage)
    return;
  loading.value = true;
  window.setTimeout(() => {
    page.value += 1;
    const base = messages.value.length;
    for (let i = 1; i <= 4; i += 1) {
      messages.value.push({
        id: base + i,
        text: `第 ${base + i} 条 · 第 ${page.value} 页取回来的`,
      });
    }
    loading.value = false;
  }, 600);
}
</script>

<template>
  <div style="width: 100%; display: grid; gap: 12px">
    <XhThreadRoot style="block-size: 220px" @stick-change="onStickChange">
      <XhThreadViewport>
        <XhThreadContent>
          <p v-for="m in messages" :key="m.id" style="margin: 0">{{ m.text }}</p>
          <p v-if="loading" style="margin: 0">正在取下一页…</p>
          <p v-else-if="page >= maxPage" style="margin: 0">没有更多了</p>
        </XhThreadContent>
      </XhThreadViewport>
      <XhThreadScrollButton>↓ 回到底部</XhThreadScrollButton>
    </XhThreadRoot>

    <span>已加载 {{ messages.length }} 条 · 第 {{ page }} / {{ maxPage }} 页</span>
  </div>
</template>

自己画回到底部的入口

root 的作用域插槽给出 showScrollButton 与 scrollToBottom，不用内置那颗浮动按钮也能拼出一条自己的提示栏

第 1 条 · 往上滚一段，下面那条提示栏就露出来

第 2 条 · 往上滚一段，下面那条提示栏就露出来

第 3 条 · 往上滚一段，下面那条提示栏就露出来

第 4 条 · 往上滚一段，下面那条提示栏就露出来

第 5 条 · 往上滚一段，下面那条提示栏就露出来

第 6 条 · 往上滚一段，下面那条提示栏就露出来

第 7 条 · 往上滚一段，下面那条提示栏就露出来

第 8 条 · 往上滚一段，下面那条提示栏就露出来

第 9 条 · 往上滚一段，下面那条提示栏就露出来

第 10 条 · 往上滚一段，下面那条提示栏就露出来

第 11 条 · 往上滚一段，下面那条提示栏就露出来

第 12 条 · 往上滚一段，下面那条提示栏就露出来

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

const messages = ref(
  Array.from({ length: 12 }, (_, i) => ({
    id: i + 1,
    text: `第 ${i + 1} 条 · 往上滚一段，下面那条提示栏就露出来`,
  })),
);

let nextId = messages.value.length;

function append(): void {
  nextId += 1;
  messages.value.push({ id: nextId, text: `第 ${nextId} 条 · 新来的` });
}
</script>

<template>
  <div style="width: 100%; display: grid; gap: 12px">
    <XhThreadRoot v-slot="{ atBottom, showScrollButton, scrollToBottom }" style="block-size: 220px">
      <XhThreadViewport>
        <XhThreadContent>
          <p v-for="m in messages" :key="m.id" style="margin: 0">{{ m.text }}</p>
        </XhThreadContent>
      </XhThreadViewport>

      <!-- 提示栏排在视口下面，不在底部时才出现 -->
      <div
        v-if="showScrollButton"
        style="display: flex; align-items: center; justify-content: space-between; gap: 8px; padding-block: 6px"
      >
        <span style="font-size: 13px">在底：{{ atBottom ? "是" : "否" }}</span>
        <XhButton variant="outline" size="sm" @click="scrollToBottom()">回到最新</XhButton>
      </div>
    </XhThreadRoot>

    <div>
      <XhButton variant="solid" @click="append">追加一条消息</XhButton>
    </div>
  </div>
</template>

会话页

线程管滚动与粘底，编辑器管收话：发出去先落一条自己的消息，回话一段段写进来时消息区自动跟到底

助手：有什么想问的？

<script setup lang="ts">
import { ref } from "vue";
import {
  XhComposerInput,
  XhComposerRoot,
  XhComposerSubmitTrigger,
  XhThreadContent,
  XhThreadRoot,
  XhThreadScrollButton,
  XhThreadViewport,
} from "@xihan-ui/vue";

type Status = "idle" | "streaming";

const reply = "好的，这就往下写。消息一段段进来时，消息区跟着往下走；你要是自己滚上去看旧消息，它就停在那儿等你回来。";

const messages = ref([{ id: 1, role: "助手", text: "有什么想问的？" }]);
const status = ref<Status>("idle");

let nextId = 1;
let timer = 0;

function onSubmit(details: { value: string }): void {
  window.clearTimeout(timer);
  nextId += 1;
  messages.value.push({ id: nextId, role: "用户", text: details.value });
  nextId += 1;
  const replyId = nextId;
  messages.value.push({ id: replyId, role: "助手", text: "" });
  status.value = "streaming";

  let cut = 0;
  const step = (): void => {
    cut += 6;
    const target = messages.value.find(m => m.id === replyId);
    if (target)
      target.text = reply.slice(0, cut);
    if (cut < reply.length) {
      timer = window.setTimeout(step, 90);
      return;
    }
    status.value = "idle";
  };
  step();
}

// 停止只是不再往下写，已经写出来的那半段留在原处
function onStop(): void {
  window.clearTimeout(timer);
  status.value = "idle";
}
</script>

<template>
  <div style="width: 100%; display: grid; gap: 12px">
    <XhThreadRoot style="block-size: 240px" :status="status">
      <XhThreadViewport>
        <XhThreadContent>
          <p v-for="m in messages" :key="m.id" style="margin: 0">
            <strong>{{ m.role }}：</strong>{{ m.text }}
          </p>
        </XhThreadContent>
      </XhThreadViewport>
      <XhThreadScrollButton>↓ 回到底部</XhThreadScrollButton>
    </XhThreadRoot>

    <XhComposerRoot
      :run-status="status === 'streaming' ? 'streaming' : 'ready'"
      @submit="onSubmit"
      @stop="onStop"
    >
      <XhComposerInput placeholder="说点什么…" rows="1" />
      <XhComposerSubmitTrigger>
        {{ status === "streaming" ? "停止" : "发送" }}
      </XhComposerSubmitTrigger>
    </XhComposerRoot>
  </div>
</template>

向上加载更早的消息

视口的滚动事件直接监听：滚到接近顶部就去取上一页，取回来的插在最前面

第 33 条 · 会话记录

第 34 条 · 会话记录

第 35 条 · 会话记录

第 36 条 · 会话记录

第 37 条 · 会话记录

第 38 条 · 会话记录

第 39 条 · 会话记录

第 40 条 · 会话记录

已加载 8 条 · 最早到第 33 条

<script setup lang="ts">
import { ref } from "vue";
import {
  XhThreadContent,
  XhThreadRoot,
  XhThreadScrollButton,
  XhThreadViewport,
} from "@xihan-ui/vue";

function makeRange(from: number, count: number) {
  return Array.from({ length: count }, (_, i) => ({
    id: from + i,
    text: `第 ${from + i} 条 · 会话记录`,
  }));
}

// 编号越小越早，取历史就是往前减
const earliest = ref(33);
const messages = ref(makeRange(earliest.value, 8));
const loading = ref(false);
const hasMore = ref(true);

// 离顶部不到 48px 就取上一页；不在底部时内容增高会按锚点补偿，读到一半的位置不会被顶走
function onScroll(event: Event): void {
  const el = event.currentTarget as HTMLElement;
  if (el.scrollTop > 48 || loading.value || !hasMore.value)
    return;
  loading.value = true;
  window.setTimeout(() => {
    const size = Math.min(6, earliest.value - 1);
    earliest.value -= size;
    messages.value.unshift(...makeRange(earliest.value, size));
    hasMore.value = earliest.value > 1;
    loading.value = false;
  }, 500);
}
</script>

<template>
  <div style="width: 100%; display: grid; gap: 12px">
    <XhThreadRoot style="block-size: 220px">
      <XhThreadViewport @scroll="onScroll">
        <XhThreadContent>
          <p v-if="loading" style="margin: 0">正在取更早的…</p>
          <p v-else-if="!hasMore" style="margin: 0">已经是最早的了</p>
          <p v-for="m in messages" :key="m.id" style="margin: 0">{{ m.text }}</p>
        </XhThreadContent>
      </XhThreadViewport>
      <XhThreadScrollButton>↓ 回到底部</XhThreadScrollButton>
    </XhThreadRoot>

    <span>已加载 {{ messages.length }} 条 · 最早到第 {{ earliest }} 条</span>
  </div>
</template>

跳到指定的一条

视口节点与消息节点都在宿主手上：滚到顶、定位到某一条都是一次普通的 DOM 操作

第 1 条 · 会话记录

第 2 条 · 会话记录

第 3 条 · 会话记录

第 4 条 · 会话记录

第 5 条 · 会话记录

第 6 条 · 会话记录

第 7 条 · 会话记录

第 8 条 · 会话记录

第 9 条 · 会话记录

第 10 条 · 会话记录

第 11 条 · 会话记录

第 12 条 · 会话记录

第 13 条 · 会话记录

第 14 条 · 会话记录

第 15 条 · 会话记录

第 16 条 · 会话记录

第 17 条 · 会话记录

第 18 条 · 会话记录

第 19 条 · 会话记录

第 20 条 · 会话记录

第 21 条 · 会话记录

第 22 条 · 会话记录

第 23 条 · 会话记录

第 24 条 · 会话记录

（还没跳过）

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

const messages = Array.from({ length: 24 }, (_, i) => ({
  id: i + 1,
  text: `第 ${i + 1} 条 · 会话记录`,
}));
const jumped = ref("（还没跳过）");

let viewport: HTMLElement | null = null;
const items = new Map<number, HTMLElement>();

// 视口只渲染一个 div，实例上的 $el 就是那个滚动容器
function bindViewport(instance: unknown): void {
  viewport = (instance as { $el: HTMLElement } | null)?.$el ?? null;
}

function bindItem(id: number, el: unknown): void {
  if (el)
    items.set(id, el as HTMLElement);
  else
    items.delete(id);
}

function scrollToTop(): void {
  viewport?.scrollTo({ top: 0, behavior: "smooth" });
  jumped.value = "跳到了顶部";
}

function scrollToItem(id: number): void {
  const item = items.get(id);
  if (!viewport || !item)
    return;
  // 两个 offsetTop 同参照系，相减就是这一条在滚动内容里的位置
  viewport.scrollTo({ top: item.offsetTop - viewport.offsetTop, behavior: "smooth" });
  jumped.value = `跳到了第 ${id} 条`;
}
</script>

<template>
  <div style="width: 100%; display: grid; gap: 12px">
    <XhThreadRoot style="block-size: 220px">
      <XhThreadViewport :ref="bindViewport">
        <XhThreadContent>
          <p
            v-for="m in messages"
            :key="m.id"
            :ref="el => bindItem(m.id, el)"
            style="margin: 0"
          >
            {{ m.text }}
          </p>
        </XhThreadContent>
      </XhThreadViewport>
    </XhThreadRoot>

    <div style="display: flex; gap: 8px">
      <XhButton variant="outline" size="sm" @click="scrollToTop">回到顶部</XhButton>
      <XhButton variant="outline" size="sm" @click="scrollToItem(8)">跳到第 8 条</XhButton>
      <XhButton variant="outline" size="sm" @click="scrollToItem(20)">跳到第 20 条</XhButton>
    </div>
    <span>{{ jumped }}</span>
  </div>
</template>

产物

层	值
自定义元素	<xh-thread>
Vue 组件	XhThreadContent XhThreadLiveRegion XhThreadRoot XhThreadScrollButton XhThreadViewport
组合式函数	useThread
状态机	threadMachine
皮肤	@xihan-ui/styles/thread.css

解剖

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

data-scope="thread"：root · viewport · content · scroll-button · live-region

Props

属性	类型	必填	说明
status	ThreadStatus		这一轮的运行态，由宿主传入。
threshold	number		距底多少 px 视为在底，缺省用粘底原语的默认值。
translations	Partial<ThreadTranslations>
onStickChange	(details: ThreadStickChangeDetails) => void		粘底状态变化时通知宿主。

状态机

状态：idle

事件：STICK.CHANGE · SCROLL_TO_BOTTOM

connect API

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

成员	类型	说明
status	ThreadStatus
atBottom	boolean
sticking	boolean
showScrollButton	boolean	是否显示回到底部按钮，不在底部时为 true。
scrollToBottom	() => void
getRootProps	() => T['element']
getViewportProps	() => T['element']
getContentProps	() => T['element']
getScrollButtonProps	() => T['button']
getLiveRegionProps	() => T['element']

键盘

规格出处：W3C APG

按键	生效条件	行为
Tab	焦点进入消息区	消息区自身可聚焦，方向键/PageUp/PageDown 交给浏览器滚动，组件不接管
Space / Enter	焦点在"回到底部"按钮上	滚回底部并重新粘附