useRequest

异步请求 Hook

Features

• 自动请求/手动请求
• swr
• 监听依赖变化，重新请求
• 防抖
• 节流
• 轮询
• 错误重试

代码演示

默认请求

在组件加载时，自动触发请求。同时自动管理异步请求的 loading , data , error 等状态

请求到的时间:

Live Editor

Copy

function Example() { const { data, loading } = useRequest([], () => { return new Promise(resolve => { setTimeout(resolve, 2000, new Date().toTimeString()) }) }) return ( <div> <Spin spinning={loading}> 请求到的时间: { data } </Spin> </div> ) }

function Example() {
  const { data, loading } = useRequest([], () => {
    return new Promise(resolve => {
      setTimeout(resolve, 2000, new Date().toTimeString())
    })
  })
  return (
    <div>
      <Spin spinning={loading}>
        请求到的时间: { data }
      </Spin>
    </div>
  )
}

手动触发

设置 options.manual = true, 则需要手动调用 request 时才会触发执行异步函数

请求到的时间:

Live Editor

Copy

function Example() { const { data, loading, request } = useRequest( [], () => { return new Promise(resolve => { setTimeout(resolve, 2000, new Date().toTimeString()) }) }, { manual: true, } ) const sendRequest = () => { request() } return ( <div> <div> <Spin spinning={loading}> 请求到的时间: { data } </Spin> </div> <Button style={{ marginTop: 20 }} onClick={sendRequest} > 发送请求 </Button> </div> ) }

function Example() {
  const { data, loading, request } = useRequest(
    [],
    () => {
      return new Promise(resolve => {
        setTimeout(resolve, 2000, new Date().toTimeString())
      })
    },
    {
      manual: true,
    }
  )
  const sendRequest = () => {
    request()
  }
  return (
    <div>
      <div>
        <Spin spinning={loading}>
          请求到的时间: { data }
        </Spin>
      </div>
      <Button
        style={{ marginTop: 20 }}
        onClick={sendRequest}
      >
        发送请求
      </Button>
    </div>
  )
}

轮询

通过设置 options.pollingInterval，进入轮询模式，定时触发函数执行

• 通过 polling / cancel 来 开启/停止 轮询
• 在 options.manual=true 时，需要执行 polling 开始轮询
• 通过设置 options.pollingWhenHidden=false ，在屏幕不可见时，暂停轮询
• 通过设置 options.pollingWhenOffline=false（默认为 false） ，在离线时，暂停轮询

请求到的时间:

开始停止

Live Editor

Copy

function Example() { const { data, loading, polling, cancel } = useRequest( [], () => { return new Promise(resolve => { setTimeout(resolve, 2000, new Date().toTimeString()) }) }, { manual: true, pollingInterval: 2000, pollingWhenHidden: false, } ) const [isPolling, setIsPolling] = useState(0) const handlePollStatusChange = (e) => { setIsPolling(e.target.value) if (e.target.value) { polling() } else { cancel() } } return ( <div> <div> <Spin spinning={loading}> 请求到的时间: { data } </Spin> </div> <div style={{ marginTop: 20 }}> <Radio.Group value={isPolling} onChange={handlePollStatusChange} > <Radio.Button value={1}>开始</Radio.Button> <Radio.Button value={0}>停止</Radio.Button> </Radio.Group> </div> </div> ) }

function Example() {
  const { data, loading, polling, cancel } = useRequest(
    [],
    () => {
      return new Promise(resolve => {
        setTimeout(resolve, 2000, new Date().toTimeString())
      })
    },
    {
      manual: true,
      pollingInterval: 2000,
      pollingWhenHidden: false,
    }
  )
  const [isPolling, setIsPolling] = useState(0)
  const handlePollStatusChange = (e) => {
    setIsPolling(e.target.value)
    if (e.target.value) {
      polling()
    } else {
      cancel()
    }
  }
  return (
    <div>
      <div>
        <Spin spinning={loading}>
          请求到的时间: { data }
        </Spin>
      </div>
      <div style={{ marginTop: 20 }}>
        <Radio.Group 
          value={isPolling}
          onChange={handlePollStatusChange}
        >
          <Radio.Button value={1}>开始</Radio.Button>
          <Radio.Button value={0}>停止</Radio.Button>
        </Radio.Group>
      </div>
    </div>
  )
}

防抖

通过设置 options.debounceInterval，进入防抖模式

Fetched count:

Live Editor

Copy

function Example() { const countRef = useRef(0) const { data, loading, request } = useRequest( [], () => { return new Promise(resolve => { setTimeout(resolve, 500, countRef.current++) }) }, { manual: true, debounceInterval: 300, } ) const sendRequest = () => { request() } return ( <div> <div> <Spin spinning={loading}> Fetched count: { data } </Spin> </div> <Button style={{ marginTop: 20 }} onClick={sendRequest} > 发送请求 </Button> </div> ) }

function Example() {
  const countRef = useRef(0)
  const { data, loading, request } = useRequest(
    [],
    () => {
      return new Promise(resolve => {
        setTimeout(resolve, 500, countRef.current++)
      })
    },
    {
      manual: true,
      debounceInterval: 300,
    }
  )
  const sendRequest = () => {
    request()
  }
  return (
    <div>
      <div>
        <Spin spinning={loading}>
          Fetched count: { data }
        </Spin>
      </div>
      <Button
        style={{ marginTop: 20 }}
        onClick={sendRequest}
      >
        发送请求
      </Button>
    </div>
  )
}

节流

通过设置 options.throttleInterval，进入节流模式

Fetched count:

Live Editor

Copy

function Example() { const countRef = useRef(0) const { data, loading, request } = useRequest( [], () => { return new Promise(resolve => { setTimeout(resolve, 500, countRef.current++) }) }, { manual: true, throttleInterval: 300, } ) return ( <div> <div> <Spin spinning={loading}> Fetched count: { data } </Spin> </div> <Button style={{ marginTop: 20 }} onClick={request} > 发送请求 </Button> </div> ) }

function Example() {
  const countRef = useRef(0)
  const { data, loading, request } = useRequest(
    [],
    () => {
      return new Promise(resolve => {
        setTimeout(resolve, 500, countRef.current++)
      })
    },
    {
      manual: true,
      throttleInterval: 300,
    }
  )
  return (
    <div>
      <div>
        <Spin spinning={loading}>
          Fetched count: { data }
        </Spin>
      </div>
      <Button
        style={{ marginTop: 20 }}
        onClick={request}
      >
        发送请求
      </Button>
    </div>
  )
}

SWR

设置 swr = true 和 key，key 通过 keySerializer 得到的 cacheKey 作为缓存标识

keySerializer 规则见 key

请求到的时间：

Live Editor

Copy

(() => { function ServerTime() { const { data, loading } = useRequest( 'cacheKey', () => { return new Promise(resolve => { setTimeout(resolve, 500, new Date().toTimeString()) }) }, { swr: true, } ) return ( <div> 请求到的时间：{ data } </div> ) } return function Example() { const [visible1, setVisible1] = useState(true) const [visible2, setVisible2] = useState(false) return ( <> <div style={{ display: 'flex', alignItems: 'center', marginBottom: 20, }} > <Button onClick={() => setVisible1(!visible1)} style={{ marginRight: 20 }} > { visible1 ? 'hide' : 'show' } </Button> { visible1 && <ServerTime/> } </div> <div style={{ display: 'flex', alignItems: 'center', marginBottom: 20, }} > <Button onClick={() => setVisible2(!visible2)} style={{ marginRight: 20 }} > { visible2 ? 'hide' : 'show' } </Button> { visible2 && <ServerTime/> } </div> </> ) } })()

(() => {
  function ServerTime() {
    const { data, loading } = useRequest(
      'cacheKey',
      () => {
        return new Promise(resolve => {
          setTimeout(resolve, 500, new Date().toTimeString())
        })
      },
      {
        swr: true,
      }
    )
  
    return (
      <div>
        请求到的时间：{ data }
      </div>
    )
  }
  return function Example() {
    const [visible1, setVisible1] = useState(true)
    const [visible2, setVisible2] = useState(false)
    return (
      <>
        <div 
          style={{ 
            display: 'flex', 
            alignItems: 'center',
            marginBottom: 20,
          }}
        >
          <Button
            onClick={() => setVisible1(!visible1)}
            style={{ marginRight: 20 }}
          >
            { visible1 ? 'hide' : 'show' }
          </Button>
          { visible1 && <ServerTime/> }
        </div>
        <div 
          style={{ 
            display: 'flex', 
            alignItems: 'center',
            marginBottom: 20,
          }}
        >
          <Button
            onClick={() => setVisible2(!visible2)}
            style={{ marginRight: 20 }}
          >
            { visible2 ? 'hide' : 'show' }
          </Button>
          { visible2 && <ServerTime/> }
        </div>
      </>
    )
  }
})()

Mutation

通过调用返回的 mutate，直接修改 data

函数签名见 Mutate

第二个参数 shouldRefresh 默认为 true，即突变数据后会重新发送请求

注：swr 模式下，相同 cacheKey 的数据会同步更新，详见 SWR

shouldRefresh：

truefalse

Live Editor

Copy

function Example() { const [shouldRefresh, setShouldRefresh] = useState(true) const { data, loading, mutate } = useRequest( 'cacheKey', () => { return new Promise(resolve => { setTimeout(resolve, 500, Math.random()) }) }, ) return ( <div> <Spin spinning={loading}> { data } </Spin> <div style={{ marginTop: 20 }}> shouldRefresh： <Radio.Group onChange={e => setShouldRefresh(e.target.value)} value={shouldRefresh} > <Radio value={true}>true</Radio> <Radio value={false}>false</Radio> </Radio.Group> </div> <Button onClick={() => mutate(Math.random(), shouldRefresh)} style={{ marginTop: 20 }} > mutation </Button> </div> ) }

function Example() {
  const [shouldRefresh, setShouldRefresh] = useState(true)
  const { data, loading, mutate } = useRequest(
    'cacheKey',
    () => {
      return new Promise(resolve => {
        setTimeout(resolve, 500, Math.random())
      })
    },
  )
  return (
    <div>
      <Spin spinning={loading}>
        { data }
      </Spin>
      <div style={{ marginTop: 20 }}>
        shouldRefresh：
        <Radio.Group 
          onChange={e => setShouldRefresh(e.target.value)} 
          value={shouldRefresh}
        >
          <Radio value={true}>true</Radio>
          <Radio value={false}>false</Radio>
        </Radio.Group>
      </div>
      <Button
        onClick={() => mutate(Math.random(), shouldRefresh)}
        style={{ marginTop: 20 }}
      >
        mutation
      </Button>
    </div>
  )
}

屏幕聚焦刷新请求

如果设置了 options.refreshOnFocus=true ，在屏幕聚焦时会触发再次请求；可以设置 focusThrottleInterval 来限制触发的时间间隔，默认为 5000

请求到的时间：

Live Editor

Copy

function Example() { const { data, loading } = useRequest( [], () => { return new Promise(resolve => { setTimeout(resolve, 500, new Date().toTimeString()) }) }, { refreshOnFocus: true, focusThrottleInterval: 0, } ) return ( <div> <Spin spinning={loading}> 请求到的时间：{ data } </Spin> </div> ) }

function Example() {
  const { data, loading } = useRequest(
    [],
    () => {
      return new Promise(resolve => {
        setTimeout(resolve, 500, new Date().toTimeString())
      })
    },
    {
      refreshOnFocus: true,
      focusThrottleInterval: 0,
    }
  )
  return (
    <div>
      <Spin spinning={loading}>
        请求到的时间：{ data }
      </Spin>
    </div>
  )
}

请求条件控制

在 manual = false 时，当第一个参数（key）为 truthy 值类型，或者返回 truthy 值的函数，才发送请求

注意：该行为依赖于默认 keySerializer 的实现

请求到的时间：

是否请求：

是否

Live Editor

Copy

function Example() { const [shouldRequest, setShouldRequest] = useState(false) const { data, loading } = useRequest( () => shouldRequest, () => { return new Promise(resolve => { setTimeout(resolve, 500, new Date().toTimeString()) }) }, ) return ( <div> <Spin spinning={loading}> 请求到的时间：{ data } </Spin> <div style={{ marginTop: 20 }}> 是否请求： <Radio.Group onChange={e => setShouldRequest(e.target.value)} value={shouldRequest} > <Radio value={true}>是</Radio> <Radio value={false}>否</Radio> </Radio.Group> </div> </div> ) }

function Example() {
  const [shouldRequest, setShouldRequest] = useState(false)
  const { data, loading } = useRequest(
    () => shouldRequest,
    () => {
      return new Promise(resolve => {
        setTimeout(resolve, 500, new Date().toTimeString())
      })
    },
  )
  return (
    <div>
      <Spin spinning={loading}>
        请求到的时间：{ data }
      </Spin>
      <div style={{ marginTop: 20 }}>
        是否请求：
        <Radio.Group 
          onChange={e => setShouldRequest(e.target.value)} 
          value={shouldRequest}
        >
          <Radio value={true}>是</Radio>
          <Radio value={false}>否</Radio>
        </Radio.Group>
      </div>
    </div>
  )
}

监听依赖

在 manual = false 时，当根据第一个参数（key）生成的 cacheKey 变化时，重新发送请求：

注意：该行为依赖于 keySerializer 的实现

请求到的时间：

年月日时分秒

Live Editor

Copy

function Example() { const [timeType, setTimeType] = useState(1) const { data, loading } = useRequest( [timeType], (timeType) => { return new Promise(resolve => { const value = timeType === 1 ? new Date().toDateString() : new Date().toTimeString() setTimeout(resolve, 500, value) }) }, ) return ( <div> <Spin spinning={loading}> 请求到的时间：{ data } </Spin> <Radio.Group onChange={e => setTimeType(e.target.value)} value={timeType} style={{ marginTop: 20 }} > <Radio value={1}>年月日</Radio> <Radio value={2}>时分秒</Radio> </Radio.Group> </div> ) }

function Example() {
  const [timeType, setTimeType] = useState(1)
  const { data, loading } = useRequest(
    [timeType],
    (timeType) => {
      return new Promise(resolve => {
        const value = timeType === 1 ? new Date().toDateString() : new Date().toTimeString()
        setTimeout(resolve, 500, value)
      })
    },
  )
  return (
    <div>
      <Spin spinning={loading}>
        请求到的时间：{ data }
      </Spin>
      <Radio.Group 
        onChange={e => setTimeType(e.target.value)} 
        value={timeType}
        style={{ marginTop: 20 }}
      >
        <Radio value={1}>年月日</Radio>
        <Radio value={2}>时分秒</Radio>
      </Radio.Group>
    </div>
  )
}

错误重试

设置 shouldRetryOnError=true，开启错误重试

• 通过 errorRetryInterval 设置重试间隔，默认为 5000
• 通过 errorRetryCount 设置最大重试次数
• 通过 onErrorRetry 设置错误重试处理函数

请求到的时间：

第 -1 次重试（最多 5 次）

Live Editor

Copy

function Example() { const [count, setCount] = useState(0) const { data, loading, error } = useRequest( [], () => { return new Promise((_, reject) => { setCount(n => n + 1) setTimeout(reject, 500) }) }, { shouldRetryOnError: true, errorRetryInterval: 2000, errorRetryCount: 5, } ) return ( <div> <Spin spinning={loading}> <span style={{ color: error ? 'red' : 'inherit' }}> 请求到的时间：{ data } </span> </Spin> <div>第 { count - 1 } 次重试（最多 5 次）</div> </div> ) }

function Example() {
  const [count, setCount] = useState(0)
  const { data, loading, error } = useRequest(
    [],
    () => {
      return new Promise((_, reject) => {
        setCount(n => n + 1)
        setTimeout(reject, 500)
      })
    },
    {
      shouldRetryOnError: true,
      errorRetryInterval: 2000,
      errorRetryCount: 5,
    }
  )
  return (
    <div>
      <Spin spinning={loading}>
        <span style={{ color: error ? 'red' : 'inherit' }}>
          请求到的时间：{ data }
        </span>
      </Spin>
      <div>第 { count - 1 } 次重试（最多 5 次）</div>
    </div>
  )
}

API

type Fetcher<T = any> = (...args: any[]) => Promise<T>
type CatchedPromise<T> = Promise<[null, T] | [Error, null]>
type CatchedFetcher<T = any> = (...args: any[]) => CatchedPromise<T>
type useRequest = {
  <T>(
    key: any,
    options?: Options<T>
  ): Result<T>
  <T>(
    key: any,
    fetcher: Fetcher<T>,
    options?: Options<T>
  ): Result<T>
}

key

key 的作用：

• key 通过 keySerializer 转换为缓存标识（cacheKey）和请求方法（fetcher）参数
• 控制请求条件：key 根据 keySerializer 转换成的 cacheKey 为 falsy 值时，请求不发送
• 根据依赖刷新请求：key 根据 keySerializer 转换成的 cacheKey 变化时，重新发送请求

默认 keySerializer 的规则：

• 除了抛出错误的函数外，key = <value> 等同于 key = () => <value>，当 <value> 数据量很大时，建议使用 key = () => <value>
• key 为 falsy 值或返回 falsy 值的函数或抛出错误的函数时，转换成的 cacheKey 为 null
• key 为对象时，深度序列化后的值不变，则转换成的 cacheKey 不变
• key 为数组时，数组项不变（数组项为对象时，深度序列化后再比较），则转换成的 cacheKey 不变

Options

参数均为可选

参数	说明	类型	默认值
manual	是否手动调用请求方法，通过调用返回的 request 方法	boolean	false
initialData	初始数据	T | null	null
keySerializer	key 的转换函数，传入 key，返回 [cacheKey, fetcherArgs]	(key: any) => [string | null, any[] | null]	-
swr	是否使用 swr 模式	boolean	false
debounceInterval	防抖间隔, 单位为毫秒，设置后，请求进入防抖模式	number	-
debounceOptions	防抖参数，maxWait 设置延迟的最大值	{ maxWait?: number }	-
throttleInterval	节流间隔, 单位为毫秒，设置后，请求进入节流模式	number	-
pollingInterval	轮询间隔	number	-
pollingWhenHidden	在页面隐藏时，是否继续轮询	boolean	true
pollingWhenOffline	在离线时，是否继续轮询	boolean	false
pollingWhenError	请求报错时，是否继续轮询，当设置为 false 且 shouldRetryOnError = true 时，重试得到成功响应后，继续轮询	boolean	false
refreshOnReconnect	是否在网络连接上后刷新请求	boolean	true
refreshOnFocus	页面重新获取焦点时，是否触发 refresh	boolean	false
focusThrottleInterval	获取焦点事件在指定时间间隔内只触发一次 refresh	number	5000
shouldRetryOnError	请求失败时是否重试	boolean	false
errorRetryInterval	重试间隔	number	5000
errorRetryCount	最大重试次数	number	-
onErrorRetry	错误重试处理函数	(error: Error, key, options: Options, request, requestOptions: {retryCount: number; forPolling: boolean}) => void	-

Result

参数	说明	类型
data	请求返回的数据	T
error	请求错误	Error
loading	表示是否在请求中	boolean
retrying	表示是否在重试中	boolean
request	手动调用方法	Function
params	请求方法参数数组	any[]
cancel	取消当前请求的函数方法	() => void
mutate	手动修改返回的data	Mutate

Mutate

type Mutate = (data: T | ((oldData: T) => T) | Promise<T>, shouldRefresh: boolean) => void