无限滚动 infinite-scroll

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

示例

基础用法

哨兵滚进可视区就派 load，取完把 loading 写回 false

第 1 条

第 2 条

第 3 条

第 4 条

第 5 条

第 6 条

第 7 条

第 8 条

第 9 条

第 10 条

第 11 条

第 12 条

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

const scrollEl = ref<HTMLElement | null>(null);
const items = ref(Array.from({ length: 12 }, (_, i) => `第 ${i + 1} 条`));
const loading = ref(false);

// 取下一页；这里用定时器代替真实请求
function onLoad(): void {
  loading.value = true;
  window.setTimeout(() => {
    const base = items.value.length;
    for (let i = 1; i <= 8; i += 1) items.value.push(`第 ${base + i} 条`);
    loading.value = false;
  }, 500);
}
</script>

<template>
  <div
    ref="scrollEl"
    style="
      block-size: 240px;
      overflow: auto;
      border: 1px solid var(--xh-border-default);
      border-radius: 8px;
    "
  >
    <!-- target 指向真正在滚的那层；不给就以窗口视口为准 -->
    <XhInfiniteScrollRoot :target="scrollEl" :loading="loading" @load="onLoad">
      <div v-for="item in items" :key="item" style="padding: 8px 12px">{{ item }}</div>
      <p v-if="loading" style="margin: 0; padding: 8px 12px; color: var(--xh-fg-muted)">
        正在取下一页…
      </p>
      <!-- 哨兵摆在列表最后一条之后 -->
      <XhInfiniteScrollSentinel />
    </XhInfiniteScrollRoot>
  </div>
</template>

提前量

distance 把可视区沿块轴向外扩，哨兵还没露头就先取下一页

提前 200px 触发 · 已取 0 页

第 1 条

第 2 条

第 3 条

第 4 条

第 5 条

第 6 条

第 7 条

第 8 条

第 9 条

第 10 条

第 11 条

第 12 条

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

const scrollEl = ref<HTMLElement | null>(null);
const distance = ref(200);
const items = ref(Array.from({ length: 12 }, (_, i) => `第 ${i + 1} 条`));
const loading = ref(false);
const rounds = ref(0);

function onLoad(): void {
  loading.value = true;
  window.setTimeout(() => {
    const base = items.value.length;
    for (let i = 1; i <= 8; i += 1) items.value.push(`第 ${base + i} 条`);
    rounds.value += 1;
    loading.value = false;
  }, 400);
}
</script>

<template>
  <div style="display: grid; gap: 12px; inline-size: 100%">
    <label style="display: flex; align-items: center; gap: 8px">
      提前
      <input v-model.number="distance" type="range" min="0" max="400" step="50" />
      {{ distance }}px 触发 · 已取 {{ rounds }} 页
    </label>

    <div
      ref="scrollEl"
      style="
        block-size: 220px;
        overflow: auto;
        border: 1px solid var(--xh-border-default);
        border-radius: 8px;
      "
    >
      <!-- 提前量扩的是 target 那块可视区，容器滚动必须把容器交出来 -->
      <XhInfiniteScrollRoot
        :target="scrollEl"
        :distance="distance"
        :loading="loading"
        @load="onLoad"
      >
        <div v-for="item in items" :key="item" style="padding: 8px 12px">{{ item }}</div>
        <XhInfiniteScrollSentinel />
      </XhInfiniteScrollRoot>
    </div>
  </div>
</template>

取到没有了

最后一页取完把 disabled 打开，哨兵不再被观察，load 也不再派

第 1 条

第 2 条

第 3 条

第 4 条

第 5 条

第 6 条

第 7 条

第 8 条

第 9 条

第 10 条

第 1 / 3 页 · 共 10 条

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

const scrollEl = ref<HTMLElement | null>(null);
const maxPage = 3;
const page = ref(1);
const items = ref(Array.from({ length: 10 }, (_, i) => `第 ${i + 1} 条`));
const loading = ref(false);

function onLoad(): void {
  loading.value = true;
  window.setTimeout(() => {
    const base = items.value.length;
    for (let i = 1; i <= 6; i += 1) items.value.push(`第 ${base + i} 条`);
    page.value += 1;
    loading.value = false;
  }, 400);
}
</script>

<template>
  <div style="display: grid; gap: 12px; inline-size: 100%">
    <div
      ref="scrollEl"
      style="
        block-size: 220px;
        overflow: auto;
        border: 1px solid var(--xh-border-default);
        border-radius: 8px;
      "
    >
      <XhInfiniteScrollRoot
        :target="scrollEl"
        :loading="loading"
        :disabled="page >= maxPage"
        @load="onLoad"
      >
        <div v-for="item in items" :key="item" style="padding: 8px 12px">{{ item }}</div>
        <p v-if="loading" style="margin: 0; padding: 8px 12px; color: var(--xh-fg-muted)">
          正在取下一页…
        </p>
        <p v-else-if="page >= maxPage" style="margin: 0; padding: 8px 12px; color: var(--xh-fg-muted)">
          没有更多了
        </p>
        <XhInfiniteScrollSentinel />
      </XhInfiniteScrollRoot>
    </div>

    <span>第 {{ page }} / {{ maxPage }} 页 · 共 {{ items.length }} 条</span>
  </div>
</template>

默认插槽透出状态

phase / loading / disabled 从插槽拿，加载提示与结束语都由宿主自己摆

第 1 条

第 2 条

第 3 条

第 4 条

第 5 条

第 6 条

第 7 条

第 8 条

第 9 条

第 10 条

继续往下滚（当前 idle）

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

const scrollEl = ref<HTMLElement | null>(null);
const items = ref(Array.from({ length: 10 }, (_, i) => `第 ${i + 1} 条`));
const loading = ref(false);
const done = ref(false);

function onLoad(): void {
  loading.value = true;
  window.setTimeout(() => {
    const base = items.value.length;
    for (let i = 1; i <= 6; i += 1) items.value.push(`第 ${base + i} 条`);
    done.value = items.value.length >= 28;
    loading.value = false;
  }, 400);
}
</script>

<template>
  <div
    ref="scrollEl"
    style="
      block-size: 240px;
      overflow: auto;
      border: 1px solid var(--xh-border-default);
      border-radius: 8px;
    "
  >
    <XhInfiniteScrollRoot
      v-slot="{ phase, loading: busy, disabled }"
      :target="scrollEl"
      :loading="loading"
      :disabled="done"
      @load="onLoad"
    >
      <div v-for="item in items" :key="item" style="padding: 8px 12px">{{ item }}</div>

      <p style="margin: 0; padding: 8px 12px; color: var(--xh-fg-muted)">
        <template v-if="busy">正在取下一页…</template>
        <template v-else-if="disabled">没有更多了</template>
        <template v-else>继续往下滚（当前 {{ phase }}）</template>
      </p>

      <XhInfiniteScrollSentinel />
    </XhInfiniteScrollRoot>
  </div>
</template>

产物

层	值
自定义元素	<xh-infinite-scroll>
Vue 组件	XhInfiniteScrollRoot XhInfiniteScrollSentinel
组合式函数	useInfiniteScroll
状态机	无，connect 直接由 props 算属性
皮肤	@xihan-ui/styles/infinite-scroll.css

解剖

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

data-scope="infinite-scroll"：root · sentinel

Props

属性	类型	必填	说明
distance	number		提前量（px）：哨兵离可视区还有这么远就算进入，默认 0（真正露头才算）。扩的是 getTargetEl 给出的那块可视区。
disabled	boolean		关掉：不再观察，也不再触发。列表已经没有下一页时用它。
loading	boolean		正在取数：其间不观察、不重复触发。取完由宿主写回 false。
onLoad	() => void		该取下一页了。

状态机

事件：SENTINEL.ENTER · MODE.SYNC

判据：isPaused · isLoading

connect API

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

成员	类型	说明
phase	InfiniteScrollPhase
loading	boolean	正在取数。
disabled	boolean	已关掉，不再观察。
getRootProps	() => T['element']
getSentinelProps	() => T['element']

键盘

规格出处：W3C APG

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