滚动区域 scroll-area

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

示例

基础用法

root 要有确定高度，视口才量得出溢出；滚动走的是浏览器原生通路，组件只画滚动条

第 1 行内容

第 2 行内容

第 3 行内容

第 4 行内容

第 5 行内容

第 6 行内容

第 7 行内容

第 8 行内容

第 9 行内容

第 10 行内容

第 11 行内容

第 12 行内容

第 13 行内容

第 14 行内容

第 15 行内容

第 16 行内容

第 17 行内容

第 18 行内容

第 19 行内容

第 20 行内容

第 21 行内容

第 22 行内容

第 23 行内容

第 24 行内容

第 25 行内容

第 26 行内容

第 27 行内容

第 28 行内容

第 29 行内容

第 30 行内容

<script setup lang="ts">
import {
  XhScrollAreaContent,
  XhScrollAreaRoot,
  XhScrollAreaScrollbar,
  XhScrollAreaThumb,
  XhScrollAreaViewport,
} from "@xihan-ui/vue";

const lines = Array.from({ length: 30 }, (_, i) => `第 ${i + 1} 行内容`);
</script>

<template>
  <XhScrollAreaRoot style="block-size: 180px; inline-size: 100%; max-inline-size: 420px">
    <XhScrollAreaViewport>
      <XhScrollAreaContent style="padding: 8px 12px">
        <p v-for="line in lines" :key="line" style="margin: 0; line-height: 24px">
          {{ line }}
        </p>
      </XhScrollAreaContent>
    </XhScrollAreaViewport>
    <XhScrollAreaScrollbar orientation="vertical">
      <XhScrollAreaThumb />
    </XhScrollAreaScrollbar>
  </XhScrollAreaRoot>
</template>

显隐时机

type 决定滚动条什么时候露面：hover 指针进来才露，always 恒露，scroll 滚动时露、停手后收起

type = hover

第 1 行

第 2 行

第 3 行

第 4 行

第 5 行

第 6 行

第 7 行

第 8 行

第 9 行

第 10 行

第 11 行

第 12 行

第 13 行

第 14 行

第 15 行

第 16 行

第 17 行

第 18 行

第 19 行

第 20 行

type = always

第 1 行

第 2 行

第 3 行

第 4 行

第 5 行

第 6 行

第 7 行

第 8 行

第 9 行

第 10 行

第 11 行

第 12 行

第 13 行

第 14 行

第 15 行

第 16 行

第 17 行

第 18 行

第 19 行

第 20 行

type = scroll

第 1 行

第 2 行

第 3 行

第 4 行

第 5 行

第 6 行

第 7 行

第 8 行

第 9 行

第 10 行

第 11 行

第 12 行

第 13 行

第 14 行

第 15 行

第 16 行

第 17 行

第 18 行

第 19 行

第 20 行

<script setup lang="ts">
import {
  XhScrollAreaContent,
  XhScrollAreaRoot,
  XhScrollAreaScrollbar,
  XhScrollAreaThumb,
  XhScrollAreaViewport,
} from "@xihan-ui/vue";

const types = ["hover", "always", "scroll"] as const;
const lines = Array.from({ length: 20 }, (_, i) => `第 ${i + 1} 行`);
</script>

<template>
  <div style="width: 100%; display: flex; flex-wrap: wrap; gap: 16px">
    <div v-for="type in types" :key="type" style="display: grid; gap: 6px">
      <span>type = {{ type }}</span>
      <XhScrollAreaRoot :type="type" style="block-size: 140px; inline-size: 180px">
        <XhScrollAreaViewport>
          <XhScrollAreaContent style="padding: 8px 12px">
            <p v-for="line in lines" :key="line" style="margin: 0; line-height: 22px">
              {{ line }}
            </p>
          </XhScrollAreaContent>
        </XhScrollAreaViewport>
        <XhScrollAreaScrollbar orientation="vertical">
          <XhScrollAreaThumb />
        </XhScrollAreaScrollbar>
      </XhScrollAreaRoot>
    </div>
  </div>
</template>

双轴与拐角

两条轴各写一条滚动条，corner 补上右下角那块空白；内容要比视口宽，横轴才量得出溢出

第 1 行 —— 这一行故意写得很长，长到横向也需要滚动才看得完整句话

第 2 行 —— 这一行故意写得很长，长到横向也需要滚动才看得完整句话

第 3 行 —— 这一行故意写得很长，长到横向也需要滚动才看得完整句话

第 4 行 —— 这一行故意写得很长，长到横向也需要滚动才看得完整句话

第 5 行 —— 这一行故意写得很长，长到横向也需要滚动才看得完整句话

第 6 行 —— 这一行故意写得很长，长到横向也需要滚动才看得完整句话

第 7 行 —— 这一行故意写得很长，长到横向也需要滚动才看得完整句话

第 8 行 —— 这一行故意写得很长，长到横向也需要滚动才看得完整句话

第 9 行 —— 这一行故意写得很长，长到横向也需要滚动才看得完整句话

第 10 行 —— 这一行故意写得很长，长到横向也需要滚动才看得完整句话

第 11 行 —— 这一行故意写得很长，长到横向也需要滚动才看得完整句话

第 12 行 —— 这一行故意写得很长，长到横向也需要滚动才看得完整句话

第 13 行 —— 这一行故意写得很长，长到横向也需要滚动才看得完整句话

第 14 行 —— 这一行故意写得很长，长到横向也需要滚动才看得完整句话

第 15 行 —— 这一行故意写得很长，长到横向也需要滚动才看得完整句话

第 16 行 —— 这一行故意写得很长，长到横向也需要滚动才看得完整句话

<script setup lang="ts">
import {
  XhScrollAreaContent,
  XhScrollAreaCorner,
  XhScrollAreaRoot,
  XhScrollAreaScrollbar,
  XhScrollAreaThumb,
  XhScrollAreaViewport,
} from "@xihan-ui/vue";

const rows = Array.from(
  { length: 16 },
  (_, i) => `第 ${i + 1} 行 —— 这一行故意写得很长，长到横向也需要滚动才看得完整句话`
);
</script>

<template>
  <XhScrollAreaRoot
    type="always"
    style="block-size: 160px; inline-size: 100%; max-inline-size: 420px"
  >
    <XhScrollAreaViewport>
      <XhScrollAreaContent style="padding: 8px 12px">
        <p
          v-for="row in rows"
          :key="row"
          style="margin: 0; line-height: 24px; white-space: nowrap"
        >
          {{ row }}
        </p>
      </XhScrollAreaContent>
    </XhScrollAreaViewport>
    <XhScrollAreaScrollbar orientation="vertical">
      <XhScrollAreaThumb />
    </XhScrollAreaScrollbar>
    <XhScrollAreaScrollbar orientation="horizontal">
      <XhScrollAreaThumb />
    </XhScrollAreaScrollbar>
    <XhScrollAreaCorner />
  </XhScrollAreaRoot>
</template>

只管一条轴

orientation 关掉的那条轴滚动条恒不显形，视口那一向也不再滚，不留滚不回来的暗格

卡片 1

卡片 2

卡片 3

卡片 4

卡片 5

卡片 6

卡片 7

卡片 8

卡片 9

卡片 10

卡片 11

卡片 12

<script setup lang="ts">
import {
  XhScrollAreaContent,
  XhScrollAreaRoot,
  XhScrollAreaScrollbar,
  XhScrollAreaThumb,
  XhScrollAreaViewport,
} from "@xihan-ui/vue";

const cards = Array.from({ length: 12 }, (_, i) => `卡片 ${i + 1}`);
</script>

<template>
  <XhScrollAreaRoot
    orientation="horizontal"
    type="always"
    style="block-size: 110px; inline-size: 100%; max-inline-size: 420px"
  >
    <XhScrollAreaViewport>
      <XhScrollAreaContent style="display: flex; gap: 10px; padding: 10px 12px">
        <div
          v-for="card in cards"
          :key="card"
          style="
            flex: none;
            display: grid;
            place-items: center;
            inline-size: 96px;
            block-size: 64px;
            border: 1px solid var(--xh-border-subtle);
            border-radius: 8px;
          "
        >
          {{ card }}
        </div>
      </XhScrollAreaContent>
    </XhScrollAreaViewport>
    <XhScrollAreaScrollbar orientation="horizontal">
      <XhScrollAreaThumb />
    </XhScrollAreaScrollbar>
  </XhScrollAreaRoot>
</template>

收起的等待

type 为 scroll 时滚动条停手后不立刻收起，scrollHideDelay 决定还留多少毫秒

200ms：停手就收

第 1 行

第 2 行

第 3 行

第 4 行

第 5 行

第 6 行

第 7 行

第 8 行

第 9 行

第 10 行

第 11 行

第 12 行

第 13 行

第 14 行

第 15 行

第 16 行

第 17 行

第 18 行

第 19 行

第 20 行

2000ms：停手后还留两秒

第 1 行

第 2 行

第 3 行

第 4 行

第 5 行

第 6 行

第 7 行

第 8 行

第 9 行

第 10 行

第 11 行

第 12 行

第 13 行

第 14 行

第 15 行

第 16 行

第 17 行

第 18 行

第 19 行

第 20 行

<script setup lang="ts">
import {
  XhScrollAreaContent,
  XhScrollAreaRoot,
  XhScrollAreaScrollbar,
  XhScrollAreaThumb,
  XhScrollAreaViewport,
} from "@xihan-ui/vue";

const cases = [
  { delay: 200, label: "200ms：停手就收" },
  { delay: 2000, label: "2000ms：停手后还留两秒" },
];
const lines = Array.from({ length: 20 }, (_, i) => `第 ${i + 1} 行`);
</script>

<template>
  <div style="width: 100%; display: flex; flex-wrap: wrap; gap: 16px">
    <div v-for="item in cases" :key="item.delay" style="display: grid; gap: 6px">
      <span>{{ item.label }}</span>
      <XhScrollAreaRoot
        type="scroll"
        :scroll-hide-delay="item.delay"
        style="block-size: 140px; inline-size: 200px"
      >
        <XhScrollAreaViewport>
          <XhScrollAreaContent style="padding: 8px 12px">
            <p v-for="line in lines" :key="line" style="margin: 0; line-height: 22px">
              {{ line }}
            </p>
          </XhScrollAreaContent>
        </XhScrollAreaViewport>
        <XhScrollAreaScrollbar orientation="vertical">
          <XhScrollAreaThumb />
        </XhScrollAreaScrollbar>
      </XhScrollAreaRoot>
    </div>
  </div>
</template>

产物

层	值
自定义元素	<xh-scroll-area>
Vue 组件	XhScrollAreaContent XhScrollAreaCorner XhScrollAreaRoot XhScrollAreaScrollbar XhScrollAreaThumb XhScrollAreaViewport
组合式函数	useScrollArea
状态机	scrollAreaMachine
皮肤	@xihan-ui/styles/scroll-area.css

解剖

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

data-scope="scroll-area"：root · viewport · content · scrollbar · thumb · corner

Props

属性	类型	必填	说明
type	ScrollAreaType		滚动条露面的时机，默认 hover。
scrollHideDelay	number		收起前的等待毫秒（type 为 scroll / hover 时生效），默认 600。
orientation	ScrollAreaOrientation		哪几条轴归本组件管，默认 both。
dir	Direction		排版方向，默认随文档。只影响横轴：RTL 下滚动量的正负、指针位移的方向都要翻一次。 必须显式给：组件不读计算样式，看不见从 RTL 祖先继承来的方向。

状态机

状态：hidden · visible · hiding · dragging

事件：MEASURE · SCROLL · POINTER.ENTER · POINTER.LEAVE · DRAG.START · DRAG.MOVE · DRAG.END · TRACK.CLICK · after.scrollHideDelay

判据：isHoverType · isScrollType · staysVisible

connect API

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

成员	类型	说明
type	ScrollAreaType
orientation	ScrollAreaOrientation
vertical	ScrollAreaAxisState
horizontal	ScrollAreaAxisState
draggingAxis	Orientation | null	正被拖动的那条轴；没在拖为 null。
cornerVisible	boolean	右下角补丁该不该显形：两条滚动条同时在场才有它的位置。
getRootProps	() => T['element']
getViewportProps	() => T['element']
getContentProps	() => T['element']
getScrollbarProps	(props: ScrollAreaScrollbarProps) => T['element']
getThumbProps	(props: ScrollAreaScrollbarProps) => T['element']
getCornerProps	() => T['element']

键盘

规格出处：W3C APG

按键	生效条件	行为
Tab / Shift+Tab	焦点走到滚动区	视口带 tabindex=0，键盘用户能停在滚动区上；组件只在这一处动过 Tab 序列
PageUp / PageDown	focus in viewport	按视口高度翻页滚动；组件不监听、不拦截
ArrowUp / ArrowDown / ArrowLeft / ArrowRight	focus in viewport	逐行/逐列滚动；组件不监听、不拦截
Home / End	focus in viewport	滚到内容两端；组件不监听、不拦截
Space / Shift+Space	focus in viewport	整屏翻页；组件不监听、不拦截