Countdown 倒计时
显示距离某个目标时间还剩多久,到时间后触发事件。用于活动截止、验证码重发、限时操作等场景。
引入
import { NsCountdown } from '@ns/ui'
基础用法
value 传目标时间的毫秒时间戳。组件按“目标时间 - 当前时间”显示,所以页面切到后台再回来、电脑休眠后恢复,显示的时间都是准的。
<script setup lang="ts">
import { NsCountdown } from '@ns/ui'
// 1 小时后
const targetTime = Date.now() + 60 * 60 * 1000
</script>
<template>
<NsCountdown :value="targetTime" title="距离活动结束" />
</template>
目标时间要先算好存起来。不要在模板里写 :value="Date.now() + 10000",这样父组件每次重新渲染都会得到一个新的目标时间,倒计时会被不断重置。
目标时间传 Date
value 也可以直接传 Date 对象。
<script setup lang="ts">
import { NsCountdown } from '@ns/ui'
// 今天 24:00
const endOfToday = new Date()
endOfToday.setHours(24, 0, 0, 0)
</script>
<template>
<NsCountdown :value="endOfToday" title="距离今天结束" />
</template>
格式
format 控制显示格式,默认 HH:mm:ss。可用的单位:
| 单位 | 含义 | 说明 |
|---|---|---|
D | 天 | D 不补零,DD 补到 2 位 |
H | 小时 | H 不补零,HH 补到 2 位 |
m | 分钟 | m 不补零,mm 补到 2 位 |
s | 秒 | s 不补零,ss 补到 2 位 |
S | 毫秒 | S 是百毫秒(1 位),SS 是十毫秒(2 位),SSS 是毫秒(3 位) |
格式里的其他字符原样输出。要输出的文字里含有上面这些字母时,用方括号括起来,例如 D [days] HH:mm:ss。
<script setup lang="ts">
import { NsCountdown, NsSpace } from '@ns/ui'
// 1 天 2 小时 3 分钟后
const targetTime = Date.now() + ((24 + 2) * 60 + 3) * 60 * 1000
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsCountdown :value="targetTime" format="DD 天 HH:mm:ss" />
<NsCountdown :value="targetTime" format="D 天 H 小时 m 分 s 秒" />
<NsCountdown :value="targetTime" format="HH时mm分ss秒" />
<NsCountdown :value="targetTime" format="D [days] HH:mm:ss" />
</NsSpace>
</template>
缺少大单位时折算
格式里没有写的大单位会折算进下一级单位。例如还剩 1 天 2 小时 3 分钟:
<script setup lang="ts">
import { NsCountdown, NsSpace } from '@ns/ui'
// 1 天 2 小时 3 分钟后
const targetTime = Date.now() + ((24 + 2) * 60 + 3) * 60 * 1000
</script>
<template>
<NsSpace direction="vertical" align="start">
<!-- 1 天 02:03:00 -->
<NsCountdown :value="targetTime" format="D 天 HH:mm:ss" />
<!-- 26:03:00 -->
<NsCountdown :value="targetTime" format="HH:mm:ss" />
<!-- 1563:00 -->
<NsCountdown :value="targetTime" format="mm:ss" />
<!-- 93780 秒 -->
<NsCountdown :value="targetTime" format="s" suffix="秒" />
</NsSpace>
</template>
毫秒
格式里带 S 就会显示毫秒:S 是百毫秒(1 位),SS 是十毫秒(2 位),SSS 是毫秒(3 位)。
<script setup lang="ts">
import { NsCountdown, NsSpace } from '@ns/ui'
// 10 分钟后
const targetTime = Date.now() + 10 * 60 * 1000
</script>
<template>
<NsSpace direction="vertical" align="start">
<NsCountdown :value="targetTime" format="mm:ss.SSS" title="SSS" />
<NsCountdown :value="targetTime" format="mm:ss.SS" title="SS" />
<NsCountdown :value="targetTime" format="mm:ss.S" title="S" />
</NsSpace>
</template>
标题、前缀和后缀
title、prefix、suffix 传文字;需要图标或其他内容时用同名插槽,插槽优先于属性。
<script setup lang="ts">
import { NsCountdown, NsIcon, NsSpace } from '@ns/ui'
const targetTime = Date.now() + 3 * 60 * 1000
</script>
<template>
<NsSpace wrap size="large">
<NsCountdown :value="targetTime" title="限时抢购" prefix="仅剩" suffix="秒" format="s" />
<NsCountdown :value="targetTime">
<template #title>秒杀倒计时</template>
<template #prefix>
<NsIcon name="clock" />
</template>
<template #suffix>后结束</template>
</NsCountdown>
<NsCountdown :value="targetTime" format="mm:ss">
<template #title>
<span style="color: var(--ns-color-danger)">距离关闭报名</span>
</template>
</NsCountdown>
</NsSpace>
</template>
自定义数值样式
valueStyle 是加在数值上的行内样式。
<script setup lang="ts">
import { NsCountdown, NsSpace } from '@ns/ui'
// 1 小时后
const targetTime = Date.now() + 60 * 60 * 1000
</script>
<template>
<NsSpace wrap size="large" align="end">
<NsCountdown
:value="targetTime"
:value-style="{ color: 'var(--ns-color-primary)', fontSize: '32px' }"
/>
<NsCountdown
:value="targetTime"
title="危险色、等宽数字"
:value-style="{ color: 'var(--ns-color-danger)', fontFamily: 'var(--ns-font-family-mono)' }"
/>
<NsCountdown
:value="targetTime"
title="小号加粗"
:value-style="{ fontSize: '16px', fontWeight: 600 }"
/>
</NsSpace>
</template>
事件和重新计时
倒计时到 0 时触发 finish。value 变化后会按新的目标时间重新计时,结束之后改成新的时间也可以再次触发 finish。
<script setup lang="ts">
import { ref } from 'vue'
import { NsCountdown, NsButton, NsSpace } from '@ns/ui'
const targetTime = ref(Date.now() + 5000)
const finished = ref(false)
const restart = () => {
finished.value = false
targetTime.value = Date.now() + 5000
}
</script>
<template>
<NsSpace wrap>
<NsCountdown :value="targetTime" format="s.S" suffix="秒" @finish="finished = true" />
<NsButton @click="restart">重新开始</NsButton>
<span v-if="finished">时间到</span>
</NsSpace>
</template>
挂载时目标时间已经过去,显示 0 并立即触发 finish:
<script setup lang="ts">
import { ref } from 'vue'
import { NsCountdown, NsSpace } from '@ns/ui'
// 1 分钟前
const expired = Date.now() - 60 * 1000
const status = ref('进行中')
</script>
<template>
<NsSpace wrap align="end">
<NsCountdown :value="expired" title="报名截止" @finish="status = '已截止'" />
<span>{{ status }}</span>
</NsSpace>
</template>
change 在倒计时进行中每一帧触发,参数按天、时、分、秒、毫秒拆好。下面只在秒数变化时更新显示,避免每秒重新渲染几十次:
<script setup lang="ts">
import { ref } from 'vue'
import { NsCountdown } from '@ns/ui'
import type { CountdownTimeData } from '@ns/ui'
// 2 天 3 小时 4 分钟后
const targetTime = Date.now() + ((2 * 24 + 3) * 60 + 4) * 60 * 1000
const timeData = ref<CountdownTimeData>()
const handleChange = (data: CountdownTimeData) => {
if (data.seconds !== timeData.value?.seconds) {
timeData.value = data
}
}
</script>
<template>
<NsCountdown :value="targetTime" format="D 天 HH:mm:ss" @change="handleChange" />
<p v-if="timeData" style="margin-top: 12px">
days {{ timeData.days }},hours {{ timeData.hours }},minutes {{ timeData.minutes }},seconds
{{ timeData.seconds }},total {{ timeData.total }} 毫秒
</p>
</template>
停止和恢复刷新
通过 ref 调用 stopCountdown 可以让显示停在当前数值上,startCountdown 恢复刷新。这两个方法只控制“是否刷新显示”,目标时间不变,所以恢复后显示的是当时真实的剩余时间,不是从停下的数值接着走。要做“暂停后接着计时”,在恢复时把 value 改成“现在 + 暂停时的剩余毫秒数”。
<script setup lang="ts">
import { ref } from 'vue'
import { NsCountdown, NsButton, NsSpace } from '@ns/ui'
import type { CountdownInstance } from '@ns/ui'
const countdownRef = ref<CountdownInstance>()
const targetTime = Date.now() + 10 * 60 * 1000
</script>
<template>
<NsSpace wrap>
<NsCountdown ref="countdownRef" :value="targetTime" format="mm:ss" />
<NsButton @click="countdownRef?.stopCountdown()">停止刷新</NsButton>
<NsButton @click="countdownRef?.startCountdown()">恢复刷新</NsButton>
</NsSpace>
</template>
“暂停后接着计时”的写法:暂停时记下剩余毫秒数并停止刷新,继续时把 value 改成“现在 + 剩余毫秒数”。
<script setup lang="ts">
import { ref } from 'vue'
import { NsCountdown, NsButton, NsSpace } from '@ns/ui'
import type { CountdownInstance, CountdownTimeData } from '@ns/ui'
const countdownRef = ref<CountdownInstance>()
const targetTime = ref(Date.now() + 60 * 1000)
const paused = ref(false)
let remaining = 60 * 1000
const handleChange = (data: CountdownTimeData) => {
remaining = data.total
}
const pause = () => {
countdownRef.value?.stopCountdown()
paused.value = true
}
const resume = () => {
targetTime.value = Date.now() + remaining
paused.value = false
}
</script>
<template>
<NsSpace wrap align="center">
<NsCountdown ref="countdownRef" :value="targetTime" format="mm:ss.S" @change="handleChange" />
<NsButton v-if="!paused" @click="pause">暂停</NsButton>
<NsButton v-else type="primary" @click="resume">继续</NsButton>
</NsSpace>
</template>
获取验证码
常见的“60 秒后重新获取”:点按钮后才挂载倒计时开始计时,期间按钮禁用;到 0 时触发 finish,卸载倒计时、按钮恢复可点。
<script setup lang="ts">
import { ref } from 'vue'
import { NsButton, NsCountdown, NsSpace } from '@ns/ui'
const target = ref<number>()
const send = () => {
target.value = Date.now() + 60 * 1000
}
</script>
<template>
<NsSpace wrap align="center">
<NsButton type="primary" :disabled="target !== undefined" @click="send">获取验证码</NsButton>
<NsCountdown
v-if="target !== undefined"
:value="target"
format="s"
suffix="秒后可重新获取"
:value-style="{ fontSize: 'var(--ns-font-size-base)' }"
@finish="target = undefined"
/>
</NsSpace>
</template>
Props
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| value | number | Date | - | 目标时间,毫秒时间戳或 Date 对象,必填。不是有效时间时显示 0,不触发 finish |
| format | string | 'HH:mm:ss' | 显示格式,见上面的“格式” |
| title | string | - | 标题 |
| prefix | string | - | 数值前面的文字 |
| suffix | string | - | 数值后面的文字 |
| valueStyle | Record<string, string | number> | - | 数值的行内样式 |
Events
| 事件 | 回调参数 | 说明 |
|---|---|---|
| finish | - | 倒计时到 0 时触发一次。挂载时目标时间已经过去,也会立即触发 |
| change | (timeData: CountdownTimeData) | 倒计时进行中每一帧触发一次(约每秒 60 次) |
Slots
| 插槽 | 作用域参数 | 说明 |
|---|---|---|
| title | - | 标题,优先于 title 属性 |
| prefix | - | 数值前面的内容,优先于 prefix 属性 |
| suffix | - | 数值后面的内容,优先于 suffix 属性 |
方法
通过组件的 ref 调用。
| 方法 | 参数 | 返回值 | 说明 |
|---|---|---|---|
| startCountdown | - | void | 按当前的目标时间重新开始刷新;目标时间已过时立即触发 finish |
| stopCountdown | - | void | 停止刷新,显示停在当前数值上 |
类型
interface CountdownTimeData {
/** 剩余天数 */
days: number
/** 去掉整天后剩余的小时(0-23) */
hours: number
/** 去掉整小时后剩余的分钟(0-59) */
minutes: number
/** 去掉整分钟后剩余的秒(0-59) */
seconds: number
/** 去掉整秒后剩余的毫秒(0-999) */
milliseconds: number
/** 剩余的总毫秒数 */
total: number
}
interface CountdownInstance {
startCountdown: () => void
stopCountdown: () => void
}
注意事项
change每一帧都触发。在回调里直接改响应式数据会让父组件每秒重新渲染几十次,建议先判断数值是否变化(例如只在秒数变了的时候更新)。change的参数始终按“天、时、分、秒、毫秒”拆分,和format无关;format的折算规则只影响显示。- 组件用
requestAnimationFrame刷新。页面在后台时浏览器不执行动画帧,这期间不会触发change;但组件另设了一个到点的定时器,到时间时finish仍会触发(浏览器可能把后台定时器延迟 1 秒左右)。显示的时间不受影响。 - 显示用的是用户电脑的时钟。对时间要求严格的场景(抢购、考试),目标时间和当前时间的差值应以服务器时间为准来换算。
优化点
- [ ] 支持倒计时暂停/继续功能(现在的
stopCountdown只停止刷新,暂停期间时间照常流逝) - [x] 支持倒计时重置功能(修改
value即重新计时) - [ ] 支持多时区显示
- [ ]
change事件支持按显示内容变化触发,而不是每一帧触发 - [ ] 支持默认插槽,用剩余时间数据自定义显示内容
- [ ] 支持用服务器时间校正