Translation in progress
This page hasn't been translated into English yet, so the content below is in Chinese. The code examples work the same way.
Scrollbar 滚动条
包住一块要滚动的内容,把浏览器的原生滚动条换成统一外观的细滚动条:细、圆角、半透明,颜色来自主题变量,暗色主题下自动变浅。
引入
import { NsScrollbar } from '@ns/ui'
基础用法
height 设置高度,内容超出时出现滚动条。滚动条默认隐藏,鼠标移进区域、滚动或拖动时显示,移开、停下 1 秒后淡出。滑块可以拖动,点轨道时滑块跳到点击的位置,按住不放可以接着拖。
<script setup lang="ts">
import { NsScrollbar } from '@ns/ui'
const items = Array.from({ length: 30 }, (_, i) => `第 ${i + 1} 行内容`)
</script>
<template>
<NsScrollbar :height="200" class="box">
<p v-for="item in items" :key="item" class="row">{{ item }}</p>
</NsScrollbar>
</template>
<style scoped>
.box {
border: 1px solid var(--ns-border-color-light);
border-radius: var(--ns-border-radius);
}
.row {
margin: 0;
padding: var(--ns-spacing-2) var(--ns-spacing-3);
border-bottom: 1px solid var(--ns-border-color-lighter);
}
</style>
横向滚动
内容比区域宽时出现横向滚动条,用法一样。内容容器默认是块级元素,宽度等于区域宽度;横向排的内容建议用 view-style 把内容容器设成 width: max-content,内容变宽时滑块能及时跟着变。
<script setup lang="ts">
import { NsScrollbar } from '@ns/ui'
const cards = Array.from({ length: 20 }, (_, i) => i + 1)
const viewStyle = {
display: 'flex',
gap: '12px',
width: 'max-content',
padding: '12px 12px 16px'
}
</script>
<template>
<NsScrollbar :view-style="viewStyle" class="box">
<div v-for="card in cards" :key="card" class="card">卡片 {{ card }}</div>
</NsScrollbar>
</template>
<style scoped>
.box {
border: 1px solid var(--ns-border-color-light);
border-radius: var(--ns-border-radius);
}
.card {
display: flex;
align-items: center;
justify-content: center;
width: 120px;
height: 80px;
border-radius: var(--ns-border-radius);
background: var(--ns-fill-color);
color: var(--ns-text-color-secondary);
}
</style>
最大高度
max-height 设置最大高度:内容不够高时区域跟着内容变矮,超过后出现滚动条。增删内容时滑块自动更新,不用手动处理。
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsScrollbar, NsSpace } from '@ns/ui'
const count = ref(3)
</script>
<template>
<NsSpace direction="vertical" fill>
<NsSpace wrap>
<NsButton type="primary" icon="plus" @click="count++">加一行</NsButton>
<NsButton icon="minus" :disabled="count === 0" @click="count--">减一行</NsButton>
<span>共 {{ count }} 行,超过 200px 后出现滚动条</span>
</NsSpace>
<NsScrollbar :max-height="200" class="box">
<p v-for="i in count" :key="i" class="row">第 {{ i }} 行内容</p>
</NsScrollbar>
</NsSpace>
</template>
<style scoped>
.box {
border: 1px solid var(--ns-border-color-light);
border-radius: var(--ns-border-radius);
}
.row {
margin: 0;
padding: var(--ns-spacing-2) var(--ns-spacing-3);
border-bottom: 1px solid var(--ns-border-color-lighter);
}
</style>
撑满父元素
height 写成 '100%' 时撑满父元素,父元素要有确定的高度。下面的面板高 240px,标题以下的部分都是滚动区域:
<script setup lang="ts">
import { NsScrollbar } from '@ns/ui'
const items = Array.from({ length: 30 }, (_, i) => `第 ${i + 1} 条通知`)
</script>
<template>
<div class="panel">
<div class="panel__header">通知</div>
<div class="panel__body">
<NsScrollbar height="100%">
<p v-for="item in items" :key="item" class="row">{{ item }}</p>
</NsScrollbar>
</div>
</div>
</template>
<style scoped>
.panel {
display: flex;
flex-direction: column;
height: 240px;
border: 1px solid var(--ns-border-color-light);
border-radius: var(--ns-border-radius);
}
.panel__header {
padding: var(--ns-spacing-2) var(--ns-spacing-3);
border-bottom: 1px solid var(--ns-border-color-light);
font-weight: 600;
}
.panel__body {
flex: 1;
min-height: 0;
}
.row {
margin: 0;
padding: var(--ns-spacing-2) var(--ns-spacing-3);
}
</style>
一直显示
always 让滚动条一直显示,不再淡出。内容放得下的方向仍然不显示。
<script setup lang="ts">
import { NsScrollbar } from '@ns/ui'
const items = Array.from({ length: 20 }, (_, i) => `第 ${i + 1} 行`)
</script>
<template>
<NsScrollbar always :height="200" class="box">
<div class="content">
<p v-for="item in items" :key="item" class="row">
{{ item }}:这一行写得比较长,比区域宽,横向也能滚动
</p>
</div>
</NsScrollbar>
</template>
<style scoped>
.box {
border: 1px solid var(--ns-border-color-light);
border-radius: var(--ns-border-radius);
}
.content {
width: 720px;
padding: var(--ns-spacing-3) var(--ns-spacing-3) var(--ns-spacing-4);
}
.row {
margin: 0 0 var(--ns-spacing-2);
}
</style>
滑块最小长度
内容很长时,滑块按比例算出来会很短、不好拖。min-size 是滑块的最小长度(px),默认 20。下面两块各有 1000 行:
<script setup lang="ts">
import { NsScrollbar, NsSpace } from '@ns/ui'
const items = Array.from({ length: 1000 }, (_, i) => `第 ${i + 1} 行内容`)
</script>
<template>
<NsSpace fill align="start">
<div>
<p class="label">默认(20px)</p>
<NsScrollbar always :height="200" class="box">
<p v-for="item in items" :key="item" class="row">{{ item }}</p>
</NsScrollbar>
</div>
<div>
<p class="label">min-size="60"</p>
<NsScrollbar always :height="200" :min-size="60" class="box">
<p v-for="item in items" :key="item" class="row">{{ item }}</p>
</NsScrollbar>
</div>
</NsSpace>
</template>
<style scoped>
.label {
margin: 0 0 var(--ns-spacing-2);
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
.box {
border: 1px solid var(--ns-border-color-light);
border-radius: var(--ns-border-radius);
}
.row {
margin: 0;
padding: var(--ns-spacing-1) var(--ns-spacing-3);
}
</style>
滚动到指定位置
通过 ref 调用方法:
scrollTo(options):传{ top, left, behavior },behavior: 'smooth'时平滑滚动;只传top或left时另一个方向不动。scrollTo(x, y):直接滚到横向x、竖向y。setScrollTop(value)、setScrollLeft(value):只改一个方向。wrapRef是滚动区域元素,可以读scrollHeight等尺寸。
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsScrollbar, NsSpace } from '@ns/ui'
import type { ScrollbarExpose } from '@ns/ui'
const scrollbarRef = ref<ScrollbarExpose>()
const items = Array.from({ length: 40 }, (_, i) => `第 ${i + 1} 行`)
const toTopLeft = () => scrollbarRef.value?.scrollTo({ top: 0, left: 0, behavior: 'smooth' })
const toBottom = () => {
const wrap = scrollbarRef.value?.wrapRef
if (wrap) scrollbarRef.value?.scrollTo({ top: wrap.scrollHeight, behavior: 'smooth' })
}
</script>
<template>
<NsSpace direction="vertical" fill>
<NsSpace wrap>
<NsButton icon="top" @click="toTopLeft">平滑回到左上角</NsButton>
<NsButton icon="arrow-down" @click="toBottom">平滑滚到底部</NsButton>
<NsButton @click="scrollbarRef?.scrollTo(200, 300)">scrollTo(200, 300)</NsButton>
<NsButton @click="scrollbarRef?.setScrollTop(400)">setScrollTop(400)</NsButton>
<NsButton @click="scrollbarRef?.setScrollLeft(150)">setScrollLeft(150)</NsButton>
</NsSpace>
<NsScrollbar ref="scrollbarRef" :height="220" class="box">
<div class="content">
<p v-for="item in items" :key="item" class="row">
{{ item }}:这一行比区域宽,横向也能滚动,方便看横向的方法
</p>
</div>
</NsScrollbar>
</NsSpace>
</template>
<style scoped>
.box {
border: 1px solid var(--ns-border-color-light);
border-radius: var(--ns-border-radius);
}
.content {
width: 900px;
padding: var(--ns-spacing-3) var(--ns-spacing-3) var(--ns-spacing-4);
}
.row {
margin: 0 0 var(--ns-spacing-2);
}
</style>
监听滚动
scroll 事件的参数是 { scrollTop, scrollLeft }。滚轮、拖动滑块、点轨道、调用方法引起的滚动都会触发。
<script setup lang="ts">
import { ref } from 'vue'
import { NsScrollbar, NsSpace } from '@ns/ui'
import type { ScrollbarScrollEvent } from '@ns/ui'
const scrollTop = ref(0)
const scrollLeft = ref(0)
const items = Array.from({ length: 40 }, (_, i) => `第 ${i + 1} 行`)
const handleScroll = (event: ScrollbarScrollEvent) => {
scrollTop.value = Math.round(event.scrollTop)
scrollLeft.value = Math.round(event.scrollLeft)
}
</script>
<template>
<NsSpace direction="vertical" fill>
<span>scrollTop:{{ scrollTop }},scrollLeft:{{ scrollLeft }}</span>
<NsScrollbar :height="200" class="box" @scroll="handleScroll">
<div class="content">
<p v-for="item in items" :key="item" class="row">{{ item }}:往下、往右滚动试试</p>
</div>
</NsScrollbar>
</NsSpace>
</template>
<style scoped>
.box {
border: 1px solid var(--ns-border-color-light);
border-radius: var(--ns-border-radius);
}
.content {
width: 800px;
padding: var(--ns-spacing-3) var(--ns-spacing-3) var(--ns-spacing-4);
}
.row {
margin: 0 0 var(--ns-spacing-2);
}
</style>
把 scroll 事件、setScrollTop 和 wrapRef 组合起来,可以让滑块和滚动位置互相联动:
<script setup lang="ts">
import { ref } from 'vue'
import { NsScrollbar, NsSlider, NsSpace } from '@ns/ui'
import type { ScrollbarExpose, ScrollbarScrollEvent } from '@ns/ui'
const scrollbarRef = ref<ScrollbarExpose>()
const percent = ref(0)
const items = Array.from({ length: 50 }, (_, i) => `第 ${i + 1} 行内容`)
const maxScrollTop = () => {
const wrap = scrollbarRef.value?.wrapRef
return wrap ? wrap.scrollHeight - wrap.clientHeight : 0
}
// 拖动滑块时滚动内容
const handleSlider = (value: number | number[]) => {
percent.value = Array.isArray(value) ? value[0] : value
scrollbarRef.value?.setScrollTop((maxScrollTop() * percent.value) / 100)
}
// 滚动内容时同步滑块
const handleScroll = ({ scrollTop }: ScrollbarScrollEvent) => {
const max = maxScrollTop()
percent.value = max > 0 ? Math.round((scrollTop / max) * 100) : 0
}
</script>
<template>
<NsSpace direction="vertical" fill>
<NsSlider :model-value="percent" @update:model-value="handleSlider" />
<NsScrollbar ref="scrollbarRef" :height="200" class="box" @scroll="handleScroll">
<p v-for="item in items" :key="item" class="row">{{ item }}</p>
</NsScrollbar>
</NsSpace>
</template>
<style scoped>
.box {
border: 1px solid var(--ns-border-color-light);
border-radius: var(--ns-border-radius);
}
.row {
margin: 0;
padding: var(--ns-spacing-2) var(--ns-spacing-3);
border-bottom: 1px solid var(--ns-border-color-lighter);
}
</style>
原生滚动条
native 时不显示自绘的滚动条,改用浏览器原生滚动条,只统一颜色和粗细;原生滚动条一直显示,占内容的位置。下面三块从左到右依次是:自绘滚动条(默认)、native、不用 Scrollbar 时浏览器默认的滚动条。
<script setup lang="ts">
import { NsScrollbar, NsSpace } from '@ns/ui'
const items = Array.from({ length: 30 }, (_, i) => `第 ${i + 1} 行内容`)
</script>
<template>
<NsSpace fill align="start">
<div>
<p class="label">自绘(默认)</p>
<NsScrollbar :height="200" class="box">
<p v-for="item in items" :key="item" class="row">{{ item }}</p>
</NsScrollbar>
</div>
<div>
<p class="label">native</p>
<NsScrollbar native :height="200" class="box">
<p v-for="item in items" :key="item" class="row">{{ item }}</p>
</NsScrollbar>
</div>
<div>
<p class="label">浏览器默认</p>
<div class="box plain">
<p v-for="item in items" :key="item" class="row">{{ item }}</p>
</div>
</div>
</NsSpace>
</template>
<style scoped>
.label {
margin: 0 0 var(--ns-spacing-2);
color: var(--ns-text-color-secondary);
font-size: var(--ns-font-size-sm);
}
.box {
border: 1px solid var(--ns-border-color-light);
border-radius: var(--ns-border-radius);
}
.plain {
height: 200px;
overflow: auto;
}
.row {
margin: 0;
padding: var(--ns-spacing-2) var(--ns-spacing-3);
border-bottom: 1px solid var(--ns-border-color-lighter);
}
</style>
内容容器
组件里有两层:滚动区域(ns-scrollbar__wrap)和里面的内容容器(ns-scrollbar__view)。wrap-class、wrap-style 加在滚动区域上,view-class、view-style 加在内容容器上,tag 改内容容器的标签。下面把内容容器渲染成 <ul>,列表项直接写在默认插槽里:
<script setup lang="ts">
import { NsScrollbar } from '@ns/ui'
const fruits = ['苹果', '香蕉', '橙子', '葡萄', '西瓜', '草莓', '芒果', '菠萝', '樱桃', '桃子']
const wrapStyle = { background: 'var(--ns-fill-color-light)' }
const viewStyle = { margin: '0', padding: '8px 12px 8px 32px' }
</script>
<template>
<NsScrollbar :height="160" tag="ul" :wrap-style="wrapStyle" :view-style="viewStyle" class="box">
<li v-for="fruit in fruits" :key="fruit" class="item">{{ fruit }}</li>
</NsScrollbar>
</template>
<style scoped>
.box {
border: 1px solid var(--ns-border-color-light);
border-radius: var(--ns-border-radius);
}
.item {
padding: var(--ns-spacing-1) 0;
}
</style>
键盘滚动
滚动条本身带 aria-hidden="true",不能聚焦,不打扰读屏软件。要让键盘用户也能滚动,给滚动区域设 tabindex="0":按 Tab 聚焦后,用方向键、PageUp、PageDown、Home、End、空格滚动,聚焦时显示滚动条和焦点框。aria-label 是区域的名称,传了以后滚动区域带 role="region"。
<script setup lang="ts">
import { NsScrollbar } from '@ns/ui'
const items = Array.from({ length: 30 }, (_, i) => `第 ${i + 1} 条公告`)
</script>
<template>
<NsScrollbar :height="200" tabindex="0" aria-label="公告列表" class="box">
<p v-for="item in items" :key="item" class="row">{{ item }}</p>
</NsScrollbar>
</template>
<style scoped>
.box {
border: 1px solid var(--ns-border-color-light);
border-radius: var(--ns-border-radius);
}
.row {
margin: 0;
padding: var(--ns-spacing-2) var(--ns-spacing-3);
border-bottom: 1px solid var(--ns-border-color-lighter);
}
</style>
自定义外观
滚动条的粗细、离边缘的距离和颜色由下面几个 CSS 变量决定,写在组件的 style 或外层的类上就能覆盖。native 时原生滚动条也用这几个变量。
| 变量 | 默认值 | 说明 |
|---|---|---|
--ns-scrollbar-size | 6px | 滚动条粗细 |
--ns-scrollbar-gap | 2px | 滚动条离区域边缘的距离 |
--ns-scrollbar-thumb-color | var(--ns-text-color-quaternary) | 滑块颜色 |
--ns-scrollbar-thumb-hover-color | var(--ns-text-color-tertiary) | 悬停、拖动时滑块的颜色 |
<script setup lang="ts">
import { NsScrollbar } from '@ns/ui'
const items = Array.from({ length: 30 }, (_, i) => `第 ${i + 1} 行内容`)
</script>
<template>
<NsScrollbar always :height="200" class="box primary">
<p v-for="item in items" :key="item" class="row">{{ item }}</p>
</NsScrollbar>
</template>
<style scoped>
.box {
border: 1px solid var(--ns-border-color-light);
border-radius: var(--ns-border-radius);
}
.primary {
--ns-scrollbar-size: 10px;
--ns-scrollbar-thumb-color: var(--ns-color-primary-light-5);
--ns-scrollbar-thumb-hover-color: var(--ns-color-primary);
}
.row {
margin: 0;
padding: var(--ns-spacing-2) var(--ns-spacing-3);
border-bottom: 1px solid var(--ns-border-color-lighter);
}
</style>
Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| height | number | string | — | 高度,数字按 px,字符串原样使用(如 '50vh'、'100%')。写百分比时父元素要有确定的高度 |
| maxHeight | number | string | — | 最大高度,数字按 px。内容不够高时跟着内容走,超过时出现滚动条 |
| always | boolean | false | 一直显示滚动条。默认只在悬停、滚动、拖动和键盘聚焦时显示 |
| minSize | number | 20 | 滑块的最小长度(px)。不是数字或小于 0 时按 20 处理 |
| native | boolean | false | 用浏览器原生滚动条,只统一颜色和粗细,不显示自绘的滚动条 |
| wrapClass | ClassValue | — | 滚动区域(ns-scrollbar__wrap)的类名 |
| wrapStyle | StyleValue | — | 滚动区域的样式 |
| viewClass | ClassValue | — | 内容容器(ns-scrollbar__view)的类名 |
| viewStyle | StyleValue | — | 内容容器的样式 |
| tag | string | 'div' | 内容容器的标签 |
| tabindex | number | string | — | 滚动区域的 tabindex。设成 0 后能用 Tab 聚焦,再用方向键等按键滚动 |
| ariaLabel | string | — | 滚动区域的无障碍名称。传了以后滚动区域带 role="region" |
Events
| 事件 | 回调参数 | 说明 |
|---|---|---|
| scroll | (event: ScrollbarScrollEvent) | 滚动时触发,参数是 { scrollTop, scrollLeft }。拖动、点轨道、调用方法引起的滚动也会触发 |
Slots
| 插槽 | 说明 |
|---|---|
| default | 要滚动的内容,放在内容容器里 |
方法
| 方法 | 参数 | 说明 |
|---|---|---|
| scrollTo | (options: ScrollToOptions) 或 (x, y) | 滚动到指定位置。选项对象可以带 behavior: 'smooth',只传一个方向时另一个方向不动 |
| setScrollTop | (value: number) | 设置竖向滚动位置(px) |
| setScrollLeft | (value: number) | 设置横向滚动位置(px) |
| update | — | 重新计算滑块的大小和位置。尺寸变化一般会自动更新,见注意事项 |
| wrapRef | — | 不是方法,是滚动区域元素(HTMLElement),可以读 scrollHeight 等尺寸 |
类型
import type {
ScrollbarProps,
ScrollbarEmits,
ScrollbarScrollEvent,
ScrollbarScrollToOptions,
ScrollbarExpose
} from '@ns/ui'
interface ScrollbarScrollEvent {
scrollTop: number
scrollLeft: number
}
// 同 DOM 的 ScrollToOptions:{ left?: number; top?: number; behavior?: 'auto' | 'smooth' | 'instant' }
type ScrollbarScrollToOptions = ScrollToOptions
interface ScrollbarExpose {
wrapRef: HTMLElement | undefined
scrollTo: {
(options: ScrollbarScrollToOptions): void
(x: number, y: number): void
}
setScrollTop: (value: number) => void
setScrollLeft: (value: number) => void
update: () => void
}
注意事项
- 要出现竖向滚动条,得限制高度:传
height、max-height,或者在组件的style、class里写height、max-height,效果一样。都不限制时区域跟着内容一样高,只会出现横向滚动条。 - 滚动本身还是浏览器在做,滚轮、触摸、键盘、Shift 加滚轮横向滚动都和原生一样,只是把原生滚动条藏起来、换成自绘的。
- 自绘的滚动条浮在内容上面,不占位置。内容的右边、底边贴着区域边缘时可能被滑块盖住一点,可以给内容留 8px 左右的内边距。
- 这些时候会自动重新计算滑块:滚动区域或内容容器尺寸变化(用
ResizeObserver监听,浏览器不支持时改为监听窗口尺寸)、插槽内容重新渲染、滚动、鼠标移进区域。内容溢出了内容容器、容器本身的尺寸又没变(例如横向排的图片加载完变宽)时发现不了,给内容容器设width: max-content(见“横向滚动”),或者手动调用update()。 scrollTo、setScrollTop、setScrollLeft传了非数字时不滚动,开发环境下在控制台输出[NsUI]开头的警告。native时滚动条的样式由浏览器决定:Firefox 和新版 Chrome、Edge 用scrollbar-color、scrollbar-width设置颜色和粗细,Safari 用::-webkit-scrollbar设置,各浏览器看起来略有差别。- 写在组件上的
class、style和其他属性加在根元素上,tabindex、aria-label加在滚动区域上。 - 暂不支持从右到左的排版(
direction: rtl),这时横向滑块的位置不对。