TechUI Docs

简中

EN

简中

EN

主题

步进滚动 ​

⭐明星组件
👑首创

专为在有限的行或列空间中展示大量元素而设计的容器组件。支持水平和垂直两个方向的步进式滚动，支持鼠标滚轮操作，并针对 TuiRadio 和 TuiCheckbox 等表单组件进行了深度优化。

基础用法 ​

最基本的用法是将一系列元素包裹在 TuiStepScroller 中。组件会自动计算空间并提供分页控制。

vue
<script setup>
import { ref } from 'vue'

const items = ref(Array.from({ length: 20 }, (_, i) => i + 1))
</script>

<template>
  <div style="height: 60px;">
    <TuiStepScroller>
      <div v-for="item in items" :key="item" class="demo-box">
        {{ item }}
      </div>
    </TuiStepScroller>
  </div>
</template>

<style scoped>
.demo-box {
  width: 50px;
  height: 40px;
  display: flex;
  align-items: center;
  justify-content: center;
  background: var(--tui-bg-color);
  border: 1px solid var(--tui-border-color);
  border-radius: 4px;
}
</style>

垂直滚动 ​

将 direction 设置为 'v' 即可开启垂直滚动模式。请确保父容器或组件自身具有明确的高度。

vue
<template>
  <div style="height: 300px; width: 100px;">
    <TuiStepScroller direction="v">
      <div v-for="i in 20" :key="i" class="vertical-item">
        Item {{ i }}
      </div>
    </TuiStepScroller>
  </div>
</template>

<style scoped>
.vertical-item {
  height: 40px;
  width: 100%;
  display: flex;
  align-items: center;
  justify-content: center;
  border-bottom: 1px solid #eee;
}
</style>

适配表单组件 ​

TuiStepScroller 针对 TuiRadio 和 TuiCheckbox 做了特殊的布局优化。当通过步进器展示大量选项时，它能保持选项的整洁排列。

建议配合 border 属性控制分割线样式。

vue
<script setup>
import { ref } from 'vue'

const radioVal = ref(1)
const checkVal = ref([])
</script>

<template>
  <div style="height: 50px; margin-bottom: 20px;">
    <TuiStepScroller border="auto">
      <TuiRadio v-model="radioVal" appearance="button">
        <TuiRadioItem v-for="i in 15" :key="i" :value="i">
          Option {{ i }}
        </TuiRadioItem>
      </TuiRadio>
    </TuiStepScroller>
  </div>

  <div style="height: 200px; width: 150px;">
    <TuiStepScroller direction="v" border="none">
      <TuiCheckbox v-model="checkVal" appearance="button" direction="v">
        <TuiCheckboxItem v-for="i in 10" :key="i" :value="i">
          Check {{ i }}
        </TuiCheckboxItem>
      </TuiCheckbox>
    </TuiStepScroller>
  </div>
</template>

控制按钮与外观 ​

提供了丰富的属性来定制滚动按钮的位置、尺寸以及边框风格。

  • buttonPosition: 控制按钮位置，支持 start (头部), end (尾部), both (两侧), float (悬浮)。
  • buttonSize: 按钮大小，支持 small, default, large。
  • border: 边框策略。
  • auto: 智能模式，通常用于按钮组，只显示内部分割线。
  • none: 无边框模式，元素之间有间隙。
  • always: 强制显示外边框和分割线，紧凑布局。
vue
<script setup>
import { reactive } from 'vue'

const config = reactive({
  position: 'both',
  size: 'default',
  border: 'auto'
})
</script>

<template>
  <div class="control-panel">
    <TuiRadio v-model="config.position" :options="['start', 'end', 'both', 'float']" />
  </div>

  <div style="height: 60px;">
    <TuiStepScroller 
      :buttonPosition="config.position" 
      :buttonSize="config.size"
      :border="config.border"
    >
      <div v-for="i in 20" :key="i" class="item">{{ i }}</div>
    </TuiStepScroller>
  </div>
</template>

滚动模式 ​

通过 scrollMode 可以控制点击按钮时的滚动幅度。

  • full: 整页滚动 (默认)，点击一次滚动一屏可见内容。
  • half: 半页滚动，点击一次滚动半屏内容，适合微调。
vue
<template>
  <TuiStepScroller scrollMode="half" showPagination>
    </TuiStepScroller>
</template>

API 参考 ​

Props ​

属性名说明类型默认值
direction滚动方向，可选 'h' (水平), 'v' (垂直)String'h'
border边框显示策略，可选 'auto', 'none', 'always'String'auto'
buttonPosition控制按钮位置，可选 'both', 'start', 'end', 'float'String'both'
buttonSize控制按钮尺寸，可选 'default', 'small', 'large'String'default'
scrollMode滚动距离模式，可选 'full', 'half'String'full'
showPagination是否显示分页信息 (如 "1/5")Booleantrue
wheelScroll是否允许鼠标滚轮滚动Booleantrue
resizeObserver尺寸监听策略，可选 'self', 'global', 'none'String'self'

Expose ​

组件暴露了以下方法和状态，可通过 ref 调用。

名称说明类型
scrollTo滚动到指定位置 (index 或像素)(index: number) => void
scrollSta滚动到起始位置() => void
scrollEnd滚动到结束位置() => void
initSize重新计算尺寸与布局() => void
resetScrollInner重置内部滚动位置() => void
state组件内部状态对象 (包含 pageInfo 等)Object

Slots ​

插槽名说明
default滚动容器内的内容