数字滚动器

🧬移植自 [VueDigitalTransform]

TuiDigitalRolling 是一个模拟类似“里程表”或“老虎机”滚动效果的数值展示组件。 与翻牌器（Flip）的机械折叠感不同，它提供平滑的纵向滚动动画。组件支持错位滚动（Dislocation）以模拟物理惯性，非常适合用于展示实时增长的销售额、统计数据或时钟。

基础用法

基础展示

最简单的用法只需绑定 value。 组件会自动处理数值变化并触发滚动动画。支持整数、小数以及时间格式字符串（如 "12:30:59"）。

<script setup>
import { ref } from 'vue';
const num = ref(12345);
</script>

<template>
  <TuiDigitalRolling :value="num" />
</template>

滚动机制

通过 dislocation 属性控制数字滚动的节奏感，以适应不同的业务场景。

• false (默认): 统一节奏。所有数字位同时开始滚动，适合计数器、倒计时或时钟，强调同步感。
• true: 错位滚动。模拟真实物理滚轮，高位和低位数字的滚动距离和时间不同，产生类似里程表的物理惯性，适合展示大额统计数据。

<template>
  <TuiDigitalRolling value="12:00:00" :dislocation="false" />
  
  <TuiDigitalRolling :value="987654" :dislocation="true" :interval="1000" />
</template>

格式化与符号

千分位与标点处理

• useGrouping: 开启千分位分隔符。
• includeSymbols: 控制标点符号（小数点、逗号）的滚动行为。
• false (默认): 标点符号固定不动，仅数字滚动。
• true: 标点符号参与滚动动画。

<template>
  <TuiDigitalRolling :value="1234.56" useGrouping />

  <TuiDigitalRolling :value="1234.56" useGrouping includeSymbols />
</template>

前后缀

通过 prefix 和 suffix 添加单位。

<TuiDigitalRolling :value="88" prefix="$ " suffix=" %" />

外观与层级

视觉层级 (Appearance Layer)

TuiDigitalRolling 提供了独特的外观层级控制 appearanceLayer，决定背景、边框和阴影的应用范围：

• group (默认): 将整个数字串视为一个整体，背景和边框包裹在最外层。
• item: 每个数字（Digit）独立拥有背景和边框。
• none: 无背景风格。

<template>
  <TuiDigitalRolling :value="12345" appearanceLayer="group" bordered />
  
  <TuiDigitalRolling :value="12345" appearanceLayer="item" bordered :gap="4" />
</template>

风格定制

• bordered: 显示边框。
• dropShadow: 显示投影。
• appearance: default (深底浅字) / reverse (浅底深字)。
• gap: 数字之间的间距 (px)。

自定义样式

设置 size="custom" 并传入 customClass，利用 CSS 变量可以精确控制滚动器的每一个细节，包括字体大小、单个数字块的宽高以及颜色。

<template>
  <TuiDigitalRolling 
    :value="12345" 
    size="custom" 
    appearance="custom"
    customClass="my-rolling-style" 
  />
</template>

<style lang="less">
.my-rolling-style {
  /* 定义尺寸 */
  --tui-droll-fz: 20px;   /* 字体大小 */
  --tui-droll-lh: 24px;   /* 行高 */
  --tui-droll-w: 24px;    /* 单个数字宽度 */
  --tui-droll-h: 30px;    /* 单个数字高度 */
  
  /* 定义配色 */
  --tui-droll-fc: #e6a23c;       /* 字体颜色 */
  --tui-droll-bg: #409eff;       /* 背景颜色 */
  --tui-droll-bd: #66b1ff;       /* 边框颜色 */
  --tui-droll-shadow: 0 2px 4px rgba(0,0,0,0.2); /* 阴影 */
}
</style>

API 参考

Props

属性名	类型	默认值	说明
value	String/Number	0	必填。显示的数值。
dislocation	Boolean	false	是否开启错位滚动（模拟物理惯性）。
interval	Number	500	滚动动画时长 (ms)。
appearanceLayer	String	'group'	外观应用层级。可选：group (整体), item (单个数字), none。
useGrouping	Boolean	false	是否启用千分位分隔符。
includeSymbols	Boolean	false	标点符号（逗号、小数点）是否参与滚动动画。
prefix	String	-	前缀文本。
suffix	String	-	后缀文本。
delay	Number	-	动画延迟触发时间 (ms)。
gap	Number	-	数字之间的间距 (px)。
size	String	'default'	尺寸。可选：huge, large, default, small, custom。
appearance	String	'default'	配色风格。可选：default, reverse, custom。
bordered	Boolean	false	是否显示边框。
dropShadow	Boolean	false	是否显示阴影。
customClass	String	-	自定义类名，配合 size="custom" 使用。

致谢

DakerHub

Github

此组件移植自开源组件 vue-digital-transform，在此基础上基于 TechUI 全局主题，进行了深度定制，并添加了诸多的API，大大增强了本组件的能力。

在此，向作者 DakerHub 致以诚挚的谢意与敬意！！