Vant RollingText 翻滚文本组件实战指南：数字与文本翻滚动效的配置、原理与手动控制-北京尧图网络

Vant RollingText 翻滚文本组件实战指南数字与文本翻滚动效的配置、原理与手动控制【免费下载链接】vantA lightweight, customizable Vue UI library for mobile web apps.项目地址: https://gitcode.com/GitHub_Trending/va/vantRollingText翻滚文本是 Vant 移动端组件库提供的一款文本翻滚动效组件可以像老虎机一样翻滚数字也可以翻滚任意等长文本常用于大屏数据看板、金额/人数等统计数字的播报场景。本文基于当前仓库中 Vant 4.10.0 的组件实现完整讲解 RollingText 的全部属性、实例方法、样式定制方式并结合源码剖析其位数补零、数字序列构建、CSS 关键帧动画与实例方法暴露等底层原理帮助你在项目中快速落地可复用的翻滚动效。组件简介与版本要求RollingText 组件位于 packages/vant/src/rolling-text由RollingText.tsx外层组件、RollingTextItem.tsx单个数位子组件、index.less样式、types.ts类型定义组成并通过 index.ts 使用withInstall封装为可全局注册的插件。使用该组件需要将vant升级到 4.6.0版本当前仓库packages/vant/package.json中的版本为4.10.0。它基于 Vue 3 编写依赖vue: ^3.0.0。组件支持两类翻滚内容数字通过start-num/target-num指定起始与目标数值自动完成翻滚非数字文本通过text-list传入等长字符串数组从第一项翻滚到最后一项。引入组件在应用入口通过app.use()全局注册组件即可在模板中使用van-rolling-textimport { createApp } from vue; import { RollingText } from vant; const app createApp(); app.use(RollingText);注册后组件会以van-rolling-text的标签名全局可用。除全局注册外也支持按需引入与局部注册更多注册方式可参考组件注册。从 index.ts 的声明可以看到组件还会向 Vue 全局组件类型中注入VanRollingText因此在 TypeScript 项目中可以直接获得模板内的类型提示。代码演示与属性详解基础用法从起始数值翻滚到目标数值通过start-num设置起始数值target-num设置目标数值。RollingText 默认会在组件挂载后自动开始动画从起始数值翻滚到目标数值van-rolling-text :start-num0 :target-num123 /这里有两个细节值得说明位数取两者较大者从 RollingText.tsx 的源码看数字场景下itemLength取Math.max(startNum, targetNum)的字符串长度即start-num0、target-num123时按 3 位渲染。自动补零起始与目标数字都会经过工具函数padZero定义于 utils/format.ts按itemLength补齐前导零所以0会被渲染成000再翻滚到123视觉效果整齐一致。设置翻滚方向down 与 updirection属性控制数字的翻滚方向默认值为down向下翻滚设置为up即向上翻滚van-rolling-text :start-num0 :target-num432 directionup /对应源码中direction的类型为RollingTextDirection取值只有up | down见 types.ts通过makeStringProp(down)声明默认值。方向在底层是如何实现的在 RollingTextItem.tsx 中每个数位会先根据方向构造滚动序列down向下翻滚将数字序列slice().reverse()反转初始位置在序列底部translateY(-总高度)随后动画从底部滚回顶部视觉上表现为数字自上而下滚落up向上翻滚保持序列顺序动画从顶部滚到底部。方向还会以 BEM 修饰类van-rolling-text-item--down/--up的形式作用于根节点配合 index.less 中两套keyframesvan-down、van-up驱动位移具体动画机制见下文“动画原理”一节。设置各数位停止顺序ltr 与 rtlstop-order属性控制各个数位动画的停止先后顺序默认ltr先停高位即最左边先停设置为rtl则先从个位最右边停止van-rolling-text :start-num0 :target-num54321 stop-orderrtl /其实现逻辑在 RollingText.tsx 的getDelay函数中每一位数都有一个独立的动画延迟延迟值由该位索引和总位数共同决定——ltrdelay 0.2 * ii为从左到右的位数索引第 0 位是最高位高位延迟最短、最先开始也最先停止rtldelay 0.2 * (len - 1 - i)最右侧的个位延迟最短最先停止。也就是说“停止顺序”本质上是每位数 0.2 秒的错峰延迟最终所有位数在各自的动画周期内完成翻转形成依次停定的层叠视觉效果。翻转非数字内容text-listtext-list属性用于翻转非数字内容。组件会从数组的第一项翻滚到最后一项。使用该模式有两点约束数组长度必须大于等于 2且每一项的长度必须一致van-rolling-text :text-listtextList :duration1 /import { ref } from vue; export default { setup() { const textList ref([ aaaaa, bbbbb, ccccc, ddddd, eeeee, fffff, ggggg, ]); return { textList }; }, };源码层面的处理方式见 RollingText.tsx只要textList是长度大于 0 的数组组件即进入isCustomType自定义文本模式itemLength取textList[0].length即每个字符串的长度每个字符串的同一索引位会组成一列可翻滚内容getTextArrByIdx(idx)遍历数组取出每项的第idx个字符作为该数位的滚动序列由于每一位的滚动内容是整列的字符因此要求所有字符串长度一致否则短字符串的越界索引会取到undefined破坏渲染。自定义样式CSS 变量与 height 属性RollingText 提供了若干 CSS 变量用于主题定制也支持直接修改组件样式。此外height属性默认40单位px用于设置单个数位的高度在数字较大时可适当调大van-rolling-text classmy-rolling-text :height54 :start-num12345 :target-num54321 /.my-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: 5px; --van-rolling-text-item-width: 40px; }样式变量在 index.less 中以:root/:host声明默认值。height的底层作用体现在两处见 RollingTextItem.tsx作为单项的line-height控制每个数字占位的高度参与计算总位移translatePx -(height * (序列长度 - 1))位移距离随高度线性放大确保无论高度多少翻滚终态都能精准停在目标数字上。手动控制start 与 reset默认组件自动播放动画但通过auto-start属性默认true可以关闭自动播放再通过 ref 获取组件实例调用start、reset方法手动控制动画van-rolling-text refrollingTextRef :start-num0 :target-num54321 :auto-startfalse / van-grid clickable :column-num3 van-grid-item iconplay-circle-o :textstart clickstart / van-grid-item iconreplay :textreset clickreset / /van-gridimport { ref } from vue; export default { setup() { const rollingTextRef ref(null); const start () { rollingTextRef.value.start(); }; const reset () { rollingTextRef.value.reset(); }; return { rollingTextRef, start, reset }; }, };从 RollingText.tsx 的源码可以看到内部状态与联动逻辑内部维护rolling响应式标记初始值等于props.autoStart它决定了子组件是否挂上--animate动画类start()仅将rolling置为truereset()先将rolling置为false移除动画类、回到初始位置如果auto-start为true则通过rafrequestAnimationFrame来自vant/use在下一帧重新触发start()实现“重置后自动重播”的效果同时组件watch了auto-start的变化当属性从false变为true时会立即调用start()两个方法通过useExpose见 composables/use-expose.ts挂载到组件实例的proxy上对外暴露。这些行为均有对应的单元测试覆盖见 rolling-text/test/index.spec.ts包括auto-start为true/false时动画类是否存在、调用start()后动画类出现、调用reset()后动画类消失以及auto-start为true时调用reset()后动画会重新启动测试中通过await later(50)等待下一帧验证。这些测试同样可以作为你在项目中验证滚动行为的参考范式。API 参考Props参数说明类型默认值start-num起始数值number0target-num目标数值number-text-list内容数组用于翻转非数字内容string[][]duration动画时长单位为秒number2direction文本翻滚方向值为down和upstringdownauto-start是否自动开始动画booleantruestop-order各个数位动画停止先后顺序值为ltr和rtlstringltrheight数字高度单位为pxnumber40上述默认值与 RollingText.tsx 中rollingTextProps的声明完全一致startNum、duration、height使用makeNumberProp声明数字类型默认值autoStart使用truthProp声明布尔truetextList使用makeArrayProp声明数组默认值[]。其中target-num无默认值数字场景下为必填项源码中通过非空断言props.targetNum!使用。方法通过 ref 可以获取到 RollingText 实例并调用实例方法实例方法获取方式可参考组件实例方法。方法名说明参数返回值start开始动画--reset重置动画--类型定义组件导出以下类型定义import type { RollingTextProps, RollingTextInstance, RollingTextDirection, RollingTextStopOrder, } from vant;RollingTextInstance是组件实例的类型在手动控制场景下可用于类型安全的 ref用法如下import { ref } from vue; import type { RollingTextInstance } from vant; const rollingTextRef refRollingTextInstance(); rollingTextRef.value?.start();从 types.ts 可以看到这些类型的完整定义RollingTextDirection up | down、RollingTextStopOrder ltr | rtl、RollingTextExpose { start: () void; reset: () void }而RollingTextInstance是ComponentPublicInstanceRollingTextProps, RollingTextExpose因此rollingTextRef.value上能同时获得 props 与start/reset方法的完整类型提示。主题定制样式变量组件提供了下列 CSS 变量可用于自定义样式使用方法可参考 ConfigProvider 组件ConfigProvider 可用于全局批量配置主题变量。名称默认值描述--van-rolling-text-backgroundinherit单个数位背景色--van-rolling-text-colorvar(--van-text-color)数字颜色--van-rolling-text-font-sizevar(--van-font-size-md)字体大小--van-rolling-text-gap0px数位之间的间隔--van-rolling-text-item-width15px单个数位宽度--van-rolling-text-item-border-radius0px单个数位边框圆角这些变量在 index.less 中统一声明默认值背景色默认inherit继承外层文字颜色默认跟随主题的--van-text-color字体大小默认跟随--van-font-size-md。--van-rolling-text-gap通过数位项的margin-right实现数位间距最后一位会移除margin-right--van-rolling-text-item-width与--van-rolling-text-item-border-radius分别控制单个数位的宽度与圆角同时类型定义中也导出了RollingTextThemeVars可在 TypeScript 中约束主题变量名。对应主题变量同样已在RollingTextThemeVars中声明见 types.ts。动画原理深度剖析理解 RollingText 的底层机制有助于你预判它在复杂业务下的表现例如异步数据变化、动画中途重触发等。数字滚动序列的构建对于数字场景每个数位需要一列“可滚动数字”。在 RollingText.tsx 的getFigureArr中该序列由三段拼接而成从起始位数字start递增到9完整的0到9循环CIRCLE_NUM次源码常量CIRCLE_NUM 2即默认滚动两圈从0递增到目标位数字target。例如起始个位为0、目标个位为3该位序列即为0,1,...,9,0,1,...,9(×2),0,1,2,3。CIRCLE_NUM决定了翻滚的“圈数”是营造真实滚动感的关键参数位移总高度即由这一列数字的数量乘以height得出。CSS 关键帧与位移驱动单个数位的渲染结构见 RollingTextItem.tsx为van-rolling-text-item外层overflow: hidden 视窗 └── van-rolling-text-item__box滚动容器挂 --animate 触发动画 └── 若干 van-rolling-text-item__item单个数字line-height height滚动容器通过行内样式注入三个 CSS 自定义属性见 RollingTextItem.tsx--van-translate目标位移-(height * (序列长度 - 1))--van-duration动画时长duration秒--van-delay该位延迟stop-order计算出的错峰延迟。动画由 index.less 中.van-rolling-text-item__box--animate触发的animation驱动animation: van-up var(--van-duration) ease-in-out var(--van-delay)且animation-iteration-count: 1只播放一次、animation-fill-mode: both结束后保持终态。两套关键帧对应两个翻滚方向keyframes van-up从translateY(0)过渡到translateY(var(--van-translate))配合未反转的序列呈现数字向上滚动keyframes van-down从translateY(var(--van-translate))过渡到translateY(0)配合反转后的序列呈现数字向下滚动。为什么“非数字文本”也能滚动非数字模式复用了完全相同的动画管线getTextArrByIdx构造出的字符序列同样交给RollingTextItem每个字符占据height高的格子通过相同的--van-translate位移完成整列翻滚。这也是“非数字翻转”与“数字翻转”在代码层面仅差一个序列构造函数的根本原因。适用场景与注意事项RollingText 适合以下场景大屏/统计页面的数字播报播放量、订单量、金额等配合duration调节节奏需要循环展示的短文本切换通过text-listauto-start手动触发数据变化时重新翻滚可结合reset()与auto-start的组合行为实现“重置后自动重播”。使用时注意几点text-list模式要求数组长度 ≥ 2 且每项等长target-num在数字模式下必须提供类型为非可选源码中使用非空断言数字位数以start-num/target-num中较大者为准较小的数值会被padZero补零动画默认自动播放需要等待用户操作或异步数据就绪时记得设置:auto-startfalse并配合实例方法触发所有主题变量均可通过 CSS 变量覆盖也可借助 ConfigProvider 进行全局主题统一管理。完整的可运行演示可参考 rolling-text/demo/index.vue其中覆盖了基础用法、双向翻滚、个位先停、非数字文本、自定义样式与手动控制六种场景并配合按钮触发动画是快速上手本组件的最佳样例。【免费下载链接】vantA lightweight, customizable Vue UI library for mobile web apps.项目地址: https://gitcode.com/GitHub_Trending/va/vant创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

Vant RollingText 翻滚文本组件实战指南：数字与文本翻滚动效的配置、原理与手动控制

相关推荐

ESP32-P4 USB Host U盘实验：TinyUSB与FATFS全链路解析

帝国CMS 7.5后台响应式模板V2.4：安装部署与二次开发指南

动态规划解决含手续费股票交易问题

更多资讯

数据安全服务核心技术解析与实践指南

AI Agent技术架构解析与企业级应用实践

Rust 编译器 MIR 构建（MIR Construction）全解析：从 HIR/THIR 到 MIR 的降级过程

用LabVIEW实现多相机轨迹追踪与三维重建：从标定到落点定位

AI论文网站测评：提升毕业论文效率的智能工具

nvm的简介、安装、使用（简单明了）

今日更新

SpacetimeDB C++ 模块库实战：用 C++20 在数据库内构建 WebAssembly 模块

别踩雷！不是所有 AI 写作工具都靠谱，2026 高校认可工具精选

SSM+MySQL幼儿园管理系统源码解析：从部署到优化

本周精选

超人会飞不算本事：系统稳定依赖清晰规则与边界设计

超人VS蜘蛛侠：拆解超级IP的影响力与传播方法论

基于CNN的调制信号识别：MATLAB实现时频图分类实战

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？