diff --git a/packages/vant-use/.vuepress/config.js b/packages/vant-use/.vuepress/config.js index 42a7222f5..5999612b2 100644 --- a/packages/vant-use/.vuepress/config.js +++ b/packages/vant-use/.vuepress/config.js @@ -21,7 +21,7 @@ module.exports = { { title: 'State', collapsable: false, - children: ['/src/useToggle/'], + children: ['/src/useToggle/', '/src/useCountDown/'], }, { title: 'DOM', diff --git a/packages/vant-use/src/useCountDown/README.md b/packages/vant-use/src/useCountDown/README.md new file mode 100644 index 000000000..669ad6ca7 --- /dev/null +++ b/packages/vant-use/src/useCountDown/README.md @@ -0,0 +1,118 @@ +# useCountDown + +提供倒计时管理能力。 + +## 代码演示 + +### 基本用法 + +```html +总时间:{{ current.total }} +剩余天数:{{ current.days }} +剩余小时:{{ current.hours }} +剩余分钟:{{ current.minutes }} +剩余秒数:{{ current.seconds }} +剩余毫秒:{{ current.milliseconds }} +``` + +```js +import { useCountDown } from '@vant/use'; + +export default { + setup() { + const countDown = useCountDown({ + // 倒计时 24 小时 + time: 24 * 60 * 60 * 1000, + }); + + // 开始倒计时 + countDown.start(); + + return { + current: countDown.current, + }; + }, +}; +``` + +### 毫秒级渲染 + +倒计时默认每秒渲染一次,设置 millisecond 属性可以开启毫秒级渲染。 + +```js +import { useCountDown } from '@vant/use'; + +export default { + setup() { + const countDown = useCountDown({ + time: 24 * 60 * 60 * 1000, + millisecond: true, + }); + countDown.start(); + + return { + current: countDown.current, + }; + }, +}; +``` + +## API + +### 类型定义 + +```ts +function useCountDown(options: UseCountDownOptions): CountDown; + +type UseCountDownOptions = { + time: number; + millisecond?: boolean; + onChange?: (current: CurrentTime) => void; + onFinish?: () => void; +}; + +type CountDown = { + start: () => void; + pause: () => void; + reset: (totalTime: number) => void; + current: ComputedRef; +}; + +type CurrentTime = { + days: number; + hours: number; + total: number; + minutes: number; + seconds: number; + milliseconds: number; +}; +``` + +### 参数 + +| 参数 | 说明 | 类型 | 默认值 | +| --- | --- | --- | --- | +| time | 倒计时时长,单位毫秒 | _number_ | - | +| millisecond | 是否开启毫秒级渲染 | _boolean_ | `false` | +| onChange | 倒计时改变时触发的回调函数 | _(current: CurrentTime) => void_ | - | +| onFinish | 倒计时结束时触发的回调函数 | - | + +### 返回值 + +| 参数 | 说明 | 类型 | +| ------- | ---------------------------------- | ----------------------- | +| current | 当前剩余的时间 | _CurrentTime_ | +| start | 开始倒计时 | _() => void_ | +| pause | 暂停倒计时 | _() => void_ | +| reset | 重置倒计时,支持传入新的倒计时时长 | _(time?: number): void_ | + +### CurrentTime 格式 + +| 名称 | 说明 | 类型 | +| ------------ | ---------------------- | -------- | +| total | 剩余总时间(单位毫秒) | _number_ | +| days | 剩余天数 | _number_ | +| hours | 剩余小时 | _number_ | +| minutes | 剩余分钟 | _number_ | +| seconds | 剩余秒数 | _number_ | +| milliseconds | 剩余毫秒 | _number_ |