> 一个功能丰富的 React Hooks 集合,提供各种实用的自定义 Hooks
npm install sweet-hooks> 一个功能丰富的 React Hooks 集合,提供各种实用的自定义 Hooks
- usStyle - 动态加载和执行 CSS
- useClickOutside - 管理元素外点击事件
- useFullscreen - 全屏控制
- useHover - 鼠标悬停状态
- useInView - 元素可见性检测
- useSize - 元素尺寸监听
- useVirtualList - 虚拟列表
- useWatermark - 水印功能
- useBoolean - 布尔状态管理
- useNumber - 数字状态管理
- useToggle - 切换状态管理
- useResetState - 可重置状态
- useStateRealtime - 实时状态
- useUrlState - URL 状态同步
- useAsyncEffect - 异步副作用
- useDeepEffect - 深度比较副作用
- useDeepUpdateEffect - 深度比较更新副作用
- useUpdateEffect - 更新副作用
- useUnmount - 卸载副作用
- useMounted - 挂载状态
- useDebounce - 值防抖
- useDebounceFn - 函数防抖
- useThrottle - 值节流
- useThrottleFn - 函数节流
- useInterval - 间隔执行
- useTimer - 定时器管理
- useFilter - 数据过滤
- useHistory - 历史记录
- usePersistCallback - 持久化回调
- usePrevious - 前一个值
- useStorage - 本地存储
- useEventListener - 事件监听
- useEventBus - 事件总线
- useKeyPress - 键盘事件
- useLockFn - 函数锁
- useClipboardCopy - 剪贴板操作
- useCookie - Cookie 管理
- useFavicon - 网站图标
- useMedia - 媒体查询
- useNetwork - 网络状态
- usePageVisible - 页面可见性
- useScript - 脚本加载
- useTitle - 页面标题
- useCatchError - 错误捕获
- useDeepMemo - 深度记忆
- useExposureTrack - 曝光追踪
- useForceUpdate - 强制更新
- useKeepPage - 页面保持
- useMouse - 鼠标位置
- useScroll - 滚动状态
- useScrollLock - 滚动锁定
- useSyncScroll - 同步滚动
---
用于动态加载 CSS 或执行 CSS 的 hook。
#### API
``ts`
const [loadedState, errorState] = usStyle(href: string, properties?: StyleProperties);
参数
| 参数 | 说明 | 类型 |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------- |
| href | 样式文件地址 | string |
| properties | HTMLLinkElement 支持的属性或HTMLStyleElement 支持的属性 | StyleProperties |
返回值
| 参数 | 说明 | 类型 |
| ----------- | -------------------- | ------------------ |
| loadedState | 样式文件是否加载完毕 | Boolean |
| errorState | 样式文件加载错误实例 | ErrorEvent \| null |
---
在 useEffect 中使用异步函数
核心特性
- 支持异步 effect 函数
#### API
`ts`
useAsyncEffect(
asyncEffectCallback: () => Promise
deps?: DependencyList,
);
参数
| 参数 | 说明 | 类型 | 默认值 |
| ------------------- | ---------------- | ----------------------------------- | ------ |
| asyncEffectCallback | 异步 effect 函数 | () => Promise
| deps | 依赖数组 | DependencyList \| undefined | - |
---
管理 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 |
---
优雅的管理目标元素外点击事件的 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
---
用于方便处理剪切板复制场景的 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
`
参数
| 参数 | 说明 | 类型 |
| --------- | ------------ | ---------------------- |
| onSuccess | 复制成功回调 | (text: string) => void |
| onError | 复制失败回调 | (error: any) => void |
返回值
| 参数 | 说明 | 类型 |
| ----------- | ------------------------------------------------------------------------------ | --------------------------------------- |
| ref | 要复制内容所在元素,会尝试读取 value 属性或 innerText 属性 | React.MutableRefObject\navigator.clipboard
| isSupported | 是否支持剪切板相关 API,会检查 和 document.execCommand | boolean |
| isCopied | 是否已经复制过 | boolean |
| copyText | 上一次被复制的文字 | string |
| copy | 复制,可手动传值,也可通过绑定元素取值 | (text?: string) => void |
| cut | 剪切,会先清空绑定元素的值再复制 | () => void |
| clear | 清空剪切板 | () => void |
---
用于同步和管理 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
---
用来处理值防抖的 hook。
#### API
`ts`
const debouncedValue = useDebounce(
value: any,
wait: number
);
参数
| 参数 | 说明 | 类型 | 默认值 |
| ----- | ------------------------ | ------ | ------ |
| value | 需要防抖的值 | any | - |
| wait | 防抖等待时间,单位为毫秒 | number | 1000 |
返回值
| 参数 | 说明 | 类型 |
| ----- | ---------- | ---- |
| value | 防抖后的值 | any |
---
用来处理函数防抖的 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 |
| 参数 | 说明 | 类型 | 默认值 |
| ----------- | ---------------------------------------- | ------- | ------ |
| immediately | 是否在第一次立即执行 | boolean | false |
| trailing | 是否在下降沿执行相关函数,即延迟后执行 | boolean | true |
| leading | 是否在上升沿执行相关函数,即在延迟前执行 | boolean | false |
---
###useDeepEffect
当依赖参数在深比较后与上一次内容相同时,返回上一次的内容,避免重复的副作用执行。可以传入自定义的比较函数,根据比较的结果控制是否执行副作用。
#### API
`ts
useDeepEffect
useDeepEffect
callback: React.EffectCallback,
isEqual: (prev:T[],cur: T[]) => boolean,
deps: T[]
): void;
`
参数
| 参数 | 说明 | 类型 | 默认值 |
| -------- | -------------------------------------------------------- | -------------------------------------------------------------- | -------------- |
| callback | 需要执行的副作用 | Function | - |
| deps | 执行副作用监听的依赖数组 | Array | - |
| isEqual | 自定义用于比较参数前后状态,根据返回值控制是否执行副作用 | 可选参数;函数类型,第一个参数为上一状态值,第二个参数为当前值 | lodash.isEqual |
返回值
| 参数 | 说明 | 类型 |
| ---- | ---------------------------------------------------------- | ---- |
| - | 通过深比较或自定义比较后,只在比较结果为 true 时执行副作用 | - |
---
当参数在深比较后与上一次内容相同时,返回上一次的内容,避免重复的副作用执行。可以传入自定义的比较函数,根据比较的结果控制是否返回新内容。
#### API
`ts
const memoizedValue: T = useDeepMemo
`
参数
| 参数 | 说明 | 类型 | 默认值 |
| ------- | -------------------------------------------------------- | -------------------------------------------------------------- | -------------- |
| value | 传入参数 | 通常传入 object 等引用类型 | - |
| isEqual | 自定义用于比较参数前后状态,根据返回值控制是否返回的内容 | 可选参数;函数类型,第一个参数为上一状态值,第二个参数为当前值 | lodash.isEqual |
返回值
| 参数 | 说明 | 类型 |
| ------------- | ------------------------------------------------------------------------------ | ------------------ |
| memoizedValue | 通过深比较或自定义比较后,若比较结果为 false,则返回新内容,反之返回之前的内容 | 与传入参数同一类型 |
---
useDeepUpdateEffect 是一个自定义的 React Hook,它在组件更新时执行副作用,但首次渲染时不执行。只有当依赖数组中的值在深度比较后发生变化时,才会触发该副作用。
#### API
参数
| 参数 | 说明 | 类型 | 默认值 |
| ------ | ---------------- | ---------------------- | ------ |
| effect | 需要执行的副作用 | React.EffectCallback | - |T[]
| deps | 副作用的依赖数组 | | - |
返回值
| 参数 | 说明 | 类型 |
| ---- | ---------------------------------------- | ---- |
| - | 只在深度比较依赖数组发生变化时执行副作用 | - |
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 |
用于添加/移除监听事件的 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
| 参数 | 说明 | 类型 | 默认值 |
| ------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- | ---------- |
| target | 监听对象,若不填写,将监听应用 ref 的对象 | HTMLElement \| null \| window | undefined |
| capture | 设置为 true 表示 eventListener 会在该类型的事件捕获阶段传播到该 target 时触发。 | boolean | false |
| once | 设置为 true 表示 eventListener 在事件触发后只执行一次 | boolean | false |
| passive | 同原生 passive 参数,具体可见:让页面滑动流畅得飞起的新特性:Passive Event Listeners。 | boolean | false |
一个用于追踪元素曝光的 hook。
性能优化说明:该 hook 内部的所有回调函数都已使用 useCallback 进行包裹。
重要提示:传入的回调函数必须使用 useCallback 包裹,以免产生不可预期的行为。
当你需要对页面中的某些元素进行曝光统计时,可以使用此 hook。例如,广告的曝光、商品的曝光等。
#### API
`ts`
useExposureTrack
onExposure: ExposureCallback
options?: ExposureOptions
)
参数
| 参数 | 说明 | 类型 | 默认值 |
| ---------- | ---------------------- | ----------------------------------------- | ------ |
| onExposure | 曝光回调函数 | (data: T, element: HTMLElement) => void | - |ExposureOptions
| options | 可选配置项,见 Options | | {} |
| 参数 | 说明 | 类型 | 默认值 |
| ---------- | ------------------ | ----------------------- | ------- |
| delay | 曝光延迟时间(ms) | number | 100 |number
| threshold | 曝光阈值,0-1 之间 | | 0.1 |root
| rootMargin | 的外边距 | string | '0px' |HTMLElement
| root | 监听的根元素 | \| null | null |
在需要曝光的元素上添加 data-exposure 属性,值为一个 JSON 字符串。
`html`
商品1
---
用于设置页面的 favicon 图标。
#### API
`ts`
useFavicon(url: string)
参数
| 参数 | 说明 | 类型 |
| ---- | ---------------------------------------------------------- | ------ |
| url | favicon 图标的 url,支持 gif、ico、jpeg、png 和 svg 的后缀 | string |
---
一个用于在客户端进行模糊过滤的 hook。
当你需要一个在客户端根据输入动态过滤列表的功能时,可以使用此 hook。
#### API
`ts`
const { filteredData, setMatcher, setData } = useFilter
| 参数 | 说明 | 类型 | 默认值 |
| ------------- | -------------------- | ------------ | ------- |
| data | 要过滤的原始数据数组 | T[] | [] |Partial
| matcher | 用于匹配的键值对对象 | | {} |boolean
| caseSensitive | 是否区分大小写 | | false |
返回值
| 参数 | 说明 | 类型 |
| ------------ | ---------------- | ------------------------------- |
| filteredData | 过滤后的数据数组 | T[] |(matcher: Partial
| setMatcher | 用于更新匹配条件 | |(data: T[]) => void
| setData | 用于更新原始数据 | |
---
用于强制更新组件的 hook,通常在 useRef 管理可变状态,但又需要重渲染时使用。
#### API
`ts`
const forceUpdate = useForceUpdate();
返回值
| 参数 | 说明 | 类型 |
| ----------- | -------------------------------------------------------- | ---------- |
| forceUpdate | 用于调用强制更新的函数,同一个函数多次调用也只会更新一次 | () => void |
---
用于控制 DOM 元素全屏状态的 hook。
#### API
`ts`
const {
isFullscreen,
setFull,
exitFull,
ref?,
} = useFullScreen(
el?: T | (() => T),
options?: Options,
);
参数
| 参数 | 说明 | 类型 |
| ------- | ---------------------------------------------------------------- | ----------------------------------------------- |
| el | 可选项,如果未传入则会监听返回结果中的 ref,否则会监听传入的节点 | HTMLElement \| (() => HTMLElement) \| undefined |
| 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
---
管理状态变化历史,方便添加撤销 / 重做功能
核心特性
- 撤销
- 重做
- 状态管理
#### API
`ts`
const result: ReturnValue
initialPresent: T
);
参数
| 参数 | 说明 | 类型 |
| -------------- | ------------ | ---- |
| initialPresent | 初始化 value | T |
返回值
| 参数 | 说明 | 类型 |
| ------- | ------------ | ----------------------- |
| state | 状态 Map | T |
| set | 存储状态 | (newPresent: T) => void |
| undo | 撤销 | () => void |
| redo | 重做 | () => void |
| clear | 清空状态池 | () => void |
| canUndo | 是否可以撤销 | boolean |
| canRedo | 是否可以重做 | boolean |
---
用于感知元素是否处于 hover 状态的 hook。
#### API
`ts`
const [ref, isHovered] = useHover
el?: T | (() => T),
options?: Options,
deps: any[] = [],
): [React.MutableRefObject
参数
| 参数 | 说明 | 类型 |
| ------- | ------------------------------------------------------------------------------ | ------------ |
| el | 监听的 DOM 元素,若使用 ref 可不传 | T \| () => T |
| options | 可选配置项,见 Options | Options |
| deps | 依赖数组,如果数组变化,则会重新绑定事件,在元素为懒加载时使用,否则会处理失败 | any[] |
返回值
| 参数 | 说明 | 类型 |
| --------- | -------------- | --------------------------------------- |
| ref | 元素 ref | React.MutableRefObject
| isHovered | 元素是否 Hover | boolean |
| 参数 | 说明 | 类型 |
| ------- | -------------------- | ---------- |
| onEnter | 鼠标移入时触发的回调 | () => void |
| onLeave | 鼠标移出时触发的回调 | () => void |
---
用于感知元素是否处于可视范围的 hook,可用于懒加载、埋点等场景。
#### API
`ts`
const [ref, inView] = useInView
el?: T | (() => T),
options?: IntersectionObserverInit,
deps: any[] = [],
cb?: () => void,
): [React.MutableRefObject
参数
| 参数 | 说明 | 类型 |
| ------- | ------------------------------------------------------------------------------ | ------------------------ |
| el | 监听的 DOM 元素,若使用 ref 可不传 | T \| () => T |
| options | IntersectionObserver 监听配置 | IntersectionObserverInit |
| deps | 依赖数组,如果数组变化,则会重新绑定事件,在元素为懒加载时使用,否则会处理失败 | any[] |
| cb | 可选的回调,在处于可视范围的时候,会发回调 | () => void |
返回值
| 参数 | 说明 | 类型 |
| ------ | -------------------------- | --------------------------------------- |
| ref | 元素 ref,未传入 el 时使用 | React.MutableRefObject
| inView | 元素是否处于可视范围 | boolean |
---
用于方便控制 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 |
---
在关闭或刷新页面时给出提示,尤其适用于填写表单的页面。
#### API
`ts`
const [shouldKeepPage, setShouldKeepPage] = useKeepPage(
initShouldKeepPage: boolean,
onLeave?: Function,
): [boolean, React.Dispatch
参数
| 参数 | 说明 | 类型 |
| --------------------- | ---------------------------------------------------------------------------- | -------- |
| initialShouldKeepPage | 是否应在关闭或刷新页面前提示 | boolean |
| onLeave | 可选参数,在 beforeunload 事件发生且 shouldKeepPage 为 true 时执行的回调函数 | Function |
返回值
| 参数 | 说明 | 类型 |
| ----------------- | ------------------------------------------ | -------- |
| shouldKeepPage | 是否应在关闭或刷新页面前提示 | boolean |
| setShouldKeepPage | 设置是否应在关闭或刷新页面前提示的回调函数 | Function |
---
用于方便管理键盘事件的 hook,设置组合键,绑定快捷键。
#### API
`ts`
const ref = useKeyPress
keyFilter: KeyFilter,
eventHandler: EventHandler = noop,
option: EventOption = {},
): RefObject
参数
> Tips: keyType 为键盘事件中的 key 和 keyCode
| 参数 | 说明 | 类型 |
| ------------ | ---------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| keyFilter | 支持键盘事件中的 key 和 keyCode,支持回调方式返回 boolean 判断,支持别名使用 | keyType \| Array
| eventHandler | 事件回调函数 | (event: KeyboardEvent) => void |
| options | 可选配置项,见 Options | Options |
返回值
| 参数 | 说明 | 类型 |
| ---- | ------------------------------------------------- | ------------- |
| ref | 当未传入任何 target 时,将 ref 绑定给需监听的节点 | RefObject
| 参数 | 说明 | 类型 | 默认值 |
| ------ | ---------------------------------------------------------------------------------------- | --------------------------------------------------------- | ----------- |
| events | 触发事件 | Array
| 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
---
避免重复提交请求
核心特性
在提交函数请求执行完成之前,会忽略再次点击请求操作
#### API
`ts`
const { fn } = useLockFn(
fn: (...args: any[]) => any
);
参数
| 参数 | 说明 | 类型 | 默认值 |
| ---- | -------------------- | ---------------------- | ------ |
| fn | 需要增加竞态锁的函数 | (...args: any[])=> any | - |
返回值
| 参数 | 说明 | 类型 |
| ---- | ------------------ | ---------------------- |
| fn | 增加了竞态锁的函数 | (...args: any[])=> any |
---
用于获取媒体查询结果的 hook,可用于响应式布局。
#### API
`ts`
const state: boolean = useMedia(query: string | MediaQueryObject, defaultState: boolean | (() => boolean));
参数
| 参数 | 说明 | 类型 | 默认值 |
| ------------ | ---------------------------------------- | -------------------------- | ------ |
| query | 媒体查询规则,以字符串形式或对象形式传入 | string \| MediaQueryObject | - |
| defaultState | 默认状态,只在服务端渲染时使用 | boolean | false |
返回值
| 参数 | 说明 | 类型 | 默认值 |
| ----- | -------------------- | ------- | ------ |
| state | 是否匹配媒体查询规则 | boolean | false |
| 参数 | 说明 | 类型 |
| ------ | ------------------------------------------------------------------------------------------------------------ | ---------------- |
| [rule] | CSS @media 规则的特性, 驼峰式写法,如 minWidth, maxDeviceAspectRatio, orientation 等,传入多个值时为“且”关系 | string \| number |
---
组件加载完成后执行回调的 hook。
#### API
`ts`
useMounted(fn: () => void): void
参数
| 参数 | 说明 | 类型 |
| ---- | -------------------- | ---------- |
| fn | 加载完成后执行的函数 | () => void |
---
追踪鼠标在元素内坐标位置的 hook。
#### API
`ts`
const [ref, state] = useMouse
el?: Window | T | (() => T),
options?: Options,
deps: any[] = [],
): [React.MutableRefObject
参数
| 参数 | 说明 | 类型 | 默认值 |
| ------- | ------------------------------------------------------------------------------ | ---------------------- | ------ |
| el | 鼠标坐标参照元素,若使用 ref 可不传 | T \| () => T | - |
| options | 可选配置项,如节流时间 | { throttle?: number; } | {} |
| deps | 依赖数组,如果数组变化,则会重新绑定事件,在元素为懒加载时使用,否则会处理失败 | any[] | [] |
返回值
| 参数 | 说明 | 类型 |
| ----- | -------------------------- | --------------------------------------- |
| ref | 元素 ref,未传入 el 时使用 | React.MutableRefObject
| state | 鼠标坐标位置信息 | { x: number; y: number } |
---
管理 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 |
---
用于感知页面可见性的 hook。
#### API
`ts`
const [hidden, visibilityState] = usePageVisible(): [boolean, VisibilityState];
参数
无
返回值
| 参数 | 说明 | 类型 |
| --------------- | ---------------------- | ------------------------------------ |
| hidden | 表示页面显示或者隐藏 | boolean |
| visibilityState | 页面可见性状态的字符串 | "hidden" \| "visible" \| "prerender" \| "unloaded" |
---
创建一个既 memoized 又保持最新引用的回调函数。
> 如何从 useCallback 读取一个经常变化的值?
> 在某些场景中,你可能会需要用 useCallback 记住一个回调,但由于内部函数必须经常重新创建,记忆效果不是很好,导致子组件重复 render。对于超级复杂的子组件,重新渲染会对性能造成影响。
#### API
`ts`
function usePersistCallback
参数
| 参数 | 说明 | 类型 |
| ---- | -------- | ----------------------- |
| fn | 回调函数 | (...args: any[]) => any |
返回值
| 参数 | 说明 | 类型 |
| ---- | ---------------- | ----------------------- |
| fn | 处理后的回调函数 | (...args: any[]) => any |
---
保存上一次渲染时状态值的 hook。
#### API
`ts`
const previousState: T = usePrevious
参数
| 参数 | 说明 | 类型 |
| ----- | ---------------- | ---- |
| state | 需要记录变化的值 | T |
返回值
| 参数 | 说明 | 类型 |
| ------------- | ------------------ | ---- |
| previousState | 上一次渲染时状态值 | T |
---
核心特性
- 通过工厂函数生成状态,并可自动根据依赖重置或者手动重置
#### API
`ts`
const [state, setState, reset] = useResetState
参数
| 参数 | 说明 | 类型 | 默认值 |
| --------- | ------------------------------ | ------- | ------ |
| init | 生成状态的函数 | () => T | - |
| autoReset | 是否在 deps 变化时强行重置状态 | boolean | - |
| deps | 依赖 | any[] | - |
返回值
| 参数 | 说明 | 类型 |
| -------- | -------- | -------------- |
| state | 状态 | T |
| setState | dispatch | (s: T) => void |
| reset | 手动重置 | ()=>void |
---
用于动态加载脚本或执行 JavaScript 的 hook,常在引入 JavaScript SDK 的场景。
#### API
`ts`
const [loadedState, errorState] = useScript(src: string, properties?: ScriptProperties);
参数
| 参数 | 说明 | 类型 |
| ---------- | -------------------------------------------------------------------------------------------------- | ---------------- |
| src | 脚本文件地址 | string |
| properties | HTMLScriptElement 支持的属性 | ScriptProperties |
返回值
| 参数 | 说明 | 类型 |
| ----------- | -------------------- | ------------------ |
| loadedState | 脚本文件是否加载完毕 | Boolean |
| errorState | 脚本文件加载错误实例 | ErrorEvent \| null |
---
用于监测滚动状态的 hook,提供一系列滚动相关信息。
#### API
`ts`
const [ref, scrollData] = useScroll
el?: T | (() => T),
options: Options = {},
deps: any[] = [],
): [React.MutableRefObject
参数
| 参数 | 说明 | 类型 | 默认值 |
| ------- | ------------------------------------------------------------------------------ | ------------ | ------ |
| el | 监听的 DOM 元素,若使用 ref 可不传 | T \| () => T | - |
| options | 可选配置项 | Options | {} |
| deps | 依赖数组,如果数组变化,则会重新绑定事件,在元素为懒加载时使用,否则会处理失败 | any[] | [] |
返回值
| 参数 | 说明 | 类型 |
| ---------- | -------------------------- | --------------------------------------- |
| ref | 元素 ref,未传入 el 时使用 | React.MutableRefObject
| scrollData | 滚动信息 | ScrollDataType |
| 参数 | 说明 | 类型 |
| ------------- | ---------------- | ------------------------------ |
| onScroll | 滚动中回调函数 | (data: ScrollDataType) => void |
| onScrollStart | 滚动开始回调函数 | (data: ScrollDataType) => void |
| onScrollEnd | 滚动结束回调函数 | (data: ScrollDataType) => void |
| 参数 | 说明 | 类型 |
| ---------------- | ------------------- | ----------------------------------- |
| 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 } |
---
用于锁定元素滚动条的 hook。
#### API
`ts`
const {
isLock,
lock,
unlock,
toggle,
ref?,
} = useScrollLock
参数
| 参数 | 说明 | 类型 |
| ------- | ---------------------- | ------- |
| options | 可选配置项,见 Options | Options |
返回值
| 参数 | 说明 | 类型 |
| ------ | --------------------------------------- | --------------------------------------- |
| isLock | 是否锁定 | boolean |
| lock | 锁定 | () => void |
| unlock | 解锁 | () => void |
| toggle | 切换 | () => void |
| ref | 当未传入 el 参数时,用 ref 绑定元素节点 | React.MutableRefObject
| 参数 | 说明 | 类型 | 默认值 |
| --------- | ---------------------------------- | ------------ | ------ |
| el | 锁定的 DOM 元素,若使用 ref 可不传 | T \| () => T | - |
| default | 是否默认锁定 | boolean | false |
| direction | 锁定滚动方向,默认完全锁定 | 'x' \| 'y' | - |
---
用于感知元素尺寸变化的 hook。
#### API
`ts`
const [ref, size] = useSize
el?: T | (() => T),
options?: Options,
deps: any[] = [],
): [React.MutableRefObject
参数
| 参数 | 说明 | 类型 |
| ------- | ------------------------------------------------------------------------------ | ------------ |
| el | 监听的 DOM 元素,若使用 ref 可不传 | T \| () => T |
| options | 可选配置项,见下方 | Options |
| deps | 依赖数组,如果数组变化,则会重新绑定事件,在元素为懒加载时使用,否则会处理失败 | any[] |
返回值
| 参数 | 说明 | 类型 |
| ---- | -------------------------- | --------------------------------------- |
| ref | 元素 ref,未传入 el 时使用 | React.MutableRefObject
| size | 元素尺寸信息 | { width: number; height: number } |
| 参数 | 说明 | 类型 |
| --------- | ---------------------------------------------- | ------------------- |
| throttle | 节流时间,默认 50ms | number |
| dimension | 限定检测的维度(高或宽),以减少不必要的重渲染 | 'width' \| 'height' |
---
对 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
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;
---
用于同步和管理 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 |
---
用于同步滚动多个元素的 hook。
#### API
`ts`
useSyncScroll
refs: React.MutableRefObject
options = {
vertical: true,
horizontal: true,
},
);
参数
| 参数 | 说明 | 类型 |
| ------- | ------------------------------------------------- | ------------------------------------------ |
| refs | 要同步滚动元素 ref 数组 | React.MutableRefObject
| options | 配置滚动类型,有垂直和水平两个方向,默认均为 true | { vertical: boolean, horizontal: boolean } |
---
用来处理值节流 hook。
#### API
`ts`
const ThrottledValue = useThrottle(
value: any,
wait: number
);
参数
| 参数 | 说明 | 类型 | 默认值 |
| ----- | ------------------------ | ------ | ------ |
| value | 需要节流变化的值 | any | - |
| wait | 防抖等待时间,单位为毫秒 | number | 1000 |
返回值
| 参数 | 说明 | 类型 |
| ----- | ---------- | ---- |
| value | 节流后的值 | any |
---
用来处理函数防抖的 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 |
| 参数 | 说明 | 类型 | 默认值 |
| ----------- | ---------------------------------------- | ------- | ------ |
| immediately | 是否在第一次立即执行 | boolean | false |
| trailing | 是否在下降沿执行相关函数,即延迟后执行 | boolean | true |
| leading | 是否在上升沿执行相关函数,即在延迟前执行 | boolean | false |
---
针对时间管理的一些方法,如倒计时和计时器
#### 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 |
| 参数 | 说明 | 类型 | 默认值 |
| ----------- | -------------------- | ---------- | -------- |
| onComplete | 倒计时结束后的回调 | () => void | () => {} |
| auto | 是否立即开始倒计时 | boolean | true |
| isCountDown | 是否强制为倒计时模式 | boolean | false |
---
用于管理页面 title 的 hook,能满足多数使用场景。
#### API
`ts`
useTitle(title: string | (() => string | Promise
参数
| 参数 | 说明 | 类型 |
| ------- | --------------------------------------------------- | ---------------------------------------------------- |
| title | 要设置的字符串或能返回字符串的函数,支持异步 | string \| (() => string \| Promise
| options | 用于配置兜底 title,固定的前缀和后缀,onChange 函数 | Options |
| deps | 依赖数组,如果 deps 变化,会重新设置 title | any[] |
| 参数 | 说明 | 类型 |
| ------------ | ----------------------------------- | ----------------------------------------- |
| defaultTitle | 用于获取 title 失败或组件销毁时兜底 | string |
| prefix | 固定的前缀 | string |
| suffix | 固定的后缀 | string |
| onChange | title 变化时的回调函数 | (title: string, oldTitle: string) => void |
---
用于在两个不同的值之间进行切换,与 useBoolean 不同的是它也支持字符串和数字等。常见的使用场景如:开启/关闭通知、切换模式等。
#### API
`ts
type State = any;
export interface ReturnValue
state: T;
toggle: (value?: T) => void;
}
function useToggle
function useToggle
function useToggle
defaultValue: T,
reverseValue: U
): ReturnValue
`
参数
| 参数 | 说明 | 类型 | 默认值 |
| -------------- | ------------------------- | ----------- | ---------------------------------------------------- |
| defaultValue | 可选项,默认的状态值 | D = boolean | false |reverseValue
| | 可选项,toggle 后的状态值 | R = any | !defaultValue(请注意对非布尔值做 ! 操作的行为) |
返回值
| 参数 | 说明 | 类型 |
| ------ | ---------------------------------------------------- | ------------------------ |
| state | 当前状态值 | D \| R |
| toggle | 触发状态更改的函数,接受一个可选参数显式地修改状态值 | (value?: D \| R) => void |
---
组件卸载前执行回调的 hook。
#### API
`ts`
useUnmount(fn: () => void): void
参数
| 参数 | 说明 | 类型 |
| ---- | -------------------- | ---------- |
| fn | 组件卸载前执行的回调 | () => void |
---
一个只在依赖更新时执行的 useEffect hook。
#### API
`ts`
useUpdateEffect(
effect: () => void,
deps?: deps,
)
参数
| 参数 | 说明 | 类型 |
| ------ | -------------------------- | ------------------ |
| effect | 可执行函数 | function |
| deps | 可选项,传入依赖变化的对象 | array \| undefined |
---
这个 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)
---
提供虚拟化列表能力的 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 |
| 参数 | 说明 | 类型 | 默认值 |
| ---------- | ---------------------------------------------------- | ---------------------------------------------- | ------ |
| itemHeight | 每行高度,静态高度可直接传像素值,动态高度可传入函数 | number \| ((data: T, index: number) => number) | - |
| overscan | 视区上、下额外展示的 dom 节点数量 | number | 10 |
| onScroll | 滚动容器的滚动事件 | (e: UIEvent
---
可对您选择的 HTML 元素添加水印,具备丰富的用户自定义功能。利用 Canvas API 和 Mutation Observers 来写入不可变的水印。
#### API
`ts`
const { ref, updateConfig, loading } = useWatermark(config: WatermarkProps);
| 参数 | 说明 | 类型 |
| ------- | -------------------------------------------------------------- | -------------- |
| config | 可选配置项,用于配置水印以满足您的需求 | 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\
| updateConfig | 用于更新现有水印配置值的函数 | Partial\
| loading | 指示hook当前是否正在更新图片,仅适用于图片水印 | boolean |
`
``