feat(useCountdown): new function (#4125)

rtugeek · huang-julien · antfu · web-flow · commit 69cedd2fc7e8 · 2025-01-22T07:59:12.000Z
Co-authored-by: Julien Huang &lt;julien.h.dev@gmail.com&gt;
Co-authored-by: Anthony Fu &lt;anthonyfu117@hotmail.com&gt;
Co-authored-by: Anthony Fu &lt;github@antfu.me&gt;
diff --git a/packages/core/useCountdown/demo.vue b/packages/core/useCountdown/demo.vue
@@ -0,0 +1,85 @@
+<script setup lang="ts">
+import { useEventListener } from '@vueuse/core'
+import { ref } from 'vue'
+import { useCountdown } from './index'
+
+const countdownSeconds = ref(5)
+const rocketRef = ref<HTMLDivElement>()
+const { remaining, start, stop, pause, resume } = useCountdown(countdownSeconds, {
+  onComplete() {
+    rocketRef.value!.classList.add('launching')
+  },
+  onTick() {
+
+  },
+})
+
+function startCountdown() {
+  rocketRef.value!.classList.remove('launching')
+  start(countdownSeconds)
+}
+
+useEventListener(rocketRef, 'animationend', () => {
+  rocketRef.value!.classList.remove('launching')
+})
+</script>
+
+<template>
+  <div class="flex flex-col items-center">
+    <div ref="rocketRef" class="rocket">
+      🚀
+    </div>
+    Rocket launch in {{ remaining }} seconds
+
+    <div class="flex items-center gap-2 mt-4">
+      Countdown: <input v-model="countdownSeconds" type="number">
+    </div>
+    <div class="flex items-center gap-2 justify-center">
+      <button @click="startCountdown">
+        Start
+      </button>
+      <button @click="stop">
+        Stop
+      </button>
+      <button @click="pause">
+        Pause
+      </button>
+      <button @click="resume">
+        Resume
+      </button>
+    </div>
+  </div>
+</template>
+
+<style>
+input {
+  width: 40px;
+}
+
+:root {
+  --rocket-rotate: rotate(-45deg);
+}
+@keyframes rocket {
+  0% {
+    transform: translateY(0) var(--rocket-rotate);
+  }
+  50% {
+    transform: translateY(-200px) var(--rocket-rotate);
+  }
+  100% {
+    transform: translateY(0) var(--rocket-rotate);
+  }
+}
+
+.rocket {
+  transform: var(--rocket-rotate);
+}
+
+.rocket.launching {
+  animation-fill-mode: forwards;
+  animation-play-state: running;
+  animation-duration: 4s;
+  animation-timing-function: ease-in-out;
+  animation-name: rocket;
+}
+</style>
diff --git a/packages/core/useCountdown/index.md b/packages/core/useCountdown/index.md
@@ -0,0 +1,23 @@
+---
+category: Time
+---
+
+# useCountdown
+
+Wrapper for `useIntervalFn` that provides a countdown timer.
+
+## Usage
+
+```js
+import { useCountdown } from '@vueuse/core'
+
+const countdownSeconds = 5
+const { remaining, start, stop, pause, resume } = useCountdown(countdownSeconds, {
+  onComplete() {
+
+  },
+  onTick() {
+
+  }
+})
+```
diff --git a/packages/core/useCountdown/index.test.ts b/packages/core/useCountdown/index.test.ts
@@ -0,0 +1,113 @@
+import type { Pausable } from '@vueuse/shared'
+import type { UseCountdownOptions } from '.'
+import { promiseTimeout } from '@vueuse/shared'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { effectScope } from 'vue'
+import { useCountdown } from '.'
+
+describe('useCountdown', () => {
+  let tickCallback = vi.fn()
+  let completeCallback = vi.fn()
+  let countdown = 3
+  let interval = 100
+  const immediate = true
+  let options: UseCountdownOptions = {
+    interval,
+    onComplete: completeCallback,
+    onTick: tickCallback,
+    immediate,
+  }
+  beforeEach(() => {
+    tickCallback = vi.fn()
+    completeCallback = vi.fn()
+    countdown = 3
+    interval = 100
+    options = {
+      interval,
+      onComplete: completeCallback,
+      onTick: tickCallback,
+      immediate,
+    }
+  })
+
+  async function exec({ isActive, pause, resume }: Pausable) {
+    expect(isActive.value).toBeTruthy()
+    expect(completeCallback).toHaveBeenCalledTimes(0)
+    await promiseTimeout(110)
+    expect(tickCallback).toHaveBeenCalledTimes(1)
+
+    pause()
+    expect(isActive.value).toBeFalsy()
+
+    await promiseTimeout(110)
+    expect(tickCallback).toHaveBeenCalledTimes(1)
+
+    resume()
+    expect(isActive.value).toBeTruthy()
+
+    await promiseTimeout(110)
+    expect(tickCallback).toHaveBeenCalledTimes(2)
+
+    await promiseTimeout(110)
+    expect(tickCallback).toHaveBeenCalledTimes(3)
+    expect(completeCallback).toHaveBeenCalledTimes(1)
+  }
+
+  it('basic start/stop', async () => {
+    const { isActive, stop, start, remaining } = useCountdown(countdown, options)
+    expect(isActive.value).toBeTruthy()
+    expect(completeCallback).toHaveBeenCalledTimes(0)
+
+    await promiseTimeout(110)
+
+    expect(tickCallback).toHaveBeenCalledTimes(1)
+    expect(completeCallback).toHaveBeenCalledTimes(0)
+
+    stop()
+    expect(isActive.value).toBeFalsy()
+    await promiseTimeout(110)
+
+    expect(tickCallback).toHaveBeenCalledTimes(1)
+    expect(remaining.value).toBe(countdown)
+
+    tickCallback.mockClear()
+    completeCallback.mockClear()
+
+    start()
+
+    expect(isActive.value).toBeTruthy()
+    await promiseTimeout(210)
+
+    expect(tickCallback).toHaveBeenCalledTimes(2)
+    expect(completeCallback).toHaveBeenCalledTimes(0)
+
+    expect(remaining.value).toBe(1)
+
+    await promiseTimeout(110)
+    expect(remaining.value).toBe(0)
+    expect(completeCallback).toHaveBeenCalledTimes(1)
+  })
+
+  it('basic pause/resume', async () => {
+    await exec(useCountdown(countdown, options))
+  })
+
+  it('pause/resume in scope', async () => {
+    const scope = effectScope()
+    await scope.run(async () => {
+      await exec(useCountdown(countdown, options))
+    })
+    tickCallback.mockClear()
+    await scope.stop()
+    await promiseTimeout(300)
+    expect(tickCallback).toHaveBeenCalledTimes(0)
+  })
+
+  it('cant work when interval is negative', async () => {
+    const { isActive } = useCountdown(5, { interval: -1 })
+
+    expect(isActive.value).toBeFalsy()
+    await promiseTimeout(60)
+    expect(tickCallback).toHaveBeenCalledTimes(0)
+  })
+})
diff --git a/packages/core/useCountdown/index.ts b/packages/core/useCountdown/index.ts
@@ -0,0 +1,98 @@
+import type { MaybeRefOrGetter, Pausable } from '@vueuse/shared'
+import type { Ref } from 'vue'
+import { useIntervalFn } from '@vueuse/shared'
+import { ref, toValue } from 'vue'
+
+export interface UseCountdownOptions {
+  /**
+   *  Interval for the countdown in milliseconds. Default is 1000ms.
+   */
+  interval?: MaybeRefOrGetter<number>
+  /**
+   * Callback function called when the countdown reaches 0.
+   */
+  onComplete?: () => void
+  /**
+   * Callback function called on each tick of the countdown.
+   */
+  onTick?: () => void
+  /**
+   * Start the countdown immediately
+   *
+   * @default false
+   */
+  immediate?: boolean
+}
+
+export interface UseCountdownReturn extends Pausable {
+  /**
+   * Current countdown value.
+   */
+  remaining: Ref<number>
+  /**
+   * Resets the countdown and repeatsLeft to their initial values.
+   */
+  reset: () => void
+  /**
+   * Stops the countdown and resets its state.
+   */
+  stop: () => void
+  /**
+   * Reset the countdown and start it again.
+   */
+  start: (initialCountdown?: MaybeRefOrGetter<number>) => void
+}
+
+/**
+ * Wrapper for `useIntervalFn` that provides a countdown timer in seconds.
+ *
+ * @param initialCountdown
+ * @param options
+ *
+ * @see https://vueuse.org/useCountdown
+ */
+export function useCountdown(initialCountdown: MaybeRefOrGetter<number>, options?: UseCountdownOptions): UseCountdownReturn {
+  const remaining = ref(toValue(initialCountdown))
+
+  const intervalController = useIntervalFn(() => {
+    const value = remaining.value - 1
+    remaining.value = value < 0 ? 0 : value
+    options?.onTick?.()
+    if (remaining.value <= 0) {
+      intervalController.pause()
+      options?.onComplete?.()
+    }
+  }, options?.interval ?? 1000, { immediate: options?.immediate ?? false })
+
+  const reset = () => {
+    remaining.value = toValue(initialCountdown)
+  }
+
+  const stop = () => {
+    intervalController.pause()
+    reset()
+  }
+
+  const resume = () => {
+    if (!intervalController.isActive.value) {
+      if (remaining.value > 0) {
+        intervalController.resume()
+      }
+    }
+  }
+
+  const start = () => {
+    reset()
+    intervalController.resume()
+  }
+
+  return {
+    remaining,
+    reset,
+    stop,
+    start,
+    pause: intervalController.pause,
+    resume,
+    isActive: intervalController.isActive,
+  }
+}
