Countdown 倒计时
高性能倒计时组件，支持目标时间/持续时间模式、暂停/恢复、预警状态、翻牌动画、服务器时间校准等高级功能。采用 requestAnimationFrame 实现精准计时。
基础用法
设置 value 为目标时间戳或 Date 对象，组件会自动计算剩余时间并倒计时。
持续时间模式
传入毫秒数（小于 978307200000，即 2001-01-01）时，视为持续时间模式。
自定义格式与文本
通过 format 属性自定义显示格式。支持 DD、HH、mm、ss、SSS 占位符。同时支持 title 和 suffix。
翻牌样式
设置 flip-animation 启用翻牌样式，结合 labels 为每个时间单位添加标签。
控制倒计时
通过 ref 获取组件实例，手动控制倒计时的生命周期。
预警状态
通过 warning-threshold 设置预警阈值。当倒计时进入该范围时，会添加 is-warning 类以便于样式自定义。
完全自定义
利用默认插槽完全接管渲染。插槽作用域暴露了完整的 current 格式化对象及状态标识。
综合场景：限时抢购
结合翻牌动画、标签和预警状态，打造极具紧迫感的电商场景。
服务器时间校准
应对客户端时钟由于手动调节或系统延迟导致的偏差。
实战：弹窗同步案例
在复杂的 SPA 应用中，同一计时任务可能在页面多个位置出现（如商品详情页及弹出的购买面板）。组件通过内部的时间对齐机制，确保弹窗频繁开启/关闭时，时间显示始终与页面保持绝对一致。
实战：电商秒杀列表
高性能 requestAnimationFrame 驱动，即使在瀑布流列表、海量秒杀券等高频刷新场景下，仍能保持极低的 CPU 占用和流畅的 UI 交互，且各计时器逻辑独立、互不干扰。
在 Nuxt 中使用
Countdown 组件完全支持 Nuxt 3/4 的 SSR 渲染。在 Nuxt 项目中使用时，组件会自动导入，无需手动注册。
SSR 注意事项：
- ✅ 组件初始渲染完全支持 SSR
- ✅ 时间计算和格式化在服务端完成
- ✅ Hydration 表现优异，无首屏跳动
- ✅ 自动感应客户端挂载并启动计时
- 💡 建议结合
server-time-offset使用以保证多端时间绝对一致
SSR 性能
Countdown 内部使用 requestAnimationFrame 进行计时，该逻辑仅在客户端执行，不会消耗任何服务端资源。初始渲染时会根据当前服务器时间预计算剩余值，确保全链路体验的一致性。
API
Props
| 属性名 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| value | 目标时间（Date/时间戳）或持续时间（毫秒） | Date | number | — |
| format | 格式化模板或函数 | string | (ctx) => string | 'HH:mm:ss' |
| auto-start | 是否自动开始 | boolean | true |
| interval | 刷新间隔（毫秒） | number | 1000 |
| precision | 计时精度（毫秒） | 1000 | 100 | 10 | 1000 |
| title | 标题/前缀文本 | string | — |
| suffix | 后缀文本 | string | — |
| use-monospace-font | 使用等宽字体防止数字跳变 | boolean | true |
| flip-animation | 启用翻牌动画模式 | boolean | false |
| value-style | 倒计时数字的内联样式 | CSSProperties | string | — |
| separator | 时间单位之间的分隔符 | string | ':' |
| show-days | 显示天数 ('auto' 表示 >= 24h 时显示) | boolean | 'auto' | 'auto' |
| show-hours | 是否显示小时 | boolean | true |
| show-minutes | 是否显示分钟 | boolean | true |
| show-seconds | 是否显示秒 | boolean | true |
| show-milliseconds | 是否显示毫秒 | boolean | false |
| labels | 时间单位的标签模板 | object | — |
| keep-alive-on-finish | 结束后是否保持在 00:00:00 | boolean | true |
| warning-threshold | 预警阈值（毫秒） | number | — |
| timezone-offset | 时区偏移（分钟），用于校准多端时差 | number | — |
| server-time-offset | 服务器时间与本地时间的毫秒差 | number | 0 |
Events
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| change | 倒计时更新时触发 | (ctx: CountdownFormatContext) => void |
| finish | 倒计时结束时触发 | () => void |
| start | 开始倒计时时触发 | () => void |
| pause | 暂停时触发 | () => void |
| resume | 恢复时触发 | () => void |
| reset | 重置时触发 | () => void |
| warning | 进入预警范围时触发 | (ctx: CountdownFormatContext) => void |
| status-change | 状态改变时触发 | (status: CountdownStatus) => void |
Slots
| 插槽名 | 说明 | 参数 |
|---|---|---|
| default | 完全自定义渲染 | { current, remaining, formatted, status, isWarning, isFinished } |
| prefix | 前缀占位符 | — |
| suffix | 后缀占位符 | — |
| value | 自定义数字显示部分 | { text: string } |
| separator | 自定义单位分隔符 | — |
| [key]-cell | 自定义具体单元格 (如 seconds-cell) | { value: string } |
Methods (通过 ref 调用)
| 方法名 | 说明 | 参数 | 返回值 |
|---|---|---|---|
| start | 开始计时 | — | void |
| pause | 暂停计时 | — | void |
| resume | 恢复计时 | — | void |
| reset | 重置计时 | — | void |
| getRemain | 获取当前剩余毫秒 | — | number |
| getStatus | 获取当前计时状态 | — | CountdownStatus |
类型定义
type CountdownStatus = 'pending' | 'running' | 'paused' | 'finished'
interface CountdownFormatContext {
total: number // 总剩余毫秒
days: number
hours: number
minutes: number
seconds: number
milliseconds: number
DD: string // 两位数天
HH: string
mm: string
ss: string
SSS: string
SS: string // 两位数毫秒前的两位
S: string // 一位数毫秒的第一位
}主题变量
Countdown 组件支持通过覆盖以下 CSS 变量来自定义局部样式。所有颜色变量已与全局主题系统对接，自动支持暗黑模式：
| 变量名 | 说明 | 默认值 |
|---|---|---|
--yh-countdown-font-size | 数字字体大小 | 24px |
--yh-countdown-value-color | 数字颜色 | var(--yh-text-color-primary) |
--yh-countdown-label-color | 标签颜色 | var(--yh-text-color-secondary) |
--yh-countdown-separator-color | 分隔符颜色 | var(--yh-text-color-placeholder) |
--yh-countdown-warning-color | 预警状态颜色 | var(--yh-color-danger) |
--yh-countdown-finished-color | 结束状态颜色 | var(--yh-color-success) |
--yh-countdown-bg | 组件根背景 | transparent |
--yh-countdown-block-bg | 翻牌块背景 | var(--yh-fill-color-light) |
--yh-countdown-block-shadow | 翻牌块阴影 | var(--yh-shadow-sm) |
--yh-countdown-block-radius | 翻牌块圆角 | var(--yh-radius-md) |
--yh-countdown-block-padding | 翻牌块内边距 | 12px 16px |
--yh-countdown-gap | 组件内部元素间距 | 8px |
--yh-countdown-font-family | 默认字体族 | var(--yh-font-family) |
--yh-countdown-monospace-font | 等宽字体族 (用于防止跳变) | JetBrains Mono, SF Mono... |