@tanzhenxing/zx-rolling-text v1.0.1

zx-rolling-text 翻滚文本

zx-rolling-text 是一个为 UniApp 设计的文本翻滚动效组件，可以用于数字的动态翻滚效果，也支持非数字文本内容的列表翻转。它旨在提供一种视觉上吸引人的方式来展示变化的数值或文本。

特性

• 数字翻滚：支持从起始数字平滑翻滚到目标数字。
• 文本列表翻转：支持一组文本内容之间的依次翻转动画。
• 自定义方向：可以设置数字或文本向上或向下翻滚。
• 自定义停止顺序：对于多位数数字，可以控制是从高位先停止还是从低位先停止。
• 灵活配置：提供动画时长、高度、字体大小、间距等多种 Props 进行样式和行为定制。
• 手动控制：可以通过 ref 获取组件实例，调用 start 和 reset 方法来手动控制动画的开始和重置。
• 跨平台：基于 UniApp 的标准组件和 API 实现，努力兼容 H5、小程序和 App 端。

使用方法

<template>
  <view>
    <!-- 数字翻滚 -->
    <zx-rolling-text :start-num="0" :target-num="1234" />

    <!-- 文本列表翻转 -->
    <zx-rolling-text :text-list="['Apple', 'Banana', 'Cherry']" />

    <!-- 手动控制 -->
    <zx-rolling-text ref="myRoller" :target-num="999" :auto-start="false" />
    <button @click="startAnimation">开始</button>
  </view>
</template>

<script setup>
import { ref } from 'vue';
// 如果项目没有自动导入组件，可能需要手动引入
// import zxRollingText from '@/components/zx-rolling-text/zx-rolling-text.vue';

const myRoller = ref(null);
const startAnimation = () => {
  myRoller.value?.start();
};
</script>

API

Props

CSS 变量 (通过 customStyle 或直接在 class 中定义):

• --zx-rolling-text-bg: 单个数位/字符的背景色 (默认: transparent)
• --zx-rolling-text-color: 数字/字符的颜色 (默认: inherit)
• --zx-rolling-text-item-radius: 单个数位/字符的圆角 (默认: 0)

Methods

通过 ref 获取组件实例后，可以调用以下方法：

注意事项

• 性能：对于非常长的数字或文本列表，以及非常快速的动画，请注意性能影响，尤其是在性能较低的设备上。
• 字体与宽度：itemWidth 设置为 auto 时，每个字符的宽度会自适应。如果需要固定宽度，请明确设置 itemWidth。字体的选择也可能影响最终的视觉宽度。
• textList 长度一致性：当使用 textList 时，数组中的每个字符串长度必须相同，否则可能导致显示异常。
• 动画平滑度：动画的平滑度依赖于 CSS transition。在不同平台和设备上，CSS 动画的表现可能略有差异。
• Nvue 兼容性：由于 Nvue 对 CSS 动画的支持限制，复杂动画（如 ease-in-out 之外的 timing-function 或某些 transform 细节）可能表现不同或不支持。此组件主要针对 Vue 页面优化。

示例页面

请参考项目中的 src/pages3/rolling-text/index.vue 文件，其中包含了各种使用场景的示例代码。