Sweet Hooks 文档

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

📚 目录

🎨 UI 相关 Hooks

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

⚡ 状态管理 Hooks

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

🔄 副作用 Hooks

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

⏱️ 时间相关 Hooks

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

📋 数据操作 Hooks

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

🎯 事件处理 Hooks

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

🌐 浏览器相关 Hooks

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

📊 工具类 Hooks

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

🎨 UI 相关 Hooks

usStyle

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

API

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

参数

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

返回值

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

useAsyncEffect

在 useEffect 中使用异步函数

核心特性

• 支持异步 effect 函数

API

useAsyncEffect(
  asyncEffectCallback: () => Promise<void | (() => void)>,
  deps?: DependencyList,
);

参数

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

⚡ 状态管理 Hooks

useBoolean

管理 boolean 类型状态的 hook。

API

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 |

useClickOutside

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

API

const ref = useClickOutside<T extends HTMLElement = any>(
  dom: RefType = undefined,
  onClickAway: (event: KeyboardEvent) => void,
): MutableRefObject<T>;

参数

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

返回值

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

useClipboardCopy

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

核心特性

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

API

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

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

const result: Result<T> = useClipboardCopy<T extends HTMLElement = any>(options: Options = {});

参数

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

返回值

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

useCookie

用于同步和管理 cookie 的 hook。

API

const [state, setState] = useCookie<T>(
  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

useDebounce

用来处理值防抖的 hook。

API

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

参数

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

返回值

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

useDebounceFn

用来处理函数防抖的 hook。

API

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 |

Options

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

###useDeepEffect

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

API

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

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

参数

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

返回值

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

useDeepMemo

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

API

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

参数

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

返回值

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

useDeepUpdateEffect

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

API

参数

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

返回值

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

useEventBus

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

API

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 |

useEventListener

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

API

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<HTMLElement> |

Options

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

useExposureTrack

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

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

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

何时使用

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

API

useExposureTrack<T extends ExposureData = ExposureData>(
  onExposure: ExposureCallback<T>,
  options?: ExposureOptions
)

参数

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

ExposureOptions

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

如何使用

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

<div data-exposure={JSON.stringify({ id: 1, name: '商品1' })}>
  商品1
</div>

useFavicon

用于设置页面的 favicon 图标。

API

useFavicon(url: string)

参数

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

useFilter

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

何时使用

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

API

const { filteredData, setMatcher, setData } = useFilter<T>(options: FilterOptions<T>);

FilterOptions

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

返回值

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

useForceUpdate

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

API

const forceUpdate = useForceUpdate();

返回值

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

useFullscreen

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

API

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

参数

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

Options

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

返回值

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

useHistory

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

核心特性

• 撤销
• 重做
• 状态管理

API

const result: ReturnValue<T> = useHistory<T>(
  initialPresent:  T
);

参数

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

返回值

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

useHover

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

API

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

参数

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

返回值

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

Options

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

useInView

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

API

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

参数

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

返回值

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

useInterval

用于方便控制 setInterval 的 hook。

API

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 |

useKeepPage

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

API

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

参数

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

返回值

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

useKeyPress

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

API

const ref = useKeyPress<T extends HTMLElement = HTMLInputElement>(
  keyFilter: KeyFilter,
  eventHandler: EventHandler = noop,
  option: EventOption = {},
): RefObject<T>

参数

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

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

返回值

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

Options

| 参数 | 说明 | 类型 | 默认值 | | ------ | ---------------------------------------------------------------------------------------- | --------------------------------------------------------- | ----------- | | events | 触发事件 | Array<keydown | keyup> | ['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

useLockFn

避免重复提交请求

核心特性

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

API

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

参数

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

返回值

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

useMedia

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

API

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

参数

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

返回值

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

MediaQueryObject

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

useMounted

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

API

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

参数

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

useMouse

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

API

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

参数

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

返回值

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

useNumber

管理 number 类型状态的 hook。

API

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 |

usePageVisible

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

API

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

参数

无

返回值

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

usePersistCallback

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

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

API

function usePersistCallback<T extends (...args: any[]) => any>(fn: T): T;

参数

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

返回值

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

usePrevious

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

API

const previousState: T = usePrevious<T>(state: T);

参数

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

返回值

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

useResetState

核心特性

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

API

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

参数

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

返回值

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

useScript

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

API

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

参数

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

返回值

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

useScroll

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

API

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

参数

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

返回值

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

Options

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

ScrollDataType

| 参数 | 说明 | 类型 | | ---------------- | ------------------- | ----------------------------------- | | 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 } |

useScrollLock

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

API

const {
   isLock,
   lock,
   unlock,
   toggle,
   ref?,
} = useScrollLock<T extends HTMLElement>(options?: Options<T>): Result<T>;

参数

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

返回值

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

Options

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

useSize

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

API

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

参数

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

返回值

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

Options

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

useStateRealtime

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

核心特性

• 获取 state 实时值

作用说明

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

API

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

参数

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

返回值

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

备注：类型声明

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

useStorage

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

API

const [state, setState] = useStorage<T>(
  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 |

useSyncScroll

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

API

useSyncScroll<T extends HTMLElement>(
  refs: React.MutableRefObject<T>[],
  options = {
    vertical: true,
    horizontal: true,
  },
);

参数

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

useThrottle

用来处理值节流 hook。

API

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

参数

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

返回值

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

useDebounceFn

用来处理函数防抖的 hook。

API

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 |

Options

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

useTimer

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

API

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 |

useTitle

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

API

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

参数

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

Options

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

useToggle

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

API

type State = any;

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

function useToggle<T = boolean>(): ReturnValue<T>;

function useToggle<T = State>(defaultValue: T): ReturnValue<T>;

function useToggle<T = State, U = State>(
  defaultValue: T,
  reverseValue: U
): ReturnValue<T | U>;

参数

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

返回值

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

useUnmount

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

API

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

参数

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

useUpdateEffect

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

API

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

参数

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

useURLState Hook

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

使用方法

首先，你需要导入 useURLState hook：

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

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

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 状态：

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

为 URL 添加查询参数:

addQuery("newParam", "newValue"); // URL becomes: ?param1=value1&param2=value2&newParam=newValue

移除 URL 查询参数:

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

移除全部的 URL 查询参数:

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

useVirtualList

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

API

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 |

Options

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

useWatermark

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

API

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

参数

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

WatermarkProps

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

返回值

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