企业官网建设流程全解析

• 前端
• 开发工具

useConditionalTimeout是 beautiful-react-hooks 库中一个条件驱动的异步 Hook：它接收回调函数、延时毫秒数和一个布尔条件，仅在条件为true时才启动setTimeout延时执行回调，并支持在组件卸载或条件变化时按选项自动清理计时器。本文基于库文档 useConditionalTimeout 与源码 src/useConditionalTimeout.ts 展开，带你掌握它的完整参数签名、两个选项cancelOnUnmount/cancelOnConditionChange的实际行为，以及回调在组件重渲染下仍能正确执行的底层原理，读完即可在“确认某状态后才启动定时任务”“可取消的倒计时提示”等场景中直接落地。

为什么需要条件化的 Timeout

原生setTimeout在 React 函数组件中直接使用会面临几个典型问题：组件重渲染后回调引用可能过期、组件卸载后定时器仍在运行导致对已卸载组件调用setState、以及无法从 UI 上感知或取消计时器状态。库文档明确列出了useConditionalTimeout解决的三个动机：

• 只在某个条件被确认后才启动 timeout；
• 保证提供的回调在组件重渲染的情况下依然能被正确执行；
• 在组件卸载时（视选项而定）或条件被改变时终止 timeout。

它与同库的 useTimeout 的区别正在于“条件”：useTimeout在挂载时立即开始计时（见 src/useTimeout.ts 中useEffect里直接调用setTimeout），而useConditionalTimeout在启动前多了condition的判断。

安装与导入

按照 安装文档：

$ npm i --save beautiful-react-hooks

或使用 yarn：

$ yarn add beautiful-react-hooks

文档特别提醒：始终从库中按单模块导入，避免引入不必要的 Hook 及其依赖：

import useConditionalTimeout from 'beautiful-react-hooks/useConditionalTimeout';

这一导入方式由构建脚本 scripts/generate-exports.js 保障：它为每个src/*.ts文件生成独立的./useConditionalTimeout导出映射（含import、require与types三种入口），因此该 Hook 的package.jsonexports 是逐文件暴露的。useConditionalTimeout本身不依赖 rxjs、react-router-dom、redux 等第三方库，属于零 peer 依赖 Hook。

基本用法：条件为 true 才启动 2 秒延时

以下示例完整继承自官方文档，演示“点击按钮把条件置为true，2 秒后显示内容”的最基础场景：

import { useState } from 'react'; import { Button, Space, Typography } from 'antd'; import useConditionalTimeout from 'beautiful-react-hooks/useConditionalTimeout'; const ConditionalDelayedContentComponent = () => { const [condition, setCondition] = useState(false); const [showContent, setShowContent] = useState(false); useConditionalTimeout(() => { setShowContent(true) }, 2000, condition); const Actions = [ <Button type="primary" onClick={() => setCondition(true)} disabled={condition} loading={condition && !showContent}> {condition ? 'Timer started' : 'Start the timer'}&hellip; </Button> ] return ( <DisplayDemo title="useConditionalTimeout" actions={Actions}> <Space direction="vertical"> <Typography.Paragraph> Click on the following button to change the condition that triggers the 2 seconds timeout to true </Typography.Paragraph> <Typography.Paragraph> After timeout is elapsed a content is displayed </Typography.Paragraph> {showContent && <div style={{ fontSize: '3rem' }}>🕰</div>} </Space> </DisplayDemo>) }; <ConditionalDelayedContentComponent />

三个参数的含义：

返回值：isCleared 状态与 clear 方法

Hook 返回一个二元组[isCleared, clear]：第一个元素是超时是否已被清除的布尔状态，第二个元素是用于手动取消计时的函数。取消操作会触发一次重渲染（因为内部调用了setIsCleared(true)）。

官方文档给出的可取消 5 秒超时示例如下，注意取消按钮只在“尚未清除且内容尚未显示”时才渲染：

import { useState } from 'react'; import { Button, Typography } from 'antd'; import useConditionalTimeout from 'beautiful-react-hooks/useConditionalTimeout'; const ConditionalDelayedContentComponent = () => { const [condition, setCondition] = useState(false); const [showContent, setShowContent] = useState(false); const [isCleared, clearTimeoutRef] = useConditionalTimeout(() => { setShowContent(true) }, 5000, condition); const Actions = [ <Button type="primary" onClick={() => setCondition(true)} disabled={condition}>Start a 5 seconds timeout</Button> ] return ( <DisplayDemo title="useConditionalTimeout" actions={Actions}> <Typography.Paragraph>Content will show after 5 second starting from the following button click</Typography.Paragraph> {showContent && <div style={{ fontSize: '3rem' }}>🕰</div>} {!isCleared && !showContent && <Button onClick={clearTimeoutRef}>Cancel timeout</Button>} {isCleared && <Typography.Paragraph>Cleared</Typography.Paragraph>} </DisplayDemo> ) }; <ConditionalDelayedContentComponent />

测试文件 test/useConditionalTimeout.spec.js 对这个契约做了两条验证：返回值确实是[boolean, function]数组；调用clear()后result.current[0]由false变为true，且 spy 回调未被调用、重复调用clear()不会抛错（对应源码中if (timeout.current)的空值保护）。

选项（Options）参数详解

第四个参数是可选的options对象，两个开关的默认值均为true，可在 src/useConditionalTimeout.ts 的defaultOptions常量中确认：

const defaultOptions: UseConditionalTimeoutOptios = { cancelOnUnmount: true, cancelOnConditionChange: true }

cancelOnUnmount：组件卸载时是否清除定时器

默认true。置为false时，即便组件被卸载，已创建的setTimeout仍会继续跑完并执行回调——适用于“把延时操作交给全局状态或副作用”的场景。文档示例：

import { useState } from 'react'; import { Button } from 'antd'; import useConditionalTimeout from 'beautiful-react-hooks/useConditionalTimeout'; const ConditionalDelayedContentComponent = () => { const [condition, setCondition] = useState(false); const [showContent, setShowContent] = useState(false); const options = { cancelOnUnmount: false }; useConditionalTimeout(() => { setShowContent(true) }, 5000, condition, options); return ( <DisplayDemo title="useConditionalTimeout"> <Button type="primary" onClick={() => setCondition(true)}>Start a 5 seconds timeout</Button> {showContent && <div style={{ fontSize: '3rem' }}>🕰</div>} </DisplayDemo>) }; <ConditionalDelayedContentComponent />

测试用例 验证了该行为：以{ cancelOnUnmount: false }调用后执行rerender(null)卸载组件，延时到期后 spy 依然被调用。

实现位于 src/useConditionalTimeout.ts：一个空依赖数组的useEffect返回清理函数，组件卸载时检查opts.cancelOnUnmount，为true则执行clear()。

cancelOnConditionChange：条件变化时是否清除定时器

默认true。当condition相对于上一次渲染发生变化且选项为true时，Hook 会清除当前计时器。文档示例演示了两个useConditionalTimeout实例互相牵制的效果：

import { useState } from 'react'; import { Button } from 'antd'; import useConditionalTimeout from 'beautiful-react-hooks/useConditionalTimeout'; const ConditionalDelayedContentComponent = () => { const [condition, setCondition] = useState(false); const [showContent, setShowContent] = useState(false); useConditionalTimeout(() => { setShowContent(true) }, 5000, condition); useConditionalTimeout(() => { setCondition(false) }, 2000, condition); return ( <DisplayDemo title="useConditionalTimeout"> <Button type="primary" onClick={() => setCondition(true)}>Start a 5 seconds timeout</Button> {showContent && <div style={{ fontSize: '3rem' }}>🕰</div>} </DisplayDemo>) }; <ConditionalDelayedContentComponent />

点击按钮把condition置为true后：5 秒实例开始计时，2 秒实例也同时开始计时并在 2 秒后把condition改回false——此时 5 秒实例检测到条件变化，按默认选项清除自己的定时器，因此点击按钮不会触发任何最终动作。这是把cancelOnConditionChange当作“条件撤销即取消任务”的用法。

这一机制依赖对上一帧条件值的追踪：源码通过 usePreviousValue 拿到prevCondition，在 src/useConditionalTimeout.ts 中比较condition !== prevCondition后调用clear()。值得注意的细节是判断条件为prevCondition && condition !== prevCondition，即只有上一帧条件为真时条件翻转才会触发清除——从源码结构看，这意味着false -> true的翻转（首次启动）不会被误清，真正生效的是true -> false这类撤销场景。

源码剖析：重渲染下回调为何仍然正确

对照 src/useConditionalTimeout.ts 全文，整个 Hook 的运转可以拆成五个部分：

1. 回调引用缓存。callback = useRef(fn)配合一个[fn]依赖的useEffect：每次传入的fn变化且通过 isFunction 校验（检查typeof === 'function'及constructor/call/apply存在）时，就更新callback.current。这样定时器到期时调用的是callback.current()而非闭包里可能过期的旧fn——这是“组件重渲染后回调依然可靠执行”这一卖点的直接来源。
2. 计时器创建。[condition, milliseconds]依赖的useEffect中，仅当condition && typeof milliseconds === 'number'时执行setTimeout(() => callback.current(), milliseconds)，定时器句柄存入timeoutref。因此条件为false时根本不产生定时器。
3. 条件翻转清除。如上节所述，基于usePreviousValue的翻转检测 +cancelOnConditionChange选项。
4. 卸载清除。空依赖useEffect的清理函数，按cancelOnUnmount选项决定去留。
5. 状态回传。isCleared是一个useState布尔值，clear()内部先判空timeout.current，执行clearTimeout并setIsCleared(true)，最终以as UseConditionalTimeoutReturn断言为元组返回。

健壮性方面，测试 还覆盖了两个边界：options显式传null时 Hook 照常工作（源码用{ ...defaultOptions, ...(options || {}) }做了空值兜底）；传入非法参数（fn是数字、milliseconds是对象）时不抛错，返回isCleared = false且clear()可安全调用。

与useTimeout的实现对照（src/useTimeout.ts）可以看出两者共享同一套设计模式：相同的isCleared状态、相同的clear判空逻辑、相同的回调 ref 缓存，只是条件版把“是否启动”和“条件变化时是否取消”抽成了独立逻辑，并额外引入usePreviousValue做翻转检测。

适用场景与 API 类型定义

适用场景（文档 “When to use”）：需要在某个特定时长之后、且仅当某个特定条件被验证时才执行一个回调的场景。典型如：用户确认某项状态后才开始延时提示、表单进入“提交中”后延时弹出结果、轮询前等待某个开关开启等。

文档末尾给出的完整类型签名如下（引自 useConditionalTimeout.md Types 一节，与 src/useConditionalTimeout.ts 中的导出类型一致）：

import { type GenericFunction } from './shared/types'; /** * An async-utility hook that accepts a callback function and a delay time (in milliseconds), then delays the * execution of the given function by the defined time from when the condition verifies. */ declare const useConditionalTimeout: <TCallback extends GenericFunction>(fn: TCallback, milliseconds: number, condition: boolean, options?: UseConditionalTimeoutOptios) => UseConditionalTimeoutReturn; export interface UseConditionalTimeoutOptios { cancelOnUnmount?: boolean; cancelOnConditionChange?: boolean; } export type UseConditionalTimeoutReturn = [boolean, () => void]; export default useConditionalTimeout;

使用提示：

• milliseconds变化时会重新进入计时useEffect，从源码结构看这会以新的setTimeout覆盖旧句柄，因此延时参数应按“每次变化重置计时”来设计；
• 条件为false时不产生任何定时器，反复渲染是安全的；
• 如需在 UI 中展示“已取消”状态，直接使用返回值中的isCleared，它由clear()驱动更新。

• 前端
• 开发工具