xtf-countdown

组件说明

xtf-countdown 是倒计时组件，用于展示剩余时间。支持多种格式（天/时/分/秒/毫秒）、块状/翻牌/文字模式、自定义分隔符、标签显示和暂停/恢复/重置方法，适用于限时抢购、活动倒计时和验证码倒计时等场景。

---

基础用法

1. 最简示例

通过 time 设置倒计时毫秒数：

<template>
  <xtf-countdown :time="3600000" format="HH:MM:SS" />
</template>

2. 包含天数与毫秒

通过 format 添加天数和毫秒，通过 millisecond 启用毫秒精度：

<template>
  <view style="display: flex; flex-direction: column; gap: 16rpx">
    <xtf-text level="caption" color="secondary">含天数</xtf-text>
    <xtf-countdown :time="86400000 * 3 + 3600000" format="DD:HH:MM:SS" />

    <xtf-text level="caption" color="secondary">含毫秒</xtf-text>
    <xtf-countdown :time="60000" format="MM:SS:ms" millisecond />
  </view>
</template>

3. 显示模式与标签

通过 mode 切换显示模式，通过 showLabels 显示时间单位标签：

<template>
  <view style="display: flex; flex-direction: column; gap: 24rpx">
    <xtf-text level="caption" color="secondary">块状模式</xtf-text>
    <xtf-countdown :time="7200000" format="HH:MM:SS" mode="block" show-labels />

    <xtf-text level="caption" color="secondary">翻牌模式</xtf-text>
    <xtf-countdown :time="7200000" format="HH:MM:SS" mode="flip" />

    <xtf-text level="caption" color="secondary">文字模式</xtf-text>
    <xtf-countdown :time="7200000" format="HH:MM:SS" mode="text" />
  </view>
</template>

4. 手动控制

通过方法手动控制倒计时：

<template>
  <view>
    <xtf-countdown ref="countdown" :time="60000" format="MM:SS" :auto-start="false" />
    <xtf-button-group :gap="12" style="margin-top: 16rpx">
      <xtf-button label="开始" size="sm" @click="$refs.countdown.start()" />
      <xtf-button label="暂停" size="sm" type="light" @click="$refs.countdown.pause()" />
      <xtf-button label="继续" size="sm" type="light" @click="$refs.countdown.resume()" />
      <xtf-button
        label="重置"
        size="sm"
        type="light"
        theme="danger"
        @click="$refs.countdown.reset()"
      />
    </xtf-button-group>
  </view>
</template>

---

全部属性

属性	类型	默认值	作用描述	适用范围
time	Number	0	倒计时毫秒数	倒计时长度
format	String	'HH:MM:SS'	时间格式，支持 DD / HH / MM / SS / ms	格式化
autoStart	Boolean	true	是否自动开始	自动开始
millisecond	Boolean	false	是否启用毫秒精度	毫秒精度
mode	String	'block'	显示模式：'block' / 'flip' / 'text'	视觉模式
separator	String	':'	分隔符	自定义分隔符
showLabels	Boolean	false	是否显示时间单位标签	标签显示
customClass	String	''	自定义类名	样式覆盖
customStyle	String | Object	''	自定义样式	动态样式覆盖

---

事件

事件名称	触发时机	回调参数	参数说明
change	倒计时变化时触发	(timeParts)	{ DD, HH, MM, SS, ms }
finish	倒计时结束时触发	-	-

事件使用示例

<template>
  <xtf-countdown :time="3000" @change="onChange" @finish="onFinish" />
</template>

<script>
export default {
  methods: {
    onChange(parts) {
      console.log('剩余', parts)
    },
    onFinish() {
      uni.showToast({ title: '倒计时结束', icon: 'none' })
    }
  }
}
</script>

---

方法

方法名	参数	返回值	说明
start	-	-	开始倒计时
pause	-	-	暂停倒计时
resume	-	-	继续倒计时
reset	(time?)	-	重置倒计时，可传入新的毫秒数

---

主题说明

• 块状/翻牌模式背景使用 var(--xtf-countdown-block-bg)
• 块状/翻牌模式文字使用 var(--xtf-countdown-block-text)
• 块状/翻牌模式阴影使用 var(--xtf-countdown-block-shadow)
• 翻牌模式分割线使用 var(--xtf-countdown-split-line)
• 分隔符颜色使用 var(--xtf-color-text-secondary)

如需全局调整主题，请在 xtf-config-provider 或主题配置中覆盖上述 CSS 变量。