滚动基础组件

⭐明星组件

👑首创

TuiRolling 是一个高性能、全功能的通用滚动容器。 它不仅作为 TechUI 其他滚动组件的底层引擎，同时也是一个独立的业务组件。您可以使用它轻松实现无缝跑马灯、列表自动滚动、自定义轮播等交互效果。

它支撑了 TuiRollingNavIcon、TuiRollingNavTabs、TuiRollingNotification、TuiRollingProgress 和 TuiRollingTable 等组件的运行。

核心特性

• 全向滚动: 完美支持 上 (up)、下 (down)、左 (left)、右 (right) 四个方向的滚动。

• 双模式引擎:

• Item 模式: 逐个元素滚动，支持无缝无限循环（跑马灯/名单）。

• Page 模式: 按可视区域翻页滚动（轮播图/分页列表）。

• 智能补齐: 当数据不足以填满视口时，支持自动克隆数据 (fillData) 以维持视觉饱满，或保持原样。

• 动态模糊: 内置高性能 motionBlur，在快速滚动时模拟真实视觉模糊，提升流畅度。

• 内置控制: 提供开箱即用的控制栏（箭头/指示器），支持灵活的布局定位。

基础用法

列表自动滚动 (Item Mode)

最常见的场景是用于展示不断更新的列表（如中奖名单、实时日志）。 设置 direction="up" 和 visibleLength 即可。

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

const list = ref(["用户A 中奖 100元", "用户B 中奖 50元", "用户C 中奖 200元", "用户D..."]);
</script>

<template>
  <div style="height: 300px; border: 1px solid #eee;">
    <TuiRolling :visibleLength="5" direction="up" autoRolling>
      <TuiRollingItem v-for="(text, index) in list" :key="index">
        <div class="list-item">{{ text }}</div>
      </TuiRollingItem>
    </TuiRolling>
  </div>
</template>

<style scoped>
.list-item { height: 100%; display: flex; align-items: center; padding: 0 15px; }
</style>

横向跑马灯 (Marquee)

将方向设置为 left，并开启 seamless 无缝模式。

<TuiRolling direction="left" :visibleLength="3" seamless :interval="0" :duration="5000">
  <TuiRollingItem v-for="img in images" :key="img.id">
    <img :src="img.src" class="carousel-img" />
  </TuiRollingItem>
</TuiRolling>

滚动模式

Item 模式 (默认)

按元素步进滚动。适合连续的数据流。

Page 模式

按“页”滚动，每次滚动的距离等于可视区域的大小。适合传统的轮播图或分屏展示。

<TuiRolling mode="page" direction="right" controlType="indicator" ... />

控制栏与交互

TuiRolling 内置了强大的控制栏系统，您无需手动编写按钮即可控制滚动。

• controlType: 控制器类型。arrow (箭头) 或 indicator (指示器/圆点)。
• controlAlign: 对齐方式 (start, center, end)。
• controlDirection: 控制栏的排列方向 (h, v) 以及位置布局。

<template>
  <TuiRolling 
    direction="up" 
    controlType="indicator" 
    controlDirection="vr" 
    trigger="hover"
  >
    ...
  </TuiRolling>
</template>

数据填充策略

当传入的数据条数少于 visibleLength 时：

• fillData = true (默认): 组件会自动克隆数据填满可视区域，确保滚动效果视觉饱满。
• fillData = false: 保持原样，若数据不足则留白，且通常会自动禁用滚动。

API 参考

Props

属性名	类型	默认值	说明
direction	String	'up'	滚动方向。可选：up, down, left, right。
mode	String	'item'	滚动模式。可选：item (按条), page (按页)。
visibleLength	Number	4	核心属性。可视区域内显示的元素数量。
autoRolling	Boolean	true	是否自动开始滚动。
interval	Number	-	自动滚动的时间间隔 (ms)。
duration	Number	-	单次滚动动画的持续时间 (ms)。
seamless	Boolean	true	是否开启无缝循环滚动。
fillData	Boolean	true	当数据不足一页时，是否自动填充数据以撑满容器。
initIndex	Number	-	初始显示的索引位置。
hoverPause	Boolean	true	鼠标悬停时是否暂停自动滚动。
motionBlur	Boolean	true	是否开启滚动时的动态模糊特效。
showControl	Boolean	true	是否显示控制栏。
controlType	String	-	控制栏类型。可选：arrow, indicator。
controlAlign	String	'center'	控制栏对齐。可选：start, center, end。
controlDirection	String	'v'	控制栏布局方向。v(垂直), h(水平), vr(垂直反向), hr(水平反向)。
trigger	String	'click'	指示器触发方式。可选：click, hover。
delay	Number	1000	初始化延迟时间 (ms)。
resizeObserver	String	'global'	尺寸监听策略：self, global, none。

Emits

事件名	说明	回调参数
start	滚动开始时触发。	-
rolling	滚动过程中持续触发。	(offset)
update	索引更新时触发。	(currentIndex)

Exposed Methods

通过 ref 可以调用组件内部方法进行精细控制：

方法名	说明	参数
play	开始自动滚动。	-
stop	停止自动滚动。	-
toggle	切换播放/暂停状态。	-
prev	滚动到上一项/上一页。	-
next	滚动到下一项/下一页。	-
goTo	跳转到指定索引。	(index: Number)
getInfo	获取当前滚动状态信息（索引、位置等）。	-
forceUpdate	强制触发布局更新。	-

Slots

插槽名	说明
default	放置 TuiRollingItem 组件列表。