@fish-render/count-to/README.md

Fish Render countTo component for Vue 3

# CountTo 数字滚动组件

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

## 特性

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

## 安装

```bash
npm install @fish-render/count-to
```

## 基础用法

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

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

## 高级用法

### SSR 和 SEO 配置

```vue
<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>
```

### 自定义动画

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

### 手动控制

```vue
<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，客户端水合后开始动画**