vant/src/count-down/README.md

CountDown

Intro

Used to display the countdown value in real time, and precision supports milliseconds.

Install

Register component globally via app.use, refer to Component Registration for more registration ways.

import { createApp } from 'vue';
import { CountDown } from 'vant';

const app = createApp();
app.use(CountDown);

Usage

Basic Usage

<van-count-down :time="time" />

import { ref } from 'vue';

export default {
  setup() {
    const time = ref(30 * 60 * 60 * 1000);
    return { time };
  },
};

Custom Format

<van-count-down :time="time" format="DD Day, HH:mm:ss" />

Millisecond

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

Custom Style

<van-count-down :time="time">
  <template #default="timeData">
    <span class="block">{{ timeData.hours }}</span>
    <span class="colon">:</span>
    <span class="block">{{ timeData.minutes }}</span>
    <span class="colon">:</span>
    <span class="block">{{ timeData.seconds }}</span>
  </template>
</van-count-down>

<style>
  .colon {
    display: inline-block;
    margin: 0 4px;
    color: #ee0a24;
  }
  .block {
    display: inline-block;
    width: 22px;
    color: #fff;
    font-size: 12px;
    text-align: center;
    background-color: #ee0a24;
  }
</style>

Manual Control

<van-count-down
  ref="countDown"
  millisecond
  :time="3000"
  :auto-start="false"
  format="ss:SSS"
  @finish="onFinish"
/>
<van-grid clickable :column-num="3">
  <van-grid-item text="Start" icon="play-circle-o" @click="start" />
  <van-grid-item text="Pause" icon="pause-circle-o" @click="pause" />
  <van-grid-item text="Reset" icon="replay" @click="reset" />
</van-grid>

import { Toast } from 'vant';

export default {
  setup() {
    const countDown = ref(null);

    const start = () => {
      countDown.value.start();
    };
    const pause = () => {
      countDown.value.pause();
    };
    const reset = () => {
      countDown.value.reset();
    };
    const onFinish = () => Toast('Finished');

    return {
      start,
      pause,
      reset,
      onFinish,
      countDown,
    };
  },
};

API

Props

Attribute	Description	Type	Default
time	Total time, unit milliseconds	number | string	0
format	Time format	string	HH:mm:ss
auto-start	Whether to auto start count down	boolean	true
millisecond	Whether to enable millisecond render	boolean	false

Available formats

Format	Description
DD	Day
HH	Hour
mm	Minute
ss	Second
S	Millisecond, 1-digit
SS	Millisecond, 2-digits
SSS	Millisecond, 3-digits

Events

Event	Description	Arguments
finish	Emitted when count down finished	-
change	Emitted when count down changed	currentTime: CurrentTime

Slots

Name	Description	SlotProps
default	Custom Content	currentTime: CurrentTime

CurrentTime Structure

Name	Description	Type
total	Total time, unit milliseconds	number
days	Remain days	number
hours	Remain hours	number
minutes	Remain minutes	number
seconds	Remain seconds	number
milliseconds	Remain milliseconds	number

Methods

Use ref to get CountDown instance and call instance methods.

Name	Description	Attribute	Return value
start	Start count down	-	-
pause	Pause count down	-	-
reset	Reset count down	-	-

Types

Get the type definition of the CountDown instance through CountDownInstance.

import { ref } from 'vue';
import type { CountDownInstance } from 'vant';

const countDownRef = ref<CountDownInstance>();

countDownRef.value?.start();

CSS Variables

The component provides the following CSS variables, which can be used to customize styles. Please refer to ConfigProvider component.

Name	Default Value	Description
--van-count-down-text-color	var(--van-text-color)	-
--van-count-down-font-size	var(--van-font-size-md)	-
--van-count-down-line-height	var(--van-line-height-md)	-