CountTo 数字滚动组件

一个支持 SSR 和 SEO 的数字滚动动画组件。

特性

• ✅ 支持服务端渲染 (SSR)
• ✅ SEO 友好
• ✅ 客户端水合兼容
• ✅ 可配置的初始显示值
• ✅ 平滑的数字滚动动画
• ✅ 支持前缀和后缀
• ✅ 可控制自动播放

安装

npm install @fish-render/count-to

基础用法

<template>
  <CountTo :end-value="1000" />
</template>

<script setup>
import { CountTo } from '@fish-render/count-to'
</script>

高级用法

SSR 和 SEO 配置

<template>
  <!-- 默认模式：SSR 时显示最终值，客户端水合后开始动画（SEO 友好） -->
  <CountTo :end-value="1000" />

  <!-- 强制显示最终值（适合静态展示） -->
  <CountTo :end-value="1000" initial-display="end" />

  <!-- 强制显示起始值（适合动画展示） -->
  <CountTo :end-value="1000" initial-display="start" />

  <!-- 禁用 SSR 模式（仅在客户端渲染） -->
  <CountTo :end-value="1000" :ssr="false" />
</template>

自定义动画

<template>
  <CountTo
    :start-value="0"
    :end-value="1000"
    :duration="5000"
    prefix="¥"
    suffix="元"
    :autoplay="true"
  />
</template>

手动控制

<template>
  <div>
    <CountTo ref="countToRef" :end-value="1000" :autoplay="false" />
    <button @click="startAnimation">开始动画</button>
    <button @click="resetAnimation">重置</button>
  </div>
</template>

<script setup>
import { ref } from 'vue'
import { CountTo } from '@fish-render/count-to'

const countToRef = ref()

const startAnimation = () => {
  countToRef.value?.startAnimation()
}

const resetAnimation = () => {
  countToRef.value?.resetToStart()
}
</script>

Props

| 属性 | 类型 | 默认值 | 说明 | | ---------------- | ---------------------------- | -------- | -------------------- | | startValue | number | 0 | 起始值 | | endValue | number | - | 结束值（必需） | | duration | number | 3000 | 动画持续时间（毫秒） | | prefix | string | '' | 前缀文本 | | suffix | string | '' | 后缀文本 | | autoplay | boolean | true | 是否自动播放 | | ssr | boolean | true | 是否启用 SSR 模式 | | initialDisplay | 'start' \| 'end' \| 'auto' | 'auto' | 初始显示值 |

方法

| 方法 | 说明 | | ------------------ | ------------ | | startAnimation() | 手动开始动画 | | resetToStart() | 重置到起始值 | | jumpToEnd() | 跳转到最终值 |

SSR 和 SEO 说明

服务端渲染 (SSR)

组件完全支持服务端渲染，在服务端会渲染最终值，在客户端水合后开始动画。

SEO 友好

• 默认情况下，SSR 时会显示最终值，确保搜索引擎能够索引到正确的数值
• 可以通过 initialDisplay 属性控制初始显示的内容
• 支持 prefix 和 suffix 属性，提供更丰富的上下文信息

水合兼容

组件确保服务端和客户端渲染结果一致，避免水合不匹配的问题。

注意事项

1. 在 SSR 环境下，动画只会在客户端水合后开始
2. 如果禁用 autoplay，组件会直接显示最终值
3. 使用 initialDisplay="end" 时，SSR 和客户端都会显示最终值，适合静态展示场景
4. 使用 initialDisplay="start" 时，始终显示起始值，适合需要动画效果的场景
5. 默认情况下，SSR 时显示最终值以优化 SEO，客户端水合后开始动画