Scrollbar 滚动条

用于包裹固定尺寸的内容区域，提供统一的自定义滚动条样式。

何时使用

页面局部区域需要独立滚动。
下拉面板、抽屉、表格等复合组件需要统一滚动条视觉。
需要通过方法控制内容区滚动位置。

基础用法

滚动内容 1

滚动内容 2

滚动内容 3

滚动内容 4

滚动内容 5

滚动内容 6

滚动内容 7

滚动内容 8

滚动内容 9

滚动内容 10

滚动内容 11

滚动内容 12

vue

<template>
  <x-scrollbar style="height: 160px">
    <div style="height: 400px; box-sizing: border-box">
      <p v-for="item in 12" :key="item">滚动内容 {{ item }}</p>
    </div>
  </x-scrollbar>
</template>

轨道类型

带轨道滚动内容 1

带轨道滚动内容 2

带轨道滚动内容 3

带轨道滚动内容 4

带轨道滚动内容 5

带轨道滚动内容 6

带轨道滚动内容 7

带轨道滚动内容 8

带轨道滚动内容 9

带轨道滚动内容 10

带轨道滚动内容 11

带轨道滚动内容 12

vue

<template>
  <x-scrollbar type="track" style="height: 160px">
    <div style="height: 400px; box-sizing: border-box">
      <p v-for="item in 12" :key="item">带轨道滚动内容 {{ item }}</p>
    </div>
  </x-scrollbar>
</template>

横向滚动

默认横向滚动不会接管普通鼠标滚轮，可通过拖动滚动条、触控板横向手势或 Shift + 滚轮滚动。

阶段 1阶段 2阶段 3阶段 4阶段 5阶段 6阶段 7阶段 8阶段 9阶段 10

vue

<template>
  <x-scrollbar style="width: 420px">
    <div style="display: inline-flex; gap: 12px; width: max-content; min-width: 940px; padding: 12px; box-sizing: border-box">
      <span v-for="item in 10" :key="item">阶段 {{ item }}</span>
    </div>
  </x-scrollbar>
</template>

鼠标滚轮横向滚动

设置 horizontalWheel 后，纯横向滚动区域会把普通鼠标滚轮转换为横向滚动；到达左右边界时会放行页面滚动。下面两个示例内容一致，可直接对比普通滚轮在未开启和开启后的差异。

未开启 horizontal-wheel

默认阶段 1默认阶段 2默认阶段 3默认阶段 4默认阶段 5默认阶段 6默认阶段 7默认阶段 8默认阶段 9默认阶段 10

已开启 horizontal-wheel

滚轮阶段 1滚轮阶段 2滚轮阶段 3滚轮阶段 4滚轮阶段 5滚轮阶段 6滚轮阶段 7滚轮阶段 8滚轮阶段 9滚轮阶段 10

vue

<template>
  <x-scrollbar style="width: 420px">
    <div style="display: inline-flex; gap: 12px; width: max-content; min-width: 940px; padding: 12px; box-sizing: border-box">
      <span v-for="item in 10" :key="item">默认阶段 {{ item }}</span>
    </div>
  </x-scrollbar>

  <x-scrollbar horizontal-wheel style="width: 420px">
    <div style="display: inline-flex; gap: 12px; width: max-content; min-width: 940px; padding: 12px; box-sizing: border-box">
      <span v-for="item in 10" :key="item">滚轮阶段 {{ item }}</span>
    </div>
  </x-scrollbar>
</template>

双向滚动

单元 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单元 31单元 32单元 33单元 34单元 35单元 36单元 37单元 38单元 39单元 40单元 41单元 42单元 43单元 44单元 45单元 46单元 47单元 48单元 49单元 50单元 51单元 52单元 53单元 54单元 55单元 56单元 57单元 58单元 59单元 60单元 61单元 62单元 63单元 64单元 65单元 66单元 67单元 68单元 69单元 70单元 71单元 72单元 73单元 74单元 75单元 76单元 77单元 78单元 79单元 80

vue

<template>
  <x-scrollbar type="track" style="width: 420px; height: 180px">
    <div style="display: grid; grid-template-columns: repeat(8, 96px); gap: 8px; width: max-content; padding: 12px; box-sizing: border-box">
      <span v-for="item in 80" :key="item">单元 {{ item }}</span>
    </div>
  </x-scrollbar>
</template>

滚动事件

事件内容 1

事件内容 2

事件内容 3

事件内容 4

事件内容 5

事件内容 6

事件内容 7

事件内容 8

事件内容 9

事件内容 10

事件内容 11

事件内容 12

等待滚动

vue

<template>
  <x-scrollbar style="height: 160px" @scroll="handleScroll">
    <div style="height: 400px; box-sizing: border-box">
      <p v-for="item in 12" :key="item">事件内容 {{ item }}</p>
    </div>
  </x-scrollbar>
  <p>{{ eventLog }}</p>
</template>

<script setup lang="ts">
import { ref } from 'vue';

const eventLog = ref('等待滚动');

const handleScroll = (event: Event) => {
  const target = event.target as HTMLElement;
  eventLog.value = `scrollTop: ${target.scrollTop}, scrollLeft: ${target.scrollLeft}`;
};
</script>

命令式滚动

vue

<template>
  <x-button @click="scrollToTop">回到左上</x-button>
  <x-button @click="scrollToMiddle">滚动到中部</x-button>
  <x-button @click="scrollToBottom">滚动到底部</x-button>

  <x-scrollbar ref="scrollbarRef" type="track" style="width: 420px; height: 180px">
    <div style="display: grid; grid-template-columns: repeat(8, 96px); gap: 8px; width: max-content; padding: 12px; box-sizing: border-box">
      <span v-for="item in 80" :key="item">单元 {{ item }}</span>
    </div>
  </x-scrollbar>
</template>

<script setup lang="ts">
import { ref } from 'vue';

const scrollbarRef = ref();

const scrollToTop = () => {
  scrollbarRef.value?.scrollTo(0, 0);
};

const scrollToMiddle = () => {
  scrollbarRef.value?.scrollTo({ top: 120, left: 180 });
};

const scrollToBottom = () => {
  scrollbarRef.value?.scrollTop(260);
};
</script>

禁用滚动方向

不会横向滚动 1不会横向滚动 2不会横向滚动 3不会横向滚动 4不会横向滚动 5不会横向滚动 6不会横向滚动 7不会横向滚动 8不会横向滚动 9不会横向滚动 10

vue

<template>
  <x-scrollbar style="width: 420px" disable-horizontal>
    <div style="display: inline-flex; gap: 12px; width: max-content; min-width: 940px; padding: 12px; box-sizing: border-box">
      <span v-for="item in 10" :key="item">不会横向滚动 {{ item }}</span>
    </div>
  </x-scrollbar>
</template>

外层样式

外层样式内容 1

外层样式内容 2

外层样式内容 3

外层样式内容 4

外层样式内容 5

外层样式内容 6

外层样式内容 7

外层样式内容 8

外层样式内容 9

外层样式内容 10

外层样式内容 11

外层样式内容 12

vue

<template>
  <x-scrollbar outer-class="scrollbar-shell" style="height: 160px">
    <div style="height: 400px; box-sizing: border-box">
      <p v-for="item in 12" :key="item">外层样式内容 {{ item }}</p>
    </div>
  </x-scrollbar>
</template>

class 和 style 会透传到内部滚动容器，同时 style 中的宽高、最大宽高等布局尺寸会同步到 Scrollbar 外层节点，保证自定义滚动条轨道和真实滚动区域对齐。横向或双向滚动场景建议直接在 Scrollbar 上设置 width / height。outerClass 和 outerStyle 用于控制 Scrollbar 外层节点。hide 是复合组件内部兼容选项，只隐藏自定义滚动条，不会禁用内容滚动，业务代码不建议直接使用。

按需导入

import { Scrollbar } from 'x-next';

Props

参数	说明	类型	默认值
`type`	滚动条类型，`embed` 悬浮在内容上，`track` 保留轨道空间	`'track' \| 'embed'`	`'embed'`
`outerClass`	外层自定义类名	`string \| object \| array`	`-`
`outerStyle`	外层自定义样式	`string \| object \| array`	`-`
`hide`	隐藏自定义滚动条，内部兼容选项，不建议业务直接使用	`boolean`	`false`
`disableHorizontal`	禁用横向滚动并隐藏横向自定义滚动条	`boolean`	`false`
`disableVertical`	禁用纵向滚动并隐藏纵向自定义滚动条	`boolean`	`false`
`horizontalWheel`	纯横向滚动时将鼠标滚轮转换为横向滚动，滚动到边界后放行页面滚动	`boolean`	`false`

Events

事件名	说明	回调参数
`scroll`	内容滚动时触发	`event: Event`

Methods

方法	说明	参数
`scrollTo`	滚动到指定位置	`(options?: number \| { left?: number; top?: number }, y?: number)`
`scrollTop`	设置纵向滚动位置	`(top: number)`
`scrollLeft`	设置横向滚动位置	`(left: number)`

Slots

插槽名	说明
`default`	滚动内容

Scrollbar 滚动条 ​

何时使用 ​

基础用法 ​

轨道类型 ​

横向滚动 ​

鼠标滚轮横向滚动 ​

双向滚动 ​

滚动事件 ​

命令式滚动 ​

禁用滚动方向 ​

外层样式 ​

按需导入 ​

Props ​

Events ​

Methods ​

Slots ​