From c118ddb392bdccb42ea00bff6a37637bcb895445 Mon Sep 17 00:00:00 2001
From: Shu Yi Kang <185901261@qq.com>
Date: Sun, 27 Oct 2024 17:20:27 +0800
Subject: [PATCH] feat: add useTimer

---
 packages/hooks/src/index.ts                   |   2 +
 .../src/useTimer/__tests__/index.test.ts      |  69 +++++++++
 packages/hooks/src/useTimer/demo/demo1.tsx    |  35 +++++
 packages/hooks/src/useTimer/demo/demo2.tsx    |  12 ++
 packages/hooks/src/useTimer/demo/demo3.tsx    |  15 ++
 packages/hooks/src/useTimer/index.en-US.md    |  64 ++++++++
 packages/hooks/src/useTimer/index.ts          | 140 ++++++++++++++++++
 packages/hooks/src/useTimer/index.zh-CN.md    |  62 ++++++++
 packages/hooks/src/useTimer/utils/index.ts    |  34 +++++
 9 files changed, 433 insertions(+)
 create mode 100644 packages/hooks/src/useTimer/__tests__/index.test.ts
 create mode 100644 packages/hooks/src/useTimer/demo/demo1.tsx
 create mode 100644 packages/hooks/src/useTimer/demo/demo2.tsx
 create mode 100644 packages/hooks/src/useTimer/demo/demo3.tsx
 create mode 100644 packages/hooks/src/useTimer/index.en-US.md
 create mode 100644 packages/hooks/src/useTimer/index.ts
 create mode 100644 packages/hooks/src/useTimer/index.zh-CN.md
 create mode 100644 packages/hooks/src/useTimer/utils/index.ts

diff --git a/packages/hooks/src/index.ts b/packages/hooks/src/index.ts
index 58cefd9c79..f3e272462e 100644
--- a/packages/hooks/src/index.ts
+++ b/packages/hooks/src/index.ts
@@ -75,6 +75,7 @@ import useVirtualList from './useVirtualList';
 import useWebSocket from './useWebSocket';
 import useWhyDidYouUpdate from './useWhyDidYouUpdate';
 import useMutationObserver from './useMutationObserver';
+import useTimer from './useTimer';
 
 export {
   useRequest,
@@ -156,4 +157,5 @@ export {
   useRafTimeout,
   useResetState,
   useMutationObserver,
+  useTimer,
 };
diff --git a/packages/hooks/src/useTimer/__tests__/index.test.ts b/packages/hooks/src/useTimer/__tests__/index.test.ts
new file mode 100644
index 0000000000..5e5d2eecb5
--- /dev/null
+++ b/packages/hooks/src/useTimer/__tests__/index.test.ts
@@ -0,0 +1,69 @@
+import { act, renderHook } from '@testing-library/react';
+import useTimer from '../index';
+
+describe('useTimer', () => {
+  let callback;
+
+  beforeAll(() => {
+    jest.useFakeTimers();
+  });
+
+  beforeEach(() => {
+    callback = jest.fn();
+  });
+
+  afterEach(() => {
+    callback.mockRestore();
+    jest.clearAllTimers();
+  });
+
+  afterAll(() => {
+    jest.useRealTimers();
+  });
+
+  it('test countdown', async () => {
+    const hook = renderHook(() =>
+      useTimer<number>(3, {
+        onComplete: callback,
+        auto: false,
+      }),
+    );
+
+    jest.advanceTimersByTime(2999);
+    expect(callback).not.toHaveBeenCalled();
+
+    jest.advanceTimersByTime(10);
+    expect(callback).not.toHaveBeenCalled();
+
+    act(() => {
+      hook.result.current.start();
+    });
+    act(() => {
+      Promise.resolve(jest.advanceTimersByTime(3000));
+    });
+    expect(callback).toHaveBeenCalled();
+    expect(Number(hook.result.current.remainingTime)).toBeFalsy();
+    expect(Number(hook.result.current.seconds)).toBeFalsy();
+    expect(Number(hook.result.current.minutes)).toBeFalsy();
+    expect(Number(hook.result.current.hours)).toBeFalsy();
+    expect(Number(hook.result.current.days)).toBeFalsy();
+  });
+
+  it('test from pass', () => {
+    const hook = renderHook(() => useTimer<number>(new Date('1999, 4, 4')));
+    expect(hook.result.current.remainingTime).toBeTruthy();
+    expect(hook.result.current.seconds).toBeDefined();
+    expect(hook.result.current.minutes).toBeDefined();
+    expect(hook.result.current.hours).toBeDefined();
+    expect(hook.result.current.days).toBeDefined();
+  });
+
+  it('test from future', () => {
+    const hook = renderHook(() => useTimer<number>(new Date('2028-07-14')));
+    expect(hook.result.current.remainingTime).toBeTruthy();
+    expect(hook.result.current.seconds).toBeDefined();
+    expect(hook.result.current.minutes).toBeDefined();
+    expect(hook.result.current.hours).toBeDefined();
+    expect(hook.result.current.days).toBeDefined();
+  });
+});
diff --git a/packages/hooks/src/useTimer/demo/demo1.tsx b/packages/hooks/src/useTimer/demo/demo1.tsx
new file mode 100644
index 0000000000..cf2d987dd9
--- /dev/null
+++ b/packages/hooks/src/useTimer/demo/demo1.tsx
@@ -0,0 +1,35 @@
+import React from 'react';
+import useTimer from '..';
+
+export default () => {
+  const { seconds, minutes, hours, days, start, pause, reset, isPaused } = useTimer<number>(
+    1000 * 3,
+    {
+      onComplete: () => {
+        console.info('计时完成');
+      },
+      auto: false,
+    },
+  );
+
+  return (
+    <>
+      {isPaused && <span>暂停中</span>}
+      <div>
+        {days ? <span>{days}天 </span> : null}
+        <span style={{ fontSize: 20 }}>
+          {hours}:{minutes}:{seconds}
+        </span>
+      </div>
+      <button style={{ marginRight: 10 }} onClick={() => start()}>
+        开始/恢复
+      </button>
+      <button style={{ marginRight: 10 }} onClick={() => pause()}>
+        暂停
+      </button>
+      <button style={{ marginRight: 10 }} onClick={() => reset()}>
+        复位
+      </button>
+    </>
+  );
+};
diff --git a/packages/hooks/src/useTimer/demo/demo2.tsx b/packages/hooks/src/useTimer/demo/demo2.tsx
new file mode 100644
index 0000000000..76035a752b
--- /dev/null
+++ b/packages/hooks/src/useTimer/demo/demo2.tsx
@@ -0,0 +1,12 @@
+import React, { useRef } from 'react';
+import useTimer from '..';
+
+export default () => {
+  const time = useRef(new Date(1999, 4, 4));
+  const { seconds, minutes, hours, days } = useTimer<Date>(time.current);
+  return (
+    <div>
+      阿里巴巴至今已经{days}天 {hours}:{minutes}:{seconds}
+    </div>
+  );
+};
diff --git a/packages/hooks/src/useTimer/demo/demo3.tsx b/packages/hooks/src/useTimer/demo/demo3.tsx
new file mode 100644
index 0000000000..60a492f7e7
--- /dev/null
+++ b/packages/hooks/src/useTimer/demo/demo3.tsx
@@ -0,0 +1,15 @@
+import React, { useRef } from 'react';
+import useTimer from '..';
+
+export default () => {
+  const time = useRef(new Date('2028-07-14'));
+  const { seconds, minutes, hours, days } = useTimer<Date>(time.current, {
+    onComplete: () => console.log('计时结束'),
+    isCountDown: true,
+  });
+  return (
+    <div>
+      距离2028年洛杉矶奥运会还有{days}天 {hours}:{minutes}:{seconds}
+    </div>
+  );
+};
diff --git a/packages/hooks/src/useTimer/index.en-US.md b/packages/hooks/src/useTimer/index.en-US.md
new file mode 100644
index 0000000000..af68ec3892
--- /dev/null
+++ b/packages/hooks/src/useTimer/index.en-US.md
@@ -0,0 +1,64 @@
+---
+title: useTimer
+nav: Hooks
+group:
+  title: Scene
+  order: 5
+order: 2
+toc: content
+demo:
+  cols: 1
+---
+
+# useTimer
+
+Some methods for time management, such as countdown and timer. Consolidate operations related to time into a single hook. For example, the countdown function can be done without any mental burden, thereby improving its business logic on this basis, and the business logic does not need to include too many countdown functions
+
+# Examples
+
+## Basic usage
+
+<code src="./demo/demo1.tsx"></code>
+<code src="./demo/demo2.tsx"></code>
+<code src="./demo/demo3.tsx"></code>
+
+## API
+
+```ts
+const returnValue= useTimer<T extends number| Date >(
+  time: number | Date,
+  options: Options,
+  deps: DependencyList = [],
+):ReturnValue<T>;
+```
+
+### parameter
+
+| parameter | illustrate               | type    | default value |
+| --------- | ------------------------ | ------- | ------------- |
+| time      | Total countdown time (s) | number  | Date          |
+| options   | Related options          | Options | {}            |
+| deps      | Dependency array         | any[]   | []            |
+
+### return value
+
+| 参数          | 说明                                                                                                                                                                                                       | 类型                                                           |
+| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
+| seconds       | Calculate the remaining seconds                                                                                                                                                                            | string                                                         |
+| minutes       | The remaining minutes                                                                                                                                                                                      | string                                                         |
+| hours         | Calculate the remaining hours                                                                                                                                                                              | string                                                         |
+| days          | Number of days after division                                                                                                                                                                              | string                                                         |
+| remainingTime | How many milliseconds are left overall                                                                                                                                                                     | number                                                         |
+| isPaused      | Is it in pause (this parameter will only be returned if the passed parameter is of type number)                                                                                                            | boolean                                                        |
+| isCounting    | Is the countdown in progress (this parameter will only be returned if the passed parameter is of type number)                                                                                              | boolean                                                        |
+| start         | Start/Resume (this parameter will only be returned if the input parameter is of type number)                                                                                                               | () => void                                                     |
+| pause         | Pause (this parameter will only be returned if the input parameter is of type number)                                                                                                                      | () => void                                                     |
+| reset         | Reset, with Begin: whether to start immediately after reset; ResetTime: The number of milliseconds reset, default is time. (This parameter will only be returned if the input parameter is of type number) | (withBegin: boolean = false, resetTime: number = time) => void |
+
+### Options
+
+| 参数        | 说明                                           | 类型       | 默认值   |
+| ----------- | ---------------------------------------------- | ---------- | -------- |
+| onComplete  | The callback after the countdown ends          | () => void | () => {} |
+| auto        | Do you want to start the countdown immediately | boolean    | true     |
+| isCountDown | Is it mandatory to switch to countdown mode    | boolean    | false    |
diff --git a/packages/hooks/src/useTimer/index.ts b/packages/hooks/src/useTimer/index.ts
new file mode 100644
index 0000000000..4f837da566
--- /dev/null
+++ b/packages/hooks/src/useTimer/index.ts
@@ -0,0 +1,140 @@
+import type { DependencyList } from 'react';
+import { useState, useEffect, useRef, useMemo } from 'react';
+import useUpdateEffect from '../useUpdateEffect';
+import { formatTime } from './utils';
+
+interface Options {
+  onComplete?: () => void;
+  auto?: boolean;
+  isCountDown?: boolean;
+}
+type CheckNumber<Time, Type> = Time extends number ? Type : never;
+
+export interface ReturnValue<Time extends Date | number> {
+  seconds: string;
+  minutes: string;
+  hours: string;
+  days: string;
+  remainingTime: number;
+  start: CheckNumber<Time, () => void>;
+  pause: () => CheckNumber<Time, () => void>;
+  reset: CheckNumber<Time, (withBegin?: boolean, resetTime?: number) => void>;
+  isPaused?: boolean;
+  isCounting?: boolean;
+}
+
+function useTimer<T extends Date | number>(
+  time: Date | number,
+  options: Options = {},
+  deps: DependencyList = [],
+): ReturnValue<T> {
+  const [isPaused, setIsPaused] = useState(false);
+  const { auto = true, onComplete = () => {} } = options;
+  const [isCounting, setisCounting] = useState<boolean>(false);
+  const isCountDown = options.isCountDown || typeof time === 'number';
+  const timeRef = useRef<number>(
+    isCountDown ? (typeof time === 'number' ? Date.now() + time : Number(time)) : Number(time),
+  );
+  const timeHandle = useRef<number>();
+  const [timeProperties, setTimeProperties] = useState(() => formatTime(timeRef.current, true));
+
+  const clearRef = () => {
+    timeHandle.current = 0;
+    setisCounting(false);
+    window.cancelAnimationFrame(timeHandle.current || 0);
+  };
+
+  const showTime = () => {
+    const formatedTime = formatTime(timeRef.current, !isCountDown);
+    setTimeProperties(formatedTime);
+    if (formatedTime.remainingTime >= 16 && timeHandle.current) {
+      timeHandle.current = window.requestAnimationFrame(() => showTime());
+    } else {
+      if (timeHandle.current) {
+        onComplete();
+        clearRef();
+      }
+    }
+  };
+
+  useEffect(() => {
+    if (!isCountDown || (auto && isCountDown)) {
+      setisCounting(true);
+      timeHandle.current = window.requestAnimationFrame(() => showTime());
+    }
+    return clearRef;
+  }, []);
+
+  useUpdateEffect(() => {
+    timeRef.current = isCountDown
+      ? typeof time === 'number'
+        ? Date.now() + time
+        : Number(time)
+      : Number(time);
+    setTimeProperties(() => formatTime(timeRef.current, true));
+    if (auto) {
+      setisCounting(true);
+      if (timeHandle.current) {
+        window.cancelAnimationFrame(timeHandle.current);
+      }
+      timeHandle.current = window.requestAnimationFrame(() => showTime());
+    }
+  }, [...deps, isCountDown && time]);
+
+  const timeMethods = useMemo(() => {
+    const start = () => {
+      setisCounting(true);
+      setIsPaused(false);
+      // 在开始前点击 timeRef.current > 0 并且 timeProperties.remainingTime  === number * 1000
+      // 在暂停后点击 timeProperties.remainingTime > 16 并且 timeHandle.current === 0
+      if (
+        (timeProperties.remainingTime >= 16 && !timeHandle.current) ||
+        (timeRef.current && timeProperties.remainingTime === Number(time))
+      ) {
+        timeRef.current = Date.now() + timeProperties.remainingTime;
+        timeHandle.current = window.requestAnimationFrame(() => showTime());
+      }
+    };
+
+    const pause = () => {
+      clearRef();
+      setisCounting(false);
+      setIsPaused(true);
+    };
+
+    const reset = (withBegin: boolean = false, resetTime: number = time as number) => {
+      clearRef();
+      const tempTimeProperties = formatTime(Date.now() + Number(resetTime));
+      setIsPaused(!withBegin);
+      setisCounting(withBegin);
+      setTimeProperties(tempTimeProperties);
+      if (withBegin) {
+        timeRef.current = Date.now() + tempTimeProperties.remainingTime;
+        timeHandle.current = window.requestAnimationFrame(() => showTime());
+      }
+    };
+
+    return {
+      start,
+      pause,
+      reset,
+    };
+  }, [timeProperties, isCounting, isPaused]);
+
+  if (isCountDown) {
+    // @ts-ignore
+    return {
+      ...timeProperties,
+      ...timeMethods,
+      isCounting,
+      isPaused,
+      isPausing: isPaused,
+    } as ReturnValue<number>;
+  }
+  // @ts-ignore
+  return {
+    ...timeProperties,
+  } as ReturnValue<Date>;
+}
+
+export default useTimer;
diff --git a/packages/hooks/src/useTimer/index.zh-CN.md b/packages/hooks/src/useTimer/index.zh-CN.md
new file mode 100644
index 0000000000..86c8381c43
--- /dev/null
+++ b/packages/hooks/src/useTimer/index.zh-CN.md
@@ -0,0 +1,62 @@
+---
+title: useTimer
+nav: Hooks
+group:
+  title: Scene
+  order: 5
+order: 2
+toc: content
+demo:
+  cols: 1
+---
+
+针对时间管理的一些方法，如倒计时和计时器。将关于时间的操作统一收敛到一个hooks里面。例如，可以毫无心智负担地去做倒计时功能,从而在此基础上去完善其业务逻辑，业务逻辑不用包含过多的倒计时功能
+
+# 代码演示
+
+## 基础用法
+
+<code src="./demo/demo1.tsx"></code>
+<code src="./demo/demo2.tsx"></code>
+<code src="./demo/demo3.tsx"></code>
+
+## API
+
+```ts
+const returnValue= useTimer<T extends number| Date >(
+  time: number | Date,
+  options: Options,
+  deps: DependencyList = [],
+):ReturnValue<T>;
+```
+
+### 参数
+
+| 参数    | 说明              | 类型    | 默认值 |
+| ------- | ----------------- | ------- | ------ |
+| time    | 倒计时的总时间(s) | number  | Date   |
+| options | 相关选项          | Options | {}     |
+| deps    | 依赖数组          | any[]   | []     |
+
+### 返回值
+
+| 参数          | 说明                                                                                                                        | 类型                                                           |
+| ------------- | --------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
+| seconds       | 求余后的秒数                                                                                                                | string                                                         |
+| minutes       | 求余后的分钟数                                                                                                              | string                                                         |
+| hours         | 求余后的小时数                                                                                                              | string                                                         |
+| days          | 整除后的天数                                                                                                                | string                                                         |
+| remainingTime | 总体还剩多少毫秒                                                                                                            | number                                                         |
+| isPaused      | 是否处于暂停中（只有传入的参数是 number 类型才会返回此参数）                                                                | boolean                                                        |
+| isCounting    | 是否正在倒计时中（只有传入的参数是 number 类型才会返回此参数）                                                              | boolean                                                        |
+| start         | 开始/恢复（只有传入的参数是 number 类型才会返回此参数）                                                                     | () => void                                                     |
+| pause         | 暂停（只有传入的参数是 number 类型才会返回此参数）                                                                          | () => void                                                     |
+| reset         | 复位，withBegin：是否在复位后立即开始；resetTime：复位的毫秒数，默认是 time。（只有传入的参数是 number 类型才会返回此参数） | (withBegin: boolean = false, resetTime: number = time) => void |
+
+### Options
+
+| 参数        | 说明                 | 类型       | 默认值   |
+| ----------- | -------------------- | ---------- | -------- |
+| onComplete  | 倒计时结束后的回调   | () => void | () => {} |
+| auto        | 是否立即开始倒计时   | boolean    | true     |
+| isCountDown | 是否强制为倒计时模式 | boolean    | false    |
diff --git a/packages/hooks/src/useTimer/utils/index.ts b/packages/hooks/src/useTimer/utils/index.ts
new file mode 100644
index 0000000000..68f6fc5180
--- /dev/null
+++ b/packages/hooks/src/useTimer/utils/index.ts
@@ -0,0 +1,34 @@
+const pad = (value: number): string =>
+  value > 100 ? String(value) : `0${Math.floor(value)}`.slice(-2);
+
+const getRemainingTime = (deadline: number): number => {
+  const currentTime = Date.now();
+  return deadline - currentTime;
+};
+
+const formatTime = (time: number, isAbs: boolean = false) => {
+  const remainingTime = isAbs ? Math.abs(getRemainingTime(time)) : getRemainingTime(time);
+  if (remainingTime < 0) {
+    // 如果小于0，代表从其他tab切回来，时间已经过了endTime，所以直接显示0即可。
+    return {
+      remainingTime: 0,
+      seconds: '00',
+      minutes: '00',
+      hours: '00',
+      days: '00',
+    };
+  }
+  const seconds = pad(Math.floor(remainingTime / 1000) % 60);
+  const minutes = pad(Math.floor(remainingTime / (60 * 1000)) % 60);
+  const hours = pad(Math.floor(remainingTime / (60 * 60 * 1000)) % 24);
+  const days = pad(Math.floor(remainingTime / (24 * 60 * 60 * 1000)));
+
+  return {
+    remainingTime,
+    seconds,
+    minutes,
+    hours,
+    days,
+  };
+};
+export { pad, getRemainingTime, formatTime };