Sard

Appearance

100%
在新窗口打开⤴

CountDown倒计时

介绍 ​

倒计时的展示 ，以便告知用户在一定时间后可以进行某些操作。

代码演示 ​

基础使用 ​

使用 time 属性配置倒计时总时长（单位毫秒），即可开始倒计时，并在倒计时归零时触发 finish 事件。

vue
<template>
  <s-count-down :time="30 * 60 * 60 * 1000" />
</template>

自定义格式 ​

默认格式为 HH:mm:ss ，也可以使用 format 自定义格式。

vue
<template>
  <s-count-down :time="30 * 60 * 60 * 1000" format="DD 天 HH 时 mm 分 ss 秒" />
</template>

毫秒级别的渲染 ​

默认每隔一秒渲染一次，使用 millisecond 属性可以设置毫秒级别渲染。

vue
<template>
  <s-count-down
    class="font-mono"
    :time="30 * 60 * 60 * 1000"
    format="HH 时 mm 分 ss 秒 SSS 毫秒"
    millisecond
  />
</template>

自定义样式 ​

如果想获取时分秒等数据分别渲染不同的样式，可以使用默认插槽提供的 time 属性来获取数据（time 类型为：CountDownCurrentTime）。

vue
<template>
  <s-count-down :time="30 * 60 * 60 * 1000" #default="{ time }">
    <div class="flex items-center">
      <s-button size="xs">
        {{ String(time.hours).padStart(2, '0') }}
      </s-button>
      <div class="mx-2 leading-0">:</div>
      <s-button size="xs">
        {{ String(time.minutes).padStart(2, '0') }}
      </s-button>
      <div class="mx-2 leading-0">:</div>
      <s-button size="xs">
        {{ String(time.seconds).padStart(2, '0') }}
      </s-button>
    </div>
  </s-count-down>
</template>

手动控制 ​

当倒计时结束时便会停止，通过组件提供的方法可以控制倒计时的开始、暂停或进行重置。

vue
<template>
  <s-list card>
    <s-list-item>
      <s-count-down
        ref="elRef"
        class="font-mono mx-auto"
        :time="1000 * 10"
        format="ss:SS"
        millisecond
        :auto-start="false"
        @finish="toast('到时了!')"
      />
    </s-list-item>
    <s-list-item>
      <s-grid clickable :columns="3">
        <s-grid-item text="开始" @click="() => elRef?.start()" #icon>
          <demo-icon name="play-circle" />
        </s-grid-item>
        <s-grid-item text="暂停" @click="() => elRef?.pause()" #icon>
          <demo-icon name="pause-circle" />
        </s-grid-item>
        <s-grid-item text="重置" @click="() => elRef?.reset()" #icon>
          <demo-icon name="arrow-clockwise" />
        </s-grid-item>
      </s-grid>
    </s-list-item>
  </s-list>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { toast, type CountDownExpose } from 'sard'

const elRef = ref<CountDownExpose>()
</script>
vue
<template>
  <s-list card>
    <s-list-item>
      <s-count-down
        ref="elRef"
        class="font-mono mx-auto"
        :time="1000 * 10"
        format="ss:SS"
        millisecond
        :auto-start="false"
        @finish="toast('到时了!')"
      />
    </s-list-item>
    <s-list-item>
      <s-grid clickable :columns="3">
        <s-grid-item text="开始" @click="() => elRef?.start()" #icon>
          <demo-icon name="play-circle" />
        </s-grid-item>
        <s-grid-item text="暂停" @click="() => elRef?.pause()" #icon>
          <demo-icon name="pause-circle" />
        </s-grid-item>
        <s-grid-item text="重置" @click="() => elRef?.reset()" #icon>
          <demo-icon name="arrow-clockwise" />
        </s-grid-item>
      </s-grid>
    </s-list-item>
  </s-list>
</template>

<script setup lang="js">
import { ref } from 'vue'
import { toast } from 'sard'
const elRef = ref()
</script>

验证码倒计时 ​

下面代码演示了获取验证码场景中倒计时配合按钮的使用。

vue
<template>
  <s-input v-model="value" placeholder="请输入验证码">
    <template #append>
      <s-button variant="link" compact :loading="loading" :disabled="disabled" @click="onClick">
        <s-count-down
          v-if="disabled"
          :time="1000 * 8"
          format="重发验证码(s)"
          @finish="disabled = false"
        />
        <span v-else-if="loading">正在发送</span>
        <span v-else>发送验证码</span>
      </s-button>
    </template>
  </s-input>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { toast } from 'sard'

const value = ref('')
const loading = ref(false)
const disabled = ref(false)

const sendCaptcha = () => {
  return new Promise((resolve) => setTimeout(resolve, 1000))
}

const onClick = () => {
  loading.value = true
  sendCaptcha()
    .then(() => {
      toast('已发送验证码')
      disabled.value = true
    })
    .finally(() => {
      loading.value = false
    })
}
</script>
vue
<template>
  <s-input v-model="value" placeholder="请输入验证码">
    <template #append>
      <s-button variant="link" compact :loading="loading" :disabled="disabled" @click="onClick">
        <s-count-down
          v-if="disabled"
          :time="1000 * 8"
          format="重发验证码(s)"
          @finish="disabled = false"
        />
        <span v-else-if="loading">正在发送</span>
        <span v-else>发送验证码</span>
      </s-button>
    </template>
  </s-input>
</template>

<script setup lang="js">
import { ref } from 'vue'
import { toast } from 'sard'
const value = ref('')
const loading = ref(false)
const disabled = ref(false)
const sendCaptcha = () => {
  return new Promise((resolve) => setTimeout(resolve, 1e3))
}
const onClick = () => {
  loading.value = true
  sendCaptcha()
    .then(() => {
      toast('已发送验证码')
      disabled.value = true
    })
    .finally(() => {
      loading.value = false
    })
}
</script>

更新倒计时 ​

当 time 改变时，会实时更新倒数时间，如果之前因倒计时结束而暂停，则会重新开始倒计时。

为避免因前后 time 相同导致没有触发更新，可在下一次 tick 中手动调用 reset() 方法重置倒计时。

vue
<template>
  <s-list card>
    <s-list-item>
      <s-count-down
        ref="countDown"
        class="font-mono"
        :time="time"
        format="ss:SS"
        millisecond
        @finish="toast('到时了!')"
      />
    </s-list-item>
    <s-list-item title="点击更新倒计时" arrow hover @click="update"></s-list-item>
  </s-list>
</template>

<script setup lang="ts">
import { nextTick, ref, useTemplateRef } from 'vue'
import { random, toast } from 'sard'

const time = ref(1000 * 10)

const elRef = useTemplateRef('countDown')

const update = () => {
  const newTime = random(3, 10) * 1000
  toast(`更新倒计时：${newTime / 1000}s`)
  time.value = newTime
  nextTick(() => {
    elRef.value?.reset()
  })
}
</script>
vue
<template>
  <s-list card>
    <s-list-item>
      <s-count-down
        ref="countDown"
        class="font-mono"
        :time="time"
        format="ss:SS"
        millisecond
        @finish="toast('到时了!')"
      />
    </s-list-item>
    <s-list-item title="点击更新倒计时" arrow hover @click="update"></s-list-item>
  </s-list>
</template>

<script setup lang="js">
import { nextTick, ref, useTemplateRef } from 'vue'
import { random, toast } from 'sard'
const time = ref(1e3 * 10)
const elRef = useTemplateRef('countDown')
const update = () => {
  const newTime = random(3, 10) * 1e3
  toast(`更新倒计时：${newTime / 1e3}s`)
  time.value = newTime
  nextTick(() => {
    elRef.value?.reset()
  })
}
</script>

API ​

CountDownProps ​

属性描述类型默认值
time倒计时总时长，单位毫秒number0
auto-start是否自动开始倒计时booleantrue
format时间格式string'HH:mm:ss'
millisecond是否开启毫秒级别渲染booleanfalse

CountDownSlots ​

插槽描述属性
default自定义默认内容{ time: CountDownCurrentTime }

CountDownEmits ​

事件描述类型
change倒计时变化时触发(time: CountDownCurrentTime) => void
finish倒计时结束时触发() => void

CountDownExpose ​

属性描述类型
start开始倒计时() => void
pause暂停倒计时() => void
reset重置倒计时() => void

CountDownCurrentTime ​

属性描述类型
milliseconds剩余毫秒number
seconds剩余秒数number
minutes剩余分钟number
hours剩余小时number
days剩余天数number
total剩余总时间（单位毫秒）number

Released under the MIT License.

Copyright © 2023-present wuzhitao