uView Next
4.0.105

外观

useCountDown - 倒计时

约 1320 字大约 4 分钟

2025-11-06

useCountDown 是一个用于倒计时的组合式函数，支持毫秒精度、状态持久化和回调函数。

快速开始

1. 导入 useCountDown

<script setup lang="uts">
import { useCountDown } from '@/uni_modules/uview-unix'

const { start, pause, resume, reset, current } = useCountDown({
    time: 60000,
    millisecond: true
})
</script>

2. 使用倒计时

<template>
	<view>
		<text>{{current.minutes}}分</text>
		<text>{{current.seconds}}秒</text>
		<text>{{current.milliseconds}}毫秒</text>
		<button @click="start">开始</button>
		<button @click="pause">暂停</button>
		<button @click="resume">继续</button>
		<button @click="reset">重置</button>
	</view>
</template>

API 参考

useCountDown(options: UnCountDownOptions)

创建倒计时实例。

参数

参数说明类型必填默认值
time倒计时总时长（毫秒）number是-
millisecond是否开启毫秒级显示boolean否false
autoStart是否自动开始倒计时boolean否false
keepRunning是否持久化状态，应用意外关闭后恢复boolean否false
uniqueKey存储的唯一标识，用于区分多个倒计时string否UVIEW_COUNT_DOWN
padZero是否在天、小时、分钟、秒数前补零boolean否false
onStart倒计时开始时的回调
Function
否-
onChange倒计时变化时的回调
Function
否-
onEnd倒计时结束时的回调
Function
否-

返回值

返回一个 UnUseCountDown 对象，包含以下属性和方法：

属性/方法说明类型
start开始倒计时
Function
pause暂停倒计时
Function
resume继续倒计时
Function
reset重置倒计时
Function
current当前倒计时状态UnCurrentTime

UnCurrentTime

当前倒计时状态对象。

属性说明类型
total剩余总毫秒数number
days剩余天数number | string
hours剩余小时数（0-23）number | string
minutes剩余分钟数（0-59）number | string
seconds剩余秒数（0-59）number | string
milliseconds剩余毫秒数（0-999）number | string

示例

基础倒计时

<template>
	<view>
		<text>{{current.seconds}}秒</text>
		<button @click="start">开始</button>
		<button @click="pause">暂停</button>
		<button @click="resume">继续</button>
		<button @click="reset">重置</button>
	</view>
</template>

<script setup lang="uts">
import { useCountDown } from '@/uni_modules/uview-unix'

const { start, pause, resume, reset, current } = useCountDown({
    time: 60000
})
</script>

毫秒级倒计时

<template>
	<view>
		<text>{{current.minutes}}:</text>
		<text>{{current.seconds}}:</text>
		<text>{{current.milliseconds}}</text>
	</view>
</template>

<script setup lang="uts">
import { useCountDown } from '@/uni_modules/uview-unix'

const { start, current } = useCountDown({
    time: 60000,
    millisecond: true
})

start()
</script>

带回调的倒计时

<script setup lang="uts">
import { useCountDown, type UnCurrentTime } from '@/uni_modules/uview-unix'

const { start, current } = useCountDown({
    time: 60000,
    millisecond: true,
    onStart: () => {
        console.log('倒计时开始')
    },
    onChange: (value: UnCurrentTime) => {
        console.log('倒计时变化', value)
    },
    onEnd: () => {
        console.log('倒计时结束')
    }
})

start()
</script>

状态持久化

<script setup lang="uts">
import { useCountDown } from '@/uni_modules/uview-unix'

const { start, current } = useCountDown({
    time: 60000,
    keepRunning: true,
    uniqueKey: 'MY_COUNT_DOWN'
})

// 应用意外关闭后，下次打开会自动恢复状态
start()
</script>

完整示例

<template>
	<un-page>
		<card>
			<view class="countdown-container">
				<view class="countdown-display">
					<view class="countdown-display__item">
						<text class="countdown-display__number">{{current.minutes}}</text>
						<text class="countdown-display__label">分</text>
					</view>
					<text class="countdown-display__separator">:</text>
					<view class="countdown-display__item">
						<text class="countdown-display__number">{{current.seconds}}</text>
						<text class="countdown-display__label">秒</text>
					</view>
					<text class="countdown-display__separator">:</text>
					<view class="countdown-display__item">
						<text class="countdown-display__number">{{current.milliseconds}}</text>
						<text class="countdown-display__label">毫秒</text>
					</view>
				</view>
			</view>
			<un-grid :border="true" col="4">
				<un-grid-item>
					<view class="count-down__grid-item" @click="reset">
						<un-icon name="reload" :size="22"></un-icon>
						<text class="count-down__grid-item__grid-text">重置</text>
					</view>
				</un-grid-item>
				<un-grid-item>
					<view class="count-down__grid-item" @click="start">
						<view class="count-down__grid-item__circle">
							<un-icon color="#fff" name="play-right-fill" :size="22"></un-icon>
						</view>
						<text class="count-down__grid-item__grid-text">开始</text>
					</view>
				</un-grid-item>
				<un-grid-item>
					<view class="count-down__grid-item" @click="pause">
						<un-icon name="pause-circle" :size="22"></un-icon>
						<text class="count-down__grid-item__grid-text">暂停</text>
					</view>
				</un-grid-item>
				<un-grid-item>
					<view class="count-down__grid-item" @click="resume">
						<un-icon name="play-circle" :size="22"></un-icon>
						<text class="count-down__grid-item__grid-text">继续</text>
					</view>
				</un-grid-item>
			</un-grid>
		</card>
	</un-page>
</template>

<script setup lang="uts">
import { useCountDown, type UnCurrentTime } from '@/uni_modules/uview-unix'

const { start, pause, resume, reset, current } = useCountDown({
	time: 60000,
	millisecond: true,
	keepRunning: true,
	onStart: () => {
		console.log('onStart')
	},
	onChange: (value: UnCurrentTime) => {
		console.log('onChange', value)
	},
	onEnd: () => {
		console.log('onEnd')
	}
})
</script>

<style lang="scss" scoped>
.countdown-container {
	padding: 30px 0;
	margin-bottom: 10px;
}

.countdown-display {
	display: flex;
	flex-direction: row;
	justify-content: center;
	align-items: center;

	&__item {
		display: flex;
		flex-direction: column;
		align-items: center;
		justify-content: center;
		padding: 10px 15px;
		width: 80px;
		background: #e8e6e6;
		border-radius: 10px;
	}

	&__number {
		font-size: 28px;
		font-weight: bold;
		color: #1677FF;
		line-height: 1;
		font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
	}

	&__label {
		font-size: 12px;
		color: #909399;
		margin-top: 6px;
	}

	&__separator {
		font-size: 48px;
		font-weight: bold;
		color: #323233;
		margin: 0 8px;
		line-height: 1;
	}
}

.count-down {
	&__grid-item {
		width: 70px;
		height: 70px;
		display: flex;
		flex-direction: row;
		justify-content: center;
		align-items: center;

		&__circle {
			width: 32px;
			height: 32px;
			border-radius: 32px;
			background-color: #3c9cff;
			display: flex;
			justify-content: center;
			align-items: center;
			box-shadow: 1px 1px 4px rgba(155, 191, 255, .7);
		}

		&__grid-text {
			font-size: 14px;
			color: #909399;
			box-sizing: border-box;
			margin-left: 6px;
		}
	}
}
</style>

数据类型

/**
 * 倒计时选项类型
 * 用于配置倒计时的参数
 */
type UnCountDownOptions = {
    time: number;  // 倒计时总时长（毫秒）
    millisecond?: boolean;  // 是否开启毫秒级显示
    keepRunning?: boolean;  // 是否持久化状态
    uniqueKey?: string;  // 存储的唯一标识
    onStart?: () => void;  // 开始回调
    onChange?: (value: UnCurrentTime) => void;  // 变化回调
    onEnd?: () => void;  // 结束回调
}

/**
 * 当前时间类型
 * 用于表示倒计时的当前状态，补零后为字符串类型，不补0时为数字类型
 */
type UnCurrentTime = {
    total: number;  // 剩余总毫秒数
    days: number | string;  // 剩余天数
    hours: number | string;  // 剩余小时数（0-23）
    minutes: number | string;  // 剩余分钟数（0-59）
    seconds: number | string;  // 剩余秒数（0-59）
    milliseconds: number | string;  // 剩余毫秒数（0-999）
}

注意事项

  1. 唯一标识：当页面有多个倒计时实例时，建议设置不同的 uniqueKey 以避免状态冲突
  2. 组件卸载：组件卸载时会自动暂停倒计时，无需手动处理

Copyright © 2026 uView Next