RollingText 翻滚文本 - Vant 4

🔢 RollingText 翻滚文本

🎯 介绍

RollingText 组件提供文本翻滚动效，可翻滚数字和其他类型文本。请确保 vant 版本 >= 4.6.0。适用于数字变化、计数展示等场景，让数据更具动感！

📦 引入

通过以下方式来全局注册组件，更多注册方式请参考组件注册。

import { createApp } from'vue'; import { RollingText } from'vant'; const app = createApp(); app.use(RollingText);

🎯 代码演示

🎬 基础用法

最简单的数字翻滚效果！通过 start-num 设置起始数值，target-num 设置目标数值，组件会自动播放炫酷的翻滚动画。

html

<template>
  <div class="demo-rolling-text">
    <van-rolling-text :start-num="0" :target-num="123" />
    <p>从 0 翻滚到 123</p>
    
    <van-rolling-text :start-num="100" :target-num="999" />
    <p>从 100 翻滚到 999</p>
  </div>
</template>

import { ref } from 'vue';

export default {
  setup() {
    return {};
  },
};

🔄 设置翻滚方向

想要不同的视觉效果？通过 direction 属性控制数字翻滚方向，向上翻滚更有科技感！

html

<template>
  <div class="demo-rolling-text">
    <!-- 向下翻滚（默认） -->
    <van-rolling-text :start-num="0" :target-num="456" direction="down" />
    <p>向下翻滚 ⬇️</p>
    
    <!-- 向上翻滚 -->
    <van-rolling-text :start-num="0" :target-num="789" direction="up" />
    <p>向上翻滚 ⬆️</p>
  </div>
</template>

import { ref } from 'vue';

export default {
  setup() {
    return {};
  },
};

⏱️ 设置各数位停止顺序

控制动画的节奏感！通过 stop-order 属性设置各个数位的停止顺序，创造不同的视觉韵律。

html

<template>
  <div class="demo-rolling-text">
    <!-- 从左到右停止（默认） -->
    <van-rolling-text :start-num="0" :target-num="12345" stop-order="ltr" />
    <p>从高位开始停止 ➡️</p>
    
    <!-- 从右到左停止 -->
    <van-rolling-text :start-num="0" :target-num="54321" stop-order="rtl" />
    <p>从个位开始停止 ⬅️</p>
  </div>
</template>

import { ref } from 'vue';

export default {
  setup() {
    return {};
  },
};

🔤 翻转非数字内容

不只是数字！使用 text-list 属性可以翻转任何文本内容，打造独特的文字动画效果。

html

<template>
  <div class="demo-rolling-text">
    <van-rolling-text :text-list="textList" />
    <p>文字翻滚动画</p>
    
    <van-rolling-text :text-list="statusList" />
    <p>状态切换动画</p>
  </div>
</template>

import { ref } from 'vue';

export default {
  setup() {
    const textList = ref([
      'Hello',
      'World',
      'Vant4',
      'React',
      'Vue3!',
    ]);
    
    const statusList = ref([
      '待付款',
      '已付款',
      '配送中',
      '已完成',
    ]);
    
    return { 
      textList,
      statusList 
    };
  },
};

🎨 自定义样式

让翻滚文本更符合你的设计风格！通过 CSS 变量和 height 属性打造个性化的动画效果。

html

<template>
  <div class="demo-rolling-text">
    <!-- 蓝色主题 -->
    <van-rolling-text 
      class="blue-rolling-text" 
      :start-num="0" 
      :target-num="888" 
      :height="50"
    />
    <p>蓝色主题样式</p>
    
    <!-- 渐变主题 -->
    <van-rolling-text 
      class="gradient-rolling-text" 
      :start-num="0" 
      :target-num="666" 
      :height="60"
    />
    <p>渐变主题样式</p>
  </div>
</template>

css

.blue-rolling-text {
  --van-rolling-text-background: #1989fa;
  --van-rolling-text-color: white;
  --van-rolling-text-font-size: 24px;
  --van-rolling-text-gap: 6px;
  --van-rolling-text-item-border-radius: 8px;
  --van-rolling-text-item-width: 40px;
}

.gradient-rolling-text {
  --van-rolling-text-background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
  --van-rolling-text-color: white;
  --van-rolling-text-font-size: 28px;
  --van-rolling-text-gap: 8px;
  --van-rolling-text-item-border-radius: 12px;
  --van-rolling-text-item-width: 45px;
  font-weight: bold;
}

🎮 手动控制

完全掌控动画的播放！通过组件实例的 start 和 reset 方法，实现按需播放的交互体验。

html

<template>
  <div class="demo-rolling-text">
    <van-rolling-text 
      ref="rollingTextRef" 
      :start-num="0" 
      :target-num="999" 
      :auto-start="false"
    />
    
    <div class="control-buttons">
      <van-button type="primary" @click="start">开始动画</van-button>
      <van-button @click="reset">重置动画</van-button>
    </div>
  </div>
</template>

import { ref } from 'vue';

export default {
  setup() {
    const rollingTextRef = ref(null);
    
    const start = () => {
      rollingTextRef.value?.start();
    };
    
    const reset = () => {
      rollingTextRef.value?.reset();
    };
    
    return { 
      rollingTextRef, 
      start, 
      reset 
    };
  },
};

📖 API

🎛️ Props

参数	说明	类型	默认值
start-num	🎯 起始数值，动画的起点	number	`0`
target-num	🏁 目标数值，动画的终点	number	-
text-list	📝 内容数组，用于翻转非数字内容（如文字、状态等）	string[]	`[]`
duration	⏱️ 动画时长，控制翻滚速度（单位：秒）	number	`2`
direction	🔄 文本翻滚方向，`down` 向下翻滚，`up` 向上翻滚	string	`down`
auto-start	🚀 是否自动开始动画，设为 `false` 可手动控制	boolean	`true`
stop-order	🎭 各个数位动画停止顺序，`ltr` 从左到右，`rtl` 从右到左	string	`ltr`
height	📏 数字高度，调整组件显示尺寸（单位：px）	number	`40`

🔧 方法

通过 ref 可以获取到 RollingText 实例并调用实例方法，详见组件实例方法。

方法名	说明	参数	返回值
start	🎬 开始播放翻滚动画	-	-
reset	🔄 重置动画到初始状态	-	-

📝 类型定义

组件导出以下类型定义，方便 TypeScript 开发：

importtype { RollingTextProps, RollingTextInstance, RollingTextDirection, RollingTextStopOrder, } from'vant';

RollingTextInstance 是组件实例的类型，用法如下：

import { ref } from'vue'; importtype { RollingTextInstance } from'vant'; const rollingTextRef = ref<RollingTextInstance>(); rollingTextRef.value?.start();

🎨 主题定制

🎭 样式变量

组件提供了下列 CSS 变量，可用于自定义样式，使用方法请参考 ConfigProvider 组件。

名称	默认值	描述
--van-rolling-text-background	transparent	🎨 背景色，设置数字容器的背景
--van-rolling-text-color	var(--van-text-color)	🖍️ 文字颜色，控制数字显示颜色
--van-rolling-text-font-size	var(--van-font-size-md)	📏 字体大小，调整数字显示尺寸
--van-rolling-text-gap	0px	📐 间距，控制数字之间的距离
--van-rolling-text-item-width	15px	📏 单个数字宽度，设置每位数字的容器宽度
--van-rolling-text-item-border-radius	0px	🔘 圆角大小，设置数字容器的圆角效果

📚 相关文档

🎬 动画组件

Transition 动画 - 页面切换动画效果
Swipe 轮播 - 图片轮播和内容切换

🔢 数字组件

Stepper 步进器 - 数字输入和调节
Rate 评分 - 星级评分显示

🎨 样式工具

ConfigProvider 全局配置 - 主题定制和全局配置
Style 内置样式 - 通用样式类和变量

🔢 RollingText 翻滚文本 ​

🎯 介绍 ​

📦 引入 ​

🎯 代码演示 ​

🎬 基础用法 ​

🔄 设置翻滚方向 ​

⏱️ 设置各数位停止顺序 ​

🔤 翻转非数字内容 ​

🎨 自定义样式 ​

🎮 手动控制 ​

📖 API ​

🎛️ Props ​

🔧 方法 ​

📝 类型定义 ​

🎨 主题定制 ​

🎭 样式变量 ​

📚 相关文档 ​

🎬 动画组件 ​

🔢 数字组件 ​

🎨 样式工具 ​

🔢 RollingText 翻滚文本

🎯 介绍

📦 引入

🎯 代码演示

🎬 基础用法

🔄 设置翻滚方向

⏱️ 设置各数位停止顺序

🔤 翻转非数字内容

🎨 自定义样式

🎮 手动控制

📖 API

🎛️ Props

🔧 方法

📝 类型定义

🎨 主题定制

🎭 样式变量

📚 相关文档

🎬 动画组件

🔢 数字组件

🎨 样式工具