CountDown 倒计时

介绍

用于实时展示倒计时数值,支持毫秒精度。

引入

通过以下方式来全局注册组件,更多注册方式请参考组件注册

  1. import { createApp } from 'vue';
  2. import { CountDown } from 'vant';
  3. const app = createApp();
  4. app.use(CountDown);

代码演示

基础用法

time 属性表示倒计时总时长,单位为毫秒。

  1. <van-count-down :time="time" />
  1. import { ref } from 'vue';
  2. export default {
  3. setup() {
  4. const time = ref(30 * 60 * 60 * 1000);
  5. return { time };
  6. },
  7. };

自定义格式

通过 format 属性设置倒计时文本的内容。

  1. <van-count-down :time="time" format="DD 天 HH 时 mm 分 ss 秒" />

毫秒级渲染

倒计时默认每秒渲染一次,设置 millisecond 属性可以开启毫秒级渲染。

  1. <van-count-down millisecond :time="time" format="HH:mm:ss:SS" />

自定义样式

通过插槽自定义倒计时的样式,timeData 对象格式见下方表格。

  1. <van-count-down :time="time">
  2. <template #default="timeData">
  3. <span class="block">{{ timeData.hours }}</span>
  4. <span class="colon">:</span>
  5. <span class="block">{{ timeData.minutes }}</span>
  6. <span class="colon">:</span>
  7. <span class="block">{{ timeData.seconds }}</span>
  8. </template>
  9. </van-count-down>
  10. <style>
  11. .colon {
  12. display: inline-block;
  13. margin: 0 4px;
  14. color: #1989fa;
  15. }
  16. .block {
  17. display: inline-block;
  18. width: 22px;
  19. color: #fff;
  20. font-size: 12px;
  21. text-align: center;
  22. background-color: #1989fa;
  23. }
  24. </style>

手动控制

通过 ref 获取到组件实例后,可以调用 startpausereset 方法。

  1. <van-count-down
  2. ref="countDown"
  3. millisecond
  4. :time="3000"
  5. :auto-start="false"
  6. format="ss:SSS"
  7. @finish="onFinish"
  8. />
  9. <van-grid clickable>
  10. <van-grid-item text="开始" icon="play-circle-o" @click="start" />
  11. <van-grid-item text="暂停" icon="pause-circle-o" @click="pause" />
  12. <van-grid-item text="重置" icon="replay" @click="reset" />
  13. </van-grid>
  1. import { showToast } from 'vant';
  2. export default {
  3. setup() {
  4. const countDown = ref(null);
  5. const start = () => {
  6. countDown.value.start();
  7. };
  8. const pause = () => {
  9. countDown.value.pause();
  10. };
  11. const reset = () => {
  12. countDown.value.reset();
  13. };
  14. const onFinish = () => showToast('倒计时结束');
  15. return {
  16. start,
  17. pause,
  18. reset,
  19. onFinish,
  20. countDown,
  21. };
  22. },
  23. };

API

Props

参数说明类型默认值
time倒计时时长,单位毫秒number | string0
format时间格式stringHH:mm:ss
auto-start是否自动开始倒计时booleantrue
millisecond是否开启毫秒级渲染booleanfalse

format 格式

格式说明
DD天数
HH小时
mm分钟
ss秒数
S毫秒(1 位)
SS毫秒(2 位)
SSS毫秒(3 位)

Events

事件名说明回调参数
finish倒计时结束时触发-
change倒计时变化时触发currentTime: CurrentTime

Slots

名称说明参数
default自定义内容currentTime: CurrentTime

CurrentTime 格式

名称说明类型
total剩余总时间(单位毫秒)number
days剩余天数number
hours剩余小时number
minutes剩余分钟number
seconds剩余秒数number
milliseconds剩余毫秒number

方法

通过 ref 可以获取到 CountDown 实例并调用实例方法,详见组件实例方法

方法名说明参数返回值
start开始倒计时--
pause暂停倒计时--
reset重设倒计时,若 auto-starttrue,重设后会自动开始倒计时--

类型定义

组件导出以下类型定义:

  1. import type {
  2. CountDownProps,
  3. CountDownInstance,
  4. CountDownCurrentTime,
  5. } from 'vant';

CountDownInstance 是组件实例的类型,用法如下:

  1. import { ref } from 'vue';
  2. import type { CountDownInstance } from 'vant';
  3. const countDownRef = ref<CountDownInstance>();
  4. countDownRef.value?.start();

主题定制

样式变量

组件提供了下列 CSS 变量,可用于自定义样式,使用方法请参考 ConfigProvider 组件

名称默认值描述
—van-count-down-text-colorvar(—van-text-color)-
—van-count-down-font-sizevar(—van-font-size-md)-
—van-count-down-line-heightvar(—van-line-height-md)-

常见问题

在 iOS 系统上倒计时不生效?

如果你遇到了在 iOS 上倒计时不生效的问题,请确认在创建 Date 对象时没有使用new Date('2020-01-01')这样的写法,iOS 不支持以中划线分隔的日期格式,正确写法是new Date('2020/01/01')

对此问题的详细解释:stackoverflow

CountDown 倒计时 - 图1