Sweet Hooks 文档

> 一个功能丰富的 React Hooks 集合，提供各种实用的自定义 Hooks

📚 目录

$3

- usStyle - 动态加载和执行 CSS
- useClickOutside - 管理元素外点击事件
- useFullscreen - 全屏控制
- useHover - 鼠标悬停状态
- useInView - 元素可见性检测
- useSize - 元素尺寸监听
- useVirtualList - 虚拟列表
- useWatermark - 水印功能

$3

- useBoolean - 布尔状态管理
- useNumber - 数字状态管理
- useToggle - 切换状态管理
- useResetState - 可重置状态
- useStateRealtime - 实时状态
- useUrlState - URL 状态同步

$3

- useAsyncEffect - 异步副作用
- useDeepEffect - 深度比较副作用
- useDeepUpdateEffect - 深度比较更新副作用
- useUpdateEffect - 更新副作用
- useUnmount - 卸载副作用
- useMounted - 挂载状态

$3

- useDebounce - 值防抖
- useDebounceFn - 函数防抖
- useThrottle - 值节流
- useThrottleFn - 函数节流
- useInterval - 间隔执行
- useTimer - 定时器管理

$3

- useFilter - 数据过滤
- useHistory - 历史记录
- usePersistCallback - 持久化回调
- usePrevious - 前一个值
- useStorage - 本地存储

$3

- useEventListener - 事件监听
- useEventBus - 事件总线
- useKeyPress - 键盘事件
- useLockFn - 函数锁

$3

- useClipboardCopy - 剪贴板操作
- useCookie - Cookie 管理
- useFavicon - 网站图标
- useMedia - 媒体查询
- useNetwork - 网络状态
- usePageVisible - 页面可见性
- useScript - 脚本加载
- useTitle - 页面标题

$3

- useCatchError - 错误捕获
- useDeepMemo - 深度记忆
- useExposureTrack - 曝光追踪
- useForceUpdate - 强制更新
- useKeepPage - 页面保持
- useMouse - 鼠标位置
- useScroll - 滚动状态
- useScrollLock - 滚动锁定
- useSyncScroll - 同步滚动

---

🎨 UI 相关 Hooks

$3

用于动态加载 CSS 或执行 CSS 的 hook。

#### API

``ts
const [loadedState, errorState] = usStyle(href: string, properties?: StyleProperties);
`

参数

| 参数 | 说明 | 类型 |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------- |
| href | 样式文件地址 | string |
| properties | HTMLLinkElement 支持的属性或HTMLStyleElement 支持的属性 | StyleProperties |

返回值

| 参数 | 说明 | 类型 |
| ----------- | -------------------- | ------------------ |
| loadedState | 样式文件是否加载完毕 | Boolean |
| errorState | 样式文件加载错误实例 | ErrorEvent \| null |

---

$3

在 useEffect 中使用异步函数

核心特性

- 支持异步 effect 函数

#### API

`ts
useAsyncEffect(
asyncEffectCallback: () => Promise void)>,
deps?: DependencyList,
);
`

参数

| 参数 | 说明 | 类型 | 默认值 |
| ------------------- | ---------------- | ----------------------------------- | ------ |
| asyncEffectCallback | 异步 effect 函数 | () => Promise void)> | - |
| deps | 依赖数组 | DependencyList \| undefined | - |

---

⚡ 状态管理 Hooks

$3

管理 boolean 类型状态的 hook。

#### API

`ts
const result: {
state: boolean;
setTrue: () => void;
setFalse: () => void;
toggle: (value?: boolean) => void;
} = useBoolean(initialValue?: boolean);
`

参数

| 参数 | 说明 | 类型 | 默认值 |
| ------------ | -------------------- | -------------------- | ------ |
| initialValue | 可选项，默认的状态值 | boolean \| undefined | false |

返回值

| 参数 | 说明 | 类型 |
| -------- | ------------------------------------------------- | --------------------- |
| state | 当前状态值 | boolean |
| toggle | 触发状态更改的函数,可以接受一个可选参数修改状态值 | (value?: any) => void |
| setTrue | 设置状态值为 true | () => void |
| setFalse | 设置状态值为 false | () => void |

---

$3

优雅的管理目标元素外点击事件的 hook。

#### API

`ts
const ref = useClickOutside(
dom: RefType = undefined,
onClickAway: (event: KeyboardEvent) => void,
): MutableRefObject;
`

参数

| 参数 | 说明 | 类型 |
| ----------- | ---------------------------------------------------------------- | ----------------------------------------------- |
| dom? | 可选项，如果未传入则会监听返回结果中的 ref，否则会监听传入的节点 | HTMLElement \| (() => HTMLElement) \| undefined |
| onClickAway | 触发事件的函数 | (event) => void |

返回值

| 参数 | 说明 | 类型 |
| ---- | --------------------------------------------- | -------------------- |
| ref | 当未传入任何参数时，将 ref 绑定给需监听的节点 | MutableRefObject |

---

$3

用于方便处理剪切板复制场景的 hook。

核心特性

- 复制、剪切、清空
- 能力检测，复制记录
- 可手动传值，可自动取值

#### API

`ts
type Options = {
onSuccess?: (text: string) => void;
onError?: (error: any) => void;
}

type Result = {
ref: React.MutableRefObject;
isSupported: boolean;
isCopied: boolean;
copyText: string;
copy: (text?: string) => void;
cut: () => void;
clear: () => void;
}

const result: Result = useClipboardCopy(options: Options = {});
`

参数

| 参数 | 说明 | 类型 |
| --------- | ------------ | ---------------------- |
| onSuccess | 复制成功回调 | (text: string) => void |
| onError | 复制失败回调 | (error: any) => void |

返回值

| 参数 | 说明 | 类型 |
| ----------- | ------------------------------------------------------------------------------ | --------------------------------------- |
| ref | 要复制内容所在元素，会尝试读取 value 属性或 innerText 属性 | React.MutableRefObject\ |
| isSupported | 是否支持剪切板相关 API，会检查 navigator.clipboard 和 document.execCommand | boolean |
| isCopied | 是否已经复制过 | boolean |
| copyText | 上一次被复制的文字 | string |
| copy | 复制，可手动传值，也可通过绑定元素取值 | (text?: string) => void |
| cut | 剪切，会先清空绑定元素的值再复制 | () => void |
| clear | 清空剪切板 | () => void |

---

$3

用于同步和管理 cookie 的 hook。

#### API

`ts
const [state, setState] = useCookie(
key: string,
defaultValue?: T,
raw: boolean = true,
): [T | undefined, (value?: T | (previousValue: T) => T), options?: Cookies.CookieAttributes) => void];
`

参数

| 参数 | 说明 | 类型 | 默认值 |
| ------------ | ---------------------------------------------------- | ------- | ------ |
| key | 键名 | string | - |
| defaultValue | 默认值，服务端渲染或取值失败时使用 | T | - |
| raw | 是否使用原始数据，即关闭 JSON 处理，默认使用原始数据 | boolean | true |

返回值

| 参数 | 说明 | 类型 |
| -------- | -------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| state | 键名对应的 cookie 的值或默认值 | T \| undefined |
| setState | 设置键名对应的 cookie 的值以及设置属性，不传值时表示删除 | (value?: T \| (previousValue: T) => T), options?: Cookies.CookieAttributes) => void |

options

参见 js-cookie#cookie-attributes

---

$3

用来处理值防抖的 hook。

#### API

`ts
const debouncedValue = useDebounce(
value: any,
wait: number
);
`

参数

| 参数 | 说明 | 类型 | 默认值 |
| ----- | ------------------------ | ------ | ------ |
| value | 需要防抖的值 | any | - |
| wait | 防抖等待时间，单位为毫秒 | number | 1000 |

返回值

| 参数 | 说明 | 类型 |
| ----- | ---------- | ---- |
| value | 防抖后的值 | any |

---

$3

用来处理函数防抖的 hook。

#### API

`ts
const {
run,
cancel
} = useDebounceFn(
fn: (...args: any[]) => any,
wait: number = 1000
deps: any[] = [],
options: Options = {
immediately: false,
trailing: true,
leading: false,
}
);
`

参数

| 参数 | 说明 | 类型 | 默认值 |
| ------- | ------------------------------------------------- | ----------------------- | ------ |
| fn | 需要防抖执行的函数 | (...args: any[]) => any | - |
| wait | 防抖等待时间，单位为毫秒 | number | 1000 |
| deps | 依赖数组，如果数组变化，则会在等待时间后，触发 fn | any[] | [] |
| options | 可选配置项，见 Options | {} |

返回值

| 参数 | 说明 | 类型 |
| ------ | ---------------------------------- | ----------------------- |
| run | 触发执行 fn，函数参数将会传递给 fn | (...args: any[]) => any |
| cancel | 取消当前防抖 | () => void |

$3

| 参数 | 说明 | 类型 | 默认值 |
| ----------- | ---------------------------------------- | ------- | ------ |
| immediately | 是否在第一次立即执行 | boolean | false |
| trailing | 是否在下降沿执行相关函数，即延迟后执行 | boolean | true |
| leading | 是否在上升沿执行相关函数，即在延迟前执行 | boolean | false |

---

###useDeepEffect

当依赖参数在深比较后与上一次内容相同时，返回上一次的内容，避免重复的副作用执行。可以传入自定义的比较函数，根据比较的结果控制是否执行副作用。

#### API

`ts

useDeepEffect(callback: React.EffectCallback, deps: T[]): void;

useDeepEffect(
callback: React.EffectCallback,
isEqual: (prev:T[],cur: T[]) => boolean,
deps: T[]
): void;
`

参数

| 参数 | 说明 | 类型 | 默认值 |
| -------- | -------------------------------------------------------- | -------------------------------------------------------------- | -------------- |
| callback | 需要执行的副作用 | Function | - |
| deps | 执行副作用监听的依赖数组 | Array | - |
| isEqual | 自定义用于比较参数前后状态，根据返回值控制是否执行副作用 | 可选参数；函数类型，第一个参数为上一状态值，第二个参数为当前值 | lodash.isEqual |

返回值

| 参数 | 说明 | 类型 |
| ---- | ---------------------------------------------------------- | ---- |
| - | 通过深比较或自定义比较后，只在比较结果为 true 时执行副作用 | - |

---

$3

当参数在深比较后与上一次内容相同时，返回上一次的内容，避免重复的副作用执行。可以传入自定义的比较函数，根据比较的结果控制是否返回新内容。

#### API

`ts

const memoizedValue: T = useDeepMemo(value: T, isEqual?: (prev: T, cur: T) => boolean);

`

参数

| 参数 | 说明 | 类型 | 默认值 |
| ------- | -------------------------------------------------------- | -------------------------------------------------------------- | -------------- |
| value | 传入参数 | 通常传入 object 等引用类型 | - |
| isEqual | 自定义用于比较参数前后状态，根据返回值控制是否返回的内容 | 可选参数；函数类型，第一个参数为上一状态值，第二个参数为当前值 | lodash.isEqual |

返回值

| 参数 | 说明 | 类型 |
| ------------- | ------------------------------------------------------------------------------ | ------------------ |
| memoizedValue | 通过深比较或自定义比较后，若比较结果为 false，则返回新内容，反之返回之前的内容 | 与传入参数同一类型 |

---

$3

useDeepUpdateEffect 是一个自定义的 React Hook，它在组件更新时执行副作用，但首次渲染时不执行。只有当依赖数组中的值在深度比较后发生变化时，才会触发该副作用。

#### API

参数

| 参数 | 说明 | 类型 | 默认值 |
| ------ | ---------------- | ---------------------- | ------ |
| effect | 需要执行的副作用 | React.EffectCallback | - |
| deps | 副作用的依赖数组 | T[] | - |

返回值

| 参数 | 说明 | 类型 |
| ---- | ---------------------------------------- | ---- |
| - | 只在深度比较依赖数组发生变化时执行副作用 | - |

$3

hooks 版本的 EventBus 实现，用于全局事件的发布与订阅。封装了自动化取消订阅的逻辑，同时 callback 中的 state 永远最新，无需手动声明依赖。

#### API

`ts
const { trigger, unsubscribe, subscribe } = useEventBus(
eventName: string,
callback?: Function,
): { trigger: Function, unsubscribe?: Function，subscribe?: Function };
`

参数

| 参数 | 说明 | 类型 | 默认值 |
| --------- | ---------------------------------- | -------- | ------ |
| eventName | 事件名称 | string | - |
| callback | 事件回调，注册事件时需要传入此参数 | Function | - |

返回值

| 参数 | 说明 | 类型 |
| ----------- | ---------------------------------------------------------------- | --------------------- |
| trigger | 事件触发器 | Function |
| subscribe | 订阅函数，若 useEventBus 没有传入 callback, 则值为 undefined | Function \| undefined |
| unsubscribe | 取消订阅函数，若 useEventBus 没有传入 callback, 则值为 undefined | Function \| undefined |

$3

用于添加/移除监听事件的 hook。

#### API

`ts
const ref = useEventListener(
eventName: string,
eventListener: Function,
options?: { target: Target, capture?: boolean; once?: boolean; passive?: boolean; },
});

type Target = Window | HTMLElement | null | undefined;
`

参数

| 参数 | 说明 | 类型 |
| ------------- | ---------------------- | -------- |
| eventName | 事件名称 | string |
| eventListener | 事件监听回调函数 | Function |
| options | 可选配置项，见 Options | Options |

返回值

| 参数 | 说明 | 类型 |
| ---- | ------------------------------------------------------------------- | ------------------------------------ |
| ref | 元素 ref，若监听 window 事件或设置了 options.target，可忽略此返回值 | React.MutableRefObject |

$3

| 参数 | 说明 | 类型 | 默认值 |
| ------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- | ---------- |
| target | 监听对象，若不填写，将监听应用 ref 的对象 | HTMLElement \| null \| window | undefined |
| capture | 设置为 true 表示 eventListener 会在该类型的事件捕获阶段传播到该 target 时触发。 | boolean | false |
| once | 设置为 true 表示 eventListener 在事件触发后只执行一次 | boolean | false |
| passive | 同原生 passive 参数，具体可见：让页面滑动流畅得飞起的新特性：Passive Event Listeners。 | boolean | false |

$3

一个用于追踪元素曝光的 hook。

性能优化说明：该 hook 内部的所有回调函数都已使用 useCallback 进行包裹。

重要提示：传入的回调函数必须使用 useCallback 包裹，以免产生不可预期的行为。

何时使用

当你需要对页面中的某些元素进行曝光统计时，可以使用此 hook。例如，广告的曝光、商品的曝光等。

#### API

`ts
useExposureTrack(
onExposure: ExposureCallback,
options?: ExposureOptions
)
`

参数

| 参数 | 说明 | 类型 | 默认值 |
| ---------- | ---------------------- | ----------------------------------------- | ------ |
| onExposure | 曝光回调函数 | (data: T, element: HTMLElement) => void | - |
| options | 可选配置项，见 Options | ExposureOptions | {} |

$3

| 参数 | 说明 | 类型 | 默认值 |
| ---------- | ------------------ | ----------------------- | ------- |
| delay | 曝光延迟时间（ms） | number | 100 |
| threshold | 曝光阈值，0-1 之间 | number | 0.1 |
| rootMargin | root 的外边距 | string | '0px' |
| root | 监听的根元素 | HTMLElement \| null | null |

$3

在需要曝光的元素上添加 data-exposure 属性，值为一个 JSON 字符串。

`html



`

---

$3

用于设置页面的 favicon 图标。

#### API

`ts
useFavicon(url: string)
`

参数

| 参数 | 说明 | 类型 |
| ---- | ---------------------------------------------------------- | ------ |
| url | favicon 图标的 url，支持 gif、ico、jpeg、png 和 svg 的后缀 | string |

---

$3

一个用于在客户端进行模糊过滤的 hook。

何时使用

当你需要一个在客户端根据输入动态过滤列表的功能时，可以使用此 hook。

#### API

`ts
const { filteredData, setMatcher, setData } = useFilter(options: FilterOptions);
`

$3

| 参数 | 说明 | 类型 | 默认值 |
| ------------- | -------------------- | ------------ | ------- |
| data | 要过滤的原始数据数组 | T[] | [] |
| matcher | 用于匹配的键值对对象 | Partial | {} |
| caseSensitive | 是否区分大小写 | boolean | false |

返回值

| 参数 | 说明 | 类型 |
| ------------ | ---------------- | ------------------------------- |
| filteredData | 过滤后的数据数组 | T[] |
| setMatcher | 用于更新匹配条件 | (matcher: Partial) => void |
| setData | 用于更新原始数据 | (data: T[]) => void |

---

$3

用于强制更新组件的 hook，通常在 useRef 管理可变状态，但又需要重渲染时使用。

#### API

`ts
const forceUpdate = useForceUpdate();
`

返回值

| 参数 | 说明 | 类型 |
| ----------- | -------------------------------------------------------- | ---------- |
| forceUpdate | 用于调用强制更新的函数，同一个函数多次调用也只会更新一次 | () => void |

---

$3

用于控制 DOM 元素全屏状态的 hook。

#### API

`ts
const {
isFullscreen,
setFull,
exitFull,
ref?,
} = useFullScreen(
el?: T | (() => T),
options?: Options,
);
`

参数

| 参数 | 说明 | 类型 |
| ------- | ---------------------------------------------------------------- | ----------------------------------------------- |
| el | 可选项，如果未传入则会监听返回结果中的 ref，否则会监听传入的节点 | HTMLElement \| (() => HTMLElement) \| undefined |
| options | 如下 | Options |

$3

| 参数 | 说明 | 类型 | 默认值 |
| ------------------- | ------------------ | ---------- | ------ |
| defaultValue | 是否默认全屏 | boolean | false |
| isBrowserFullscreen | 是否只是浏览器全屏 | boolean | false |
| onExitFull | 监听退出全屏 | () => void | - |
| onFull | 监听全屏 | () => void | - |

返回值

| 参数 | 说明 | 类型 |
| ------------ | --------------------------------------------- | --------------------------------------- |
| isFullscreen | 是否全屏 | boolean |
| setFull | 设置全屏 | () => void |
| exitFull | 退出全屏 | () => void |
| toggleFull | 切换全屏 | () => void |
| ref | 当未传入 el 参数时，将 ref 绑定给需全屏的节点 | React.MutableRefObject |

---

$3

管理状态变化历史，方便添加撤销 / 重做功能

核心特性

- 撤销
- 重做
- 状态管理

#### API

`ts
const result: ReturnValue = useHistory(
initialPresent: T
);
`

参数

| 参数 | 说明 | 类型 |
| -------------- | ------------ | ---- |
| initialPresent | 初始化 value | T |

返回值

| 参数 | 说明 | 类型 |
| ------- | ------------ | ----------------------- |
| state | 状态 Map | T |
| set | 存储状态 | (newPresent: T) => void |
| undo | 撤销 | () => void |
| redo | 重做 | () => void |
| clear | 清空状态池 | () => void |
| canUndo | 是否可以撤销 | boolean |
| canRedo | 是否可以重做 | boolean |

---

$3

用于感知元素是否处于 hover 状态的 hook。

#### API

`ts
const [ref, isHovered] = useHover(
el?: T | (() => T),
options?: Options,
deps: any[] = [],
): [React.MutableRefObject, boolean];
`

参数

| 参数 | 说明 | 类型 |
| ------- | ------------------------------------------------------------------------------ | ------------ |
| el | 监听的 DOM 元素，若使用 ref 可不传 | T \| () => T |
| options | 可选配置项，见 Options | Options |
| deps | 依赖数组，如果数组变化，则会重新绑定事件，在元素为懒加载时使用，否则会处理失败 | any[] |

返回值

| 参数 | 说明 | 类型 |
| --------- | -------------- | --------------------------------------- |
| ref | 元素 ref | React.MutableRefObject |
| isHovered | 元素是否 Hover | boolean |

$3

| 参数 | 说明 | 类型 |
| ------- | -------------------- | ---------- |
| onEnter | 鼠标移入时触发的回调 | () => void |
| onLeave | 鼠标移出时触发的回调 | () => void |

---

$3

用于感知元素是否处于可视范围的 hook，可用于懒加载、埋点等场景。

#### API

`ts
const [ref, inView] = useInView(
el?: T | (() => T),
options?: IntersectionObserverInit,
deps: any[] = [],
cb?: () => void,
): [React.MutableRefObject, boolean];
`

参数

| 参数 | 说明 | 类型 |
| ------- | ------------------------------------------------------------------------------ | ------------------------ |
| el | 监听的 DOM 元素，若使用 ref 可不传 | T \| () => T |
| options | IntersectionObserver 监听配置 | IntersectionObserverInit |
| deps | 依赖数组，如果数组变化，则会重新绑定事件，在元素为懒加载时使用，否则会处理失败 | any[] |
| cb | 可选的回调，在处于可视范围的时候，会发回调 | () => void |

返回值

| 参数 | 说明 | 类型 |
| ------ | -------------------------- | --------------------------------------- |
| ref | 元素 ref，未传入 el 时使用 | React.MutableRefObject |
| inView | 元素是否处于可视范围 | boolean |

---

$3

用于方便控制 setInterval 的 hook。

#### API

`ts
import { DependencyList } from 'react';
interface IUseIntervalOptions {
deps?: DependencyList
}

const { run, cancel } = useInterval(callback: Function, delay: number, immediate = true, options: IUseIntervalOptions = {}): {
run: () => void;
cancel: () => void;
};
`

参数

| 参数 | 说明 | 类型 | 默认值 |
| --------- | ------------------------------------------------------------------------------------ | ------------------------------------------- | ------ |
| callback | 要重复调用的函数 | Function | - |
| delay | 每次延迟的毫秒数 | number | - |
| immediate | 定时器是否立即启动，也可使用返回的 run 函数启动 | boolean | true |
| options | deps(可选): 一个依赖列表，当其中的依赖更新时，自动执行 run（需要 immediate 为 true） | {
  deps?: DependencyList
} | {} |

返回值

| 参数 | 说明 | 类型 |
| ------ | ---------- | ---------- |
| run | 启动定时器 | () => void |
| cancel | 结束定时器 | () => void |

---

$3

在关闭或刷新页面时给出提示，尤其适用于填写表单的页面。

#### API

`ts
const [shouldKeepPage, setShouldKeepPage] = useKeepPage(
initShouldKeepPage: boolean,
onLeave?: Function,
): [boolean, React.Dispatch>];
`

参数

| 参数 | 说明 | 类型 |
| --------------------- | ---------------------------------------------------------------------------- | -------- |
| initialShouldKeepPage | 是否应在关闭或刷新页面前提示 | boolean |
| onLeave | 可选参数，在 beforeunload 事件发生且 shouldKeepPage 为 true 时执行的回调函数 | Function |

返回值

| 参数 | 说明 | 类型 |
| ----------------- | ------------------------------------------ | -------- |
| shouldKeepPage | 是否应在关闭或刷新页面前提示 | boolean |
| setShouldKeepPage | 设置是否应在关闭或刷新页面前提示的回调函数 | Function |

---

$3

用于方便管理键盘事件的 hook，设置组合键，绑定快捷键。

#### API

`ts
const ref = useKeyPress(
keyFilter: KeyFilter,
eventHandler: EventHandler = noop,
option: EventOption = {},
): RefObject
`

参数

> Tips: keyType 为键盘事件中的 key 和 keyCode

| 参数 | 说明 | 类型 |
| ------------ | ---------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| keyFilter | 支持键盘事件中的 key 和 keyCode，支持回调方式返回 boolean 判断，支持别名使用 | keyType \| Array \| ((event: KeyboardEvent) => boolean) |
| eventHandler | 事件回调函数 | (event: KeyboardEvent) => void |
| options | 可选配置项，见 Options | Options |

返回值

| 参数 | 说明 | 类型 |
| ---- | ------------------------------------------------- | ------------- |
| ref | 当未传入任何 target 时，将 ref 绑定给需监听的节点 | RefObject |

$3

| 参数 | 说明 | 类型 | 默认值 |
| ------ | ---------------------------------------------------------------------------------------- | --------------------------------------------------------- | ----------- |
| events | 触发事件 | Array | ['keydown'] |
| target | 可选，如果未传入，则监听返回结果中的 ref，否则监听传入的节点，默认情况下监听 window | window \| HTMLElement \| (() => HTMLElement) \| undefined | window |
| exact | 精确模式。若设为 true，则只有当真实事件和 keyFilter 所描述的修饰键完全一致时才视为匹配。 | boolean | false |

备注

1.全部的按键别名

`
enter
tab
delete (捕获“删除”和“退格”键)
esc
space
up
down
left
right
`

2.修饰键

`
ctrl
alt
shift
meta
`

---

$3

避免重复提交请求

核心特性

在提交函数请求执行完成之前，会忽略再次点击请求操作

#### API

`ts
const { fn } = useLockFn(
fn: (...args: any[]) => any
);
`

参数

| 参数 | 说明 | 类型 | 默认值 |
| ---- | -------------------- | ---------------------- | ------ |
| fn | 需要增加竞态锁的函数 | (...args: any[])=> any | - |

返回值

| 参数 | 说明 | 类型 |
| ---- | ------------------ | ---------------------- |
| fn | 增加了竞态锁的函数 | (...args: any[])=> any |

---

$3

用于获取媒体查询结果的 hook，可用于响应式布局。

#### API

`ts
const state: boolean = useMedia(query: string | MediaQueryObject, defaultState: boolean | (() => boolean));
`

参数

| 参数 | 说明 | 类型 | 默认值 |
| ------------ | ---------------------------------------- | -------------------------- | ------ |
| query | 媒体查询规则，以字符串形式或对象形式传入 | string \| MediaQueryObject | - |
| defaultState | 默认状态，只在服务端渲染时使用 | boolean | false |

返回值

| 参数 | 说明 | 类型 | 默认值 |
| ----- | -------------------- | ------- | ------ |
| state | 是否匹配媒体查询规则 | boolean | false |

$3

| 参数 | 说明 | 类型 |
| ------ | ------------------------------------------------------------------------------------------------------------ | ---------------- |
| [rule] | CSS @media 规则的特性, 驼峰式写法，如 minWidth, maxDeviceAspectRatio, orientation 等，传入多个值时为“且”关系 | string \| number |

---

$3

组件加载完成后执行回调的 hook。

#### API

`ts
useMounted(fn: () => void): void
`

参数

| 参数 | 说明 | 类型 |
| ---- | -------------------- | ---------- |
| fn | 加载完成后执行的函数 | () => void |

---

$3

追踪鼠标在元素内坐标位置的 hook。

#### API

`ts
const [ref, state] = useMouse(
el?: Window | T | (() => T),
options?: Options,
deps: any[] = [],
): [React.MutableRefObject, State];
`

参数

| 参数 | 说明 | 类型 | 默认值 |
| ------- | ------------------------------------------------------------------------------ | ---------------------- | ------ |
| el | 鼠标坐标参照元素，若使用 ref 可不传 | T \| () => T | - |
| options | 可选配置项，如节流时间 | { throttle?: number; } | {} |
| deps | 依赖数组，如果数组变化，则会重新绑定事件，在元素为懒加载时使用，否则会处理失败 | any[] | [] |

返回值

| 参数 | 说明 | 类型 |
| ----- | -------------------------- | --------------------------------------- |
| ref | 元素 ref，未传入 el 时使用 | React.MutableRefObject |
| state | 鼠标坐标位置信息 | { x: number; y: number } |

---

$3

管理 number 类型状态的 hook。

#### API

`ts
const result: {
state: number;
inc: (delta?: number) => void;
dec: (delta?: number) => void;
set: (value: number | ((c: number) => number)) => void;
reset: () => void;
} = useNumber(initialValue?: number, { min, max });
`

参数

| 参数 | 说明 | 类型 | 默认值 |
| ------------ | -------------------- | ------ | ------ |
| initialValue | 可选项，默认的状态值 | number | 0 |
| min | 可选项，限制的最小值 | number | - |
| max | 可选项，限制的最大值 | number | - |

返回值

| 参数 | 说明 | 类型 |
| ----- | ------------ | -------------------------------------------------- |
| state | 当前状态值 | number |
| inc | 加，默认加 1 | (delta?: number) => void |
| dec | 减，默认减 1 | (delta?: number) => void |
| set | 设置值 | (value: number \| ((c: number) => number)) => void |
| reset | 重置为默认值 | () => void |

---

$3

用于感知页面可见性的 hook。

#### API

`ts
const [hidden, visibilityState] = usePageVisible(): [boolean, VisibilityState];
`

参数

无

返回值

| 参数 | 说明 | 类型 |
| --------------- | ---------------------- | ------------------------------------ |
| hidden | 表示页面显示或者隐藏 | boolean |
| visibilityState | 页面可见性状态的字符串 | "hidden" \| "visible" \| "prerender" \| "unloaded" |

---

$3

创建一个既 memoized 又保持最新引用的回调函数。

> 如何从 useCallback 读取一个经常变化的值？
> 在某些场景中，你可能会需要用 useCallback 记住一个回调，但由于内部函数必须经常重新创建，记忆效果不是很好，导致子组件重复 render。对于超级复杂的子组件，重新渲染会对性能造成影响。

#### API

`ts
function usePersistCallback any>(fn: T): T;
`

参数

| 参数 | 说明 | 类型 |
| ---- | -------- | ----------------------- |
| fn | 回调函数 | (...args: any[]) => any |

返回值

| 参数 | 说明 | 类型 |
| ---- | ---------------- | ----------------------- |
| fn | 处理后的回调函数 | (...args: any[]) => any |

---

$3

保存上一次渲染时状态值的 hook。

#### API

`ts
const previousState: T = usePrevious(state: T);
`

参数

| 参数 | 说明 | 类型 |
| ----- | ---------------- | ---- |
| state | 需要记录变化的值 | T |

返回值

| 参数 | 说明 | 类型 |
| ------------- | ------------------ | ---- |
| previousState | 上一次渲染时状态值 | T |

---

$3

核心特性

- 通过工厂函数生成状态，并可自动根据依赖重置或者手动重置

#### API

`ts
const [state, setState, reset] = useResetState(init: () => T, autoReset: boolean, deps: any[]);
`

参数

| 参数 | 说明 | 类型 | 默认值 |
| --------- | ------------------------------ | ------- | ------ |
| init | 生成状态的函数 | () => T | - |
| autoReset | 是否在 deps 变化时强行重置状态 | boolean | - |
| deps | 依赖 | any[] | - |

返回值

| 参数 | 说明 | 类型 |
| -------- | -------- | -------------- |
| state | 状态 | T |
| setState | dispatch | (s: T) => void |
| reset | 手动重置 | ()=>void |

---

$3

用于动态加载脚本或执行 JavaScript 的 hook，常在引入 JavaScript SDK 的场景。

#### API

`ts
const [loadedState, errorState] = useScript(src: string, properties?: ScriptProperties);
`

参数

| 参数 | 说明 | 类型 |
| ---------- | -------------------------------------------------------------------------------------------------- | ---------------- |
| src | 脚本文件地址 | string |
| properties | HTMLScriptElement 支持的属性 | ScriptProperties |

返回值

| 参数 | 说明 | 类型 |
| ----------- | -------------------- | ------------------ |
| loadedState | 脚本文件是否加载完毕 | Boolean |
| errorState | 脚本文件加载错误实例 | ErrorEvent \| null |

---

$3

用于监测滚动状态的 hook，提供一系列滚动相关信息。

#### API

`ts
const [ref, scrollData] = useScroll(
el?: T | (() => T),
options: Options = {},
deps: any[] = [],
): [React.MutableRefObject, ScrollDataType];
`

参数

| 参数 | 说明 | 类型 | 默认值 |
| ------- | ------------------------------------------------------------------------------ | ------------ | ------ |
| el | 监听的 DOM 元素，若使用 ref 可不传 | T \| () => T | - |
| options | 可选配置项 | Options | {} |
| deps | 依赖数组，如果数组变化，则会重新绑定事件，在元素为懒加载时使用，否则会处理失败 | any[] | [] |

返回值

| 参数 | 说明 | 类型 |
| ---------- | -------------------------- | --------------------------------------- |
| ref | 元素 ref，未传入 el 时使用 | React.MutableRefObject |
| scrollData | 滚动信息 | ScrollDataType |

$3

| 参数 | 说明 | 类型 |
| ------------- | ---------------- | ------------------------------ |
| onScroll | 滚动中回调函数 | (data: ScrollDataType) => void |
| onScrollStart | 滚动开始回调函数 | (data: ScrollDataType) => void |
| onScrollEnd | 滚动结束回调函数 | (data: ScrollDataType) => void |

$3

| 参数 | 说明 | 类型 |
| ---------------- | ------------------- | ----------------------------------- |
| scrolling | 是否正在滚动 | boolean |
| time | 滚动时长，单位 ms | number |
| direction | 滚动方向 | "up" \| "down" \| "right" \| "left" |
| offset | 偏移量 | { x: number, y: number } |
| speed | 滚动速度，单位 px/s | { x: number, y: number } |
| totalDistance | 总滚动距离 | { x: number, y: number } |
| relativeDistance | 本轮滚动距离 | { x: number, y: number } |

---

$3

用于锁定元素滚动条的 hook。

#### API

`ts
const {
isLock,
lock,
unlock,
toggle,
ref?,
} = useScrollLock(options?: Options): Result;
`

参数

| 参数 | 说明 | 类型 |
| ------- | ---------------------- | ------- |
| options | 可选配置项，见 Options | Options |

返回值

| 参数 | 说明 | 类型 |
| ------ | --------------------------------------- | --------------------------------------- |
| isLock | 是否锁定 | boolean |
| lock | 锁定 | () => void |
| unlock | 解锁 | () => void |
| toggle | 切换 | () => void |
| ref | 当未传入 el 参数时，用 ref 绑定元素节点 | React.MutableRefObject |

$3

| 参数 | 说明 | 类型 | 默认值 |
| --------- | ---------------------------------- | ------------ | ------ |
| el | 锁定的 DOM 元素，若使用 ref 可不传 | T \| () => T | - |
| default | 是否默认锁定 | boolean | false |
| direction | 锁定滚动方向，默认完全锁定 | 'x' \| 'y' | - |

---

$3

用于感知元素尺寸变化的 hook。

#### API

`ts
const [ref, size] = useSize(
el?: T | (() => T),
options?: Options,
deps: any[] = [],
): [React.MutableRefObject, Size];
`

参数

| 参数 | 说明 | 类型 |
| ------- | ------------------------------------------------------------------------------ | ------------ |
| el | 监听的 DOM 元素，若使用 ref 可不传 | T \| () => T |
| options | 可选配置项，见下方 | Options |
| deps | 依赖数组，如果数组变化，则会重新绑定事件，在元素为懒加载时使用，否则会处理失败 | any[] |

返回值

| 参数 | 说明 | 类型 |
| ---- | -------------------------- | --------------------------------------- |
| ref | 元素 ref，未传入 el 时使用 | React.MutableRefObject |
| size | 元素尺寸信息 | { width: number; height: number } |

$3

| 参数 | 说明 | 类型 |
| --------- | ---------------------------------------------- | ------------------- |
| throttle | 节流时间，默认 50ms | number |
| dimension | 限定检测的维度（高或宽），以减少不必要的重渲染 | 'width' \| 'height' |

---

$3

对 useState 进行增强，第三个返回值增加了一个 get 方法，可以在设置 setState 后立即在其他地方获取到这个值。

核心特性

- 获取 state 实时值

作用说明

- 比如在用户 setState 操作后立即发起请求时，如果读取 state 值，是未被修改的，显然不满足我们的需要。
- 在 react 的理念中 render 是纯的，state 只与渲染有关，可以有其它的副作用需要取到最新的 state，可以使用 useEffect+useRef 在每次视图更新后更新 state 最新值，如果你需要在 setState->视图更新触发 useEffect 这段时间也能取到最新值，那么你就可以使用 useStateRealtime

#### API

`ts
function useStateRealtime(
initialState: T | (() => T)
): [T, Dispatch>, () => T];
function useStateRealtime(): [
T | undefined,
Dispatch>,
() => T | undefined
];
const [state, setState, getRealState] = useStateRealtime(initialState);
`

参数

| 参数 | 说明 | 类型 |
| ------------ | ---------- | -------------- |
| initialState | 状态初始值 | T \| (() => T) |

返回值

| 参数 | 说明 | 类型 |
| ------------ | -------------------------------------- | ------------------------------------------ |
| state | 当前状态（同 useState 中） | T \| undefined |
| setState | 设置状态值（同 useState 中） | Dispatch\> |
| getRealState | 获取实时状态值（ view 更新后真正的值） | () => T \| undefined |

#### 备注：类型声明

- T 为范型
- type SetStateAction = S | ((prevState: S) => S);
- type Dispatch = (value: A) => void;

---

$3

用于同步和管理 localStorage / sessionStorage 的 hook。

#### API

`ts
const [state, setState] = useStorage(
key: string,
defaultValue?: T,
storage: Storage = localStorage,
raw: boolean = false,
): [T | undefined, (value?: T | (previousValue: T) => T)) => void];
`

参数

| 参数 | 说明 | 类型 | 默认值 |
| ------------ | ------------------------------------- | ------- | ------------ |
| key | 键名 | string | - |
| defaultValue | 默认值，服务端渲染或取值失败时使用 | T | - |
| storage | Web Storage 对象，默认为 localStorage | Storage | localStorage |
| raw | 是否自动进行 JSON 处理，默认不进行 | boolean | false |

返回值

| 参数 | 说明 | 类型 |
| -------- | ----------------------------------------------- | ----------------------------------------------- |
| state | 键名对应的 storage 的值或默认值 | T \| undefined |
| setState | 设置键名对应的 storage 的值，不传参数时表示删除 | (value?: T \| (previousValue: T) => T)) => void |

---

$3

用于同步滚动多个元素的 hook。

#### API

`ts
useSyncScroll(
refs: React.MutableRefObject[],
options = {
vertical: true,
horizontal: true,
},
);
`

参数

| 参数 | 说明 | 类型 |
| ------- | ------------------------------------------------- | ------------------------------------------ |
| refs | 要同步滚动元素 ref 数组 | React.MutableRefObject[] |
| options | 配置滚动类型，有垂直和水平两个方向，默认均为 true | { vertical: boolean, horizontal: boolean } |

---

$3

用来处理值节流 hook。

#### API

`ts
const ThrottledValue = useThrottle(
value: any,
wait: number
);
`

参数

| 参数 | 说明 | 类型 | 默认值 |
| ----- | ------------------------ | ------ | ------ |
| value | 需要节流变化的值 | any | - |
| wait | 防抖等待时间，单位为毫秒 | number | 1000 |

返回值

| 参数 | 说明 | 类型 |
| ----- | ---------- | ---- |
| value | 节流后的值 | any |

---

$3

用来处理函数防抖的 hook。

#### API

`ts
const {
run,
cancel
} = useDebounceFn(
fn: (...args: any[]) => any,
wait: number = 1000
deps: any[] = [],
options: Options = {
immediately: false,
trailing: true,
leading: false,
}
);
`

参数

| 参数 | 说明 | 类型 | 默认值 |
| ------- | ------------------------------------------------- | ----------------------- | ------ |
| fn | 需要防抖执行的函数 | (...args: any[]) => any | - |
| wait | 防抖等待时间，单位为毫秒 | number | 1000 |
| deps | 依赖数组，如果数组变化，则会在等待时间后，触发 fn | any[] | [] |
| options | 可选配置项，见 Options | {} |

返回值

| 参数 | 说明 | 类型 |
| ------ | ---------------------------------- | ----------------------- |
| run | 触发执行 fn，函数参数将会传递给 fn | (...args: any[]) => any |
| cancel | 取消当前防抖 | () => void |

$3

| 参数 | 说明 | 类型 | 默认值 |
| ----------- | ---------------------------------------- | ------- | ------ |
| immediately | 是否在第一次立即执行 | boolean | false |
| trailing | 是否在下降沿执行相关函数，即延迟后执行 | boolean | true |
| leading | 是否在上升沿执行相关函数，即在延迟前执行 | boolean | false |

---

$3

针对时间管理的一些方法，如倒计时和计时器

#### API

`ts
const returnValue= useTimer(
time: number | Date,
options: Options,
deps: DependencyList = [],
):ReturnValue;
`

参数

| 参数 | 说明 | 类型 | 默认值 |
| ------- | ----------------- | ------------- | ------ |
| 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 |

$3

| 参数 | 说明 | 类型 | 默认值 |
| ----------- | -------------------- | ---------- | -------- |
| onComplete | 倒计时结束后的回调 | () => void | () => {} |
| auto | 是否立即开始倒计时 | boolean | true |
| isCountDown | 是否强制为倒计时模式 | boolean | false |

---

$3

用于管理页面 title 的 hook，能满足多数使用场景。

#### API

`ts
useTitle(title: string | (() => string | Promise | void), options: Options, deps: any[] = []);
`

参数

| 参数 | 说明 | 类型 |
| ------- | --------------------------------------------------- | ---------------------------------------------------- |
| title | 要设置的字符串或能返回字符串的函数，支持异步 | string \| (() => string \| Promise \| void) |
| options | 用于配置兜底 title，固定的前缀和后缀，onChange 函数 | Options |
| deps | 依赖数组，如果 deps 变化，会重新设置 title | any[] |

$3

| 参数 | 说明 | 类型 |
| ------------ | ----------------------------------- | ----------------------------------------- |
| defaultTitle | 用于获取 title 失败或组件销毁时兜底 | string |
| prefix | 固定的前缀 | string |
| suffix | 固定的后缀 | string |
| onChange | title 变化时的回调函数 | (title: string, oldTitle: string) => void |

---

$3

用于在两个不同的值之间进行切换，与 useBoolean 不同的是它也支持字符串和数字等。常见的使用场景如：开启/关闭通知、切换模式等。

#### API

`ts
type State = any;

export interface ReturnValue {
state: T;
toggle: (value?: T) => void;
}

function useToggle(): ReturnValue;

function useToggle(defaultValue: T): ReturnValue;

function useToggle(
defaultValue: T,
reverseValue: U
): ReturnValue;
`

参数

| 参数 | 说明 | 类型 | 默认值 |
| -------------- | ------------------------- | ----------- | ---------------------------------------------------- |
| defaultValue | 可选项，默认的状态值 | D = boolean | false |
| reverseValue | 可选项，toggle 后的状态值 | R = any | !defaultValue（请注意对非布尔值做 ! 操作的行为） |

返回值

| 参数 | 说明 | 类型 |
| ------ | ---------------------------------------------------- | ------------------------ |
| state | 当前状态值 | D \| R |
| toggle | 触发状态更改的函数，接受一个可选参数显式地修改状态值 | (value?: D \| R) => void |

---

$3

组件卸载前执行回调的 hook。

#### API

`ts
useUnmount(fn: () => void): void
`

参数

| 参数 | 说明 | 类型 |
| ---- | -------------------- | ---------- |
| fn | 组件卸载前执行的回调 | () => void |

---

$3

一个只在依赖更新时执行的 useEffect hook。

#### API

`ts
useUpdateEffect(
effect: () => void,
deps?: deps,
)
`

参数

| 参数 | 说明 | 类型 |
| ------ | -------------------------- | ------------------ |
| effect | 可执行函数 | function |
| deps | 可选项，传入依赖变化的对象 | array \| undefined |

---

$3

这个 useURLState 是一个自定义的 React Hook，用于处理 URL 的查询参数。这个钩子返回一个对象，其中包含当前 URL 查询参数的当前状态，以及添加、删除和清除查询参数的函数。

#### 使用方法

首先，你需要导入 useURLState hook：

`javascript
import { useURLState } from "your/path/to/useURLState";
`

然后，在你的组件中使用它：

`javascript
const YourComponent = () => {
const { urlState, addQuery, removeQuery, removeAllQuery } = useURLState();

// now you can use the returned values and functions
};
`

#### API

useURLState 返回一个包含以下锁定的对象：

- urlState (URLState)：它是一个对象，包含当前 URL 查询参数的键值对。
- addQuery ((param: string, value: string) => void)：一个函数，用于添加查询参数。需要传入两个参数，参数名 param 和相应的值 value。
- removeQuery ((param: string) => void)：一个函数，用于删除特定查询参数。需要传入要删除的查询参数名 param。
- removeAllQuery (() => void)：一个函数，用于清除所有查询参数。

例如，你可通过以下方式查看当前 URL 状态：

`javascript
console.log(urlState); // { param1: 'value1', param2: 'value2' }
`

为 URL 添加查询参数:

`javascript
addQuery("newParam", "newValue"); // URL becomes: ?param1=value1¶m2=value2&newParam=newValue
`

移除 URL 查询参数:

`javascript
removeQuery("param1"); // URL becomes: ?param2=value2&newParam=newValue
`

移除全部的 URL 查询参数:

`javascript
removeAllQuery(); // URL becomes: ? (empty)
`

---

$3

提供虚拟化列表能力的 hook，用于解决展示海量数据渲染时首屏渲染缓慢和滚动卡顿问题。

#### API

`ts
const result:Result = useVirtualList(originalList: any[], Options);
`

参数

| 参数 | 说明 | 类型 |
| ------------ | ------------------------------------------------ | ---- |
| originalList | 包含大量数据的列表 | T[] |
| options | 配置项，见下方 Options，其中 itemHeight 为必传项 | - |

返回值

| 参数 | 说明 | 类型 |
| ------------- | ------------------------- | -------------------------- |
| list | 当前需要展示的列表内容 | {data: T, index: number}[] |
| scrollerProps | 滚动容器的 props | { ref, onScroll, style } |
| wrapperProps | children 外层包裹器 props | { style } |
| scrollTo | 快速滚动到指定 index | (index: number) => void |

$3

| 参数 | 说明 | 类型 | 默认值 |
| ---------- | ---------------------------------------------------- | ---------------------------------------------- | ------ |
| itemHeight | 每行高度，静态高度可直接传像素值，动态高度可传入函数 | number \| ((data: T, index: number) => number) | - |
| overscan | 视区上、下额外展示的 dom 节点数量 | number | 10 |
| onScroll | 滚动容器的滚动事件 | (e: UIEvent) => void | - |

---

$3

可对您选择的 HTML 元素添加水印，具备丰富的用户自定义功能。利用 Canvas API 和 Mutation Observers 来写入不可变的水印。

#### API

`ts
const { ref, updateConfig, loading } = useWatermark(config: WatermarkProps);
`

$3

| 参数 | 说明 | 类型 |
| ------- | -------------------------------------------------------------- | -------------- |
| config | 可选配置项，用于配置水印以满足您的需求 | WatermarkProps |

$3

| 参数 | 说明 | 类型 | 默认值 |
| ----------------- | ----------------------------------------------------------- | ------------------------------------ | ------------- |
| content | 水印文本内容 | string | - |
| width? | 水印框的宽度 | number | 100 |
| height? | 水印框的高度 | number | 100 |
| xOffset? | X轴偏移量 | number | 0 |
| yOffset? | Y轴偏移量 | number | 0 |
| rows? | 行数，仅适用于图片水印 | number | 0 |
| column? | 列数，仅适用于图片水印 | number | 0 |
| textAlign? | 水印框中文本的对齐方式 | CanvasTextAlign | center |
| verticalAlign? | 水印框中文本的垂直对齐方式 | CanvasTextBaseline | middle |
| fontSize? | 水印文本的字体大小 | CSSProperties['fontSize'] | 16px |
| fontFamily? | 水印文本的字体家族 | CSSProperties['fontFamily'] | Microsoft Yahei |
| color? | 水印文本的颜色 | CSSProperties['color'] | rgba(255, 0, 0, 0.9) |
| backgroundRepeat? | 是否在特定方向上重复水印 | 'repeat' \| 'repeat-x' \| 'repeat-y' | repeat |
| rotate? | 文本的旋转角度 | number | 20 |
| zIndex? | 水印元素的z-index值 | number | 1000000 |

$3

| 参数 | 说明 | 类型 |
| ------------ | ------------------------------------------------------------------------------------------------ | ---------------------------------- |
| ref | 要放置在被水印的HTML元素上的ref引用 | RefObject\ |
| updateConfig | 用于更新现有水印配置值的函数 | Partial\ => void; |
| loading | 指示hook当前是否正在更新图片，仅适用于图片水印 | boolean |

`

``