数字翻牌器

v0.0.5+

TuiDigitalFlip 是一个具有机械翻牌效果的数值展示组件。 它通过模拟物理翻牌的动态效果，让数值的变化过程更具视觉吸引力，常用于数据大屏、统计看板或倒计时场景。

使用场景

需要较大的卡片，flip的效果才较为明显，虽然支持 size : small 但建议使用 size : default 以上的尺寸。

基础用法

基础展示

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

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

const num = ref(12345);
</script>

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

格式化

千分位与小数

• useGrouping: 开启千分位分隔符（如 1,234,567）。
• 小数支持: 组件会自动识别并保留小数点，无需额外配置。

<template>
  <TuiDigitalFlip :value="123456" useGrouping />
  
  <TuiDigitalFlip :value="123.45" />
</template>

前后缀 (Prefix & Suffix)

通过 prefix 和 suffix 属性为数值添加单位或符号，例如货币符号或百分比。

<template>
  <TuiDigitalFlip :value="1234" prefix="$ " />
  
  <TuiDigitalFlip :value="85" suffix=" %" />
  
  <TuiDigitalFlip :value="122" prefix="产值 " suffix=" 吨" />
</template>

动画控制

翻牌速度与延迟

• duration: 翻牌动画持续时间 (ms)，默认 600。
• delay: 首次加载或数值变化时的延迟触发时间 (ms)。

<template>
  <TuiDigitalFlip :value="88888" :duration="300" />
  
  <TuiDigitalFlip :value="12345" :delay="3000" />
</template>

翻牌模式 (Flip Mode)

通过 flipMode 控制数字滚动的逻辑：

• shortest (默认): 选择最短路径滚动（例如 9 -> 0 直接向下翻）。
• downOnly: 始终向下滚动（模拟传统机械表）。
• smart: 智能模式，根据数值变化方向自动选择。

<TuiDigitalFlip :value="count" flipMode="downOnly" />

外观和样式

尺寸与风格

• size: 内置 huge, large, default, small 四种尺寸。

• appearance:

• default: 默认风格（通常为深色背景浅色文字）。

• reverse: 反转风格（浅色背景深色文字）。

• bordered: 是否显示单个数字的边框。

• dropShadow: 是否显示投影。

<template>
  <TuiDigitalFlip :value="12345" size="large" appearance="reverse" bordered />
</template>

自定义样式

设置 size="custom" 并传入 customClass，可以通过 CSS 变量深度定制翻牌器的宽高、字体大小及配色。

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

<style lang="less">
.my-flip-style {
  /* 定义尺寸 */
  --tui-dflip-fz: 20px;   /* 字体大小 */
  --tui-dflip-lh: 24px;   /* 行高 */
  --tui-dflip-w: 24px;    /* 单个牌宽度 */
  --tui-dflip-h: 30px;    /* 单个牌高度 */
  
  /* 定义配色 */
  --tui-dflip-fc: #e6a23c;       /* 字体颜色 */
  --tui-dflip-bg: #409eff;       /* 牌面背景 */
  --tui-dflip-bg_alt: #66b1ff;   /* 翻转面背景 */
}
</style>

API 参考

Props

属性名	类型	默认值	说明
value	String/Number	0	必填。显示的数值或时间字符串。
duration	Number	600	翻牌动画持续时间 (ms)。
delay	Number	1000	动画延迟开始时间 (ms)。
flipMode	String	'shortest'	翻牌模式。可选：smart, downOnly, shortest。
useGrouping	Boolean	false	是否启用千分位分隔符。
prefix	String	-	前缀文本。
suffix	String	-	后缀文本。
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" 使用。