公共 API

VueRequest 通常由 Return ValuesServiceOptions 三个部分组成

const { ...ReturnValues } = useRequest<R, P>(Service, Options);

TS 泛型说明

R 是返回 data 的泛型

Pparams 的泛型 (注:该泛型受到 unknown[] 的约束)

Return Values

data

  • 类型: shallowRef<R | undefined>

  • 默认值: undefined

    接口返回的数据。

loading

  • 类型: Ref<boolean>

  • 默认值: false

    Service 请求的执行状态

params

  • 类型: Ref<P[]>

  • 默认值: []

    Service 的请求参数

  • 示例:

    function getUser(name, age) {
      return axios.get('api/user', {
        params: {
          name: name,
          age: age,
        },
      });
    }
    
    const { params, run } = useRequest(getUser, {
      defaultParams: ['John', 18],
    });
    // 默认请求时,如果存在 defaultParams, 则 params.value 将会等于 defaultParams,否则为空数组
    
    // 当 run 传入参数时,此时的参数将会同步到 params 里面
    run('Benny', 18); // params.value 等于 ['Benny', 18]
    

error

  • 类型: shallowRef<Error | undefined>

  • 默认值: undefined

    如果在内部抛出了一个错误,则会被 error 接收并返回

run

  • 类型: (...params: P[]) => void

    手动触发 Service 的请求。会自动捕获异常,通过 options.onError 处理

runAsync

  • 类型: (...params: P[]) => Promise<R>

    run 用法一致。但返回的是 Promise,需要自行处理异常。

cancel

  • 类型: () => void

    • 手动取消本次请求
    • 停止轮询功能

    注意

    这里说的取消并不是真正的停止请求,只是取消了对 data 的赋值以及 loading 重置为 false 当前已发出的接口请求依旧会继续进行

refresh

  • 类型: () => void

    使用上一次的 params 重新调用 run

refreshAsync

  • 类型: () => Promise<R>

    使用上一次的 params 重新调用 runAsync

mutate

  • 类型: (arg: (oldData: R) => R) => void | (newData: R) => void

    直接修改 data 的结果

  • 参考:数据更改

Service

  • 类型: (...params: P[]) => Promise<R>

  • 详情:

    用于发起获取资源的请求 ,可参考 数据请求

    Service 必须是一个返回 Promise 的函数。你可以借助第三方的请求库(如 axios )来帮你生成一个用于发起获取资源的请求 Promise 函数。

    import { useRequest } from 'vue-request';
    import axios from 'axios';
    
    const getUser = () => {
      return axios.get('api/user');
    };
    
    const { data } = useRequest(getUser);
    

Options

loadingDelay 响应式

  • 类型: number | Ref<number>

  • 默认值: 0

  • 详情:

    通过设置延迟的毫秒数,可以延迟 loading 变成 true 的时间,有效防止闪烁。

  • 参考: Loading 状态

loadingKeep 响应式

  • 类型: number | Ref<number>

  • 默认值: 0

  • 详情:

    可以让 loading 动画保持一定的时间。

  • 参考: Loading 状态

pollingInterval 响应式

  • 类型: number | Ref<number>

  • 默认值: undefined

  • 详情:

    通过设置轮询间隔毫秒值,可以进入轮询模式,定时触发请求。可以通过 run / cancel开启/停止 轮询。在 manual设置为true 时,需要手动执行一次 run 后,才开始轮询。

    • 间隔值必须大于 0 才会生效
  • 参考: 轮询

pollingWhenHidden

  • 类型: boolean

  • 默认值: false

  • 详情:

    pollingInterval 大于 0 时才生效。默认情况下,轮询在屏幕不可见时,会暂停轮询。当设置成 true 时,在屏幕不可见时,轮询任务依旧会定时执行。

  • 参考: 屏幕不可见时轮询

pollingWhenOffline

  • 类型: boolean

  • 默认值: false

  • 详情:

    pollingInterval 大于 0 时才生效。默认情况下,轮询在网络不可用时,会暂停轮询。当设置成 true 时,在网络不可用时,轮询任务依旧会定时执行。

  • 参考: 网络离线时轮询

debounceInterval 响应式

  • 类型: number | Ref<number>

  • 默认值: undefined

  • 详情:

    通过设置需要延迟的毫秒数,进入防抖模式。此时如果频繁触发请求,则会以防抖策略进行请求。

  • 参考: 防抖

debounceOptions 响应式

  • 类型: DebounceOptions | Reactive<DebounceOptions>

    type DebounceOptions = {
      leading: boolean;
      maxWait: number;
      trailing: boolean;
    };
    
  • 默认值:

    {
      leading: false,
      maxWait: undefined,
      trailing: true
    }
    
  • 详情:

    • leading (boolean): 指定在延迟开始前调用。
    • maxWait (number): 设置请求方法允许被延迟的最大值。
    • trailing (boolean): 指定在延迟结束后调用。

throttleInterval 响应式

  • 类型: number | Ref<number>

  • 默认值: undefined

  • 详情:

    通过设置需要节流的毫秒数,进入节流模式。此时如果频繁触发请求,则会以节流策略进行请求。

  • 参考: 节流

throttleOptions 响应式

  • 类型: ThrottleOptions | Reactive<ThrottleOptions>

    type ThrottleOptions = {
      leading: boolean;
      trailing: boolean;
    };
    
  • 默认值:

    {
      leading: true,
      trailing: true,
    }
    
  • 详情:

    • leading (boolean): 指定调用在节流开始前。
    • trailing (boolean): 指定调用在节流结束后。

refreshOnWindowFocus 响应式

refocusTimespan 响应式

cacheKey

  • 类型: string | (params?: P) => string

  • 默认值: undefined

  • 详情:

    • 我们会缓存每次请求的 data , error , params , loading
    • 如果设置了 cacheKey , VueRequest 会将当前请求数据缓存起来。当下次组件初始化时,如果有缓存数据,我们会优先返回缓存数据,然后在背后发送新请求,待新数据返回后,重新触发数据更新并更新缓存数据,也就是 SWR 的能力。
    • 数据同步,任何时候,当我们改变其中某个 cacheKey 的内容时,其它相同 cacheKey 的数据也会同步改变。
    • 请求 Promise 共享,相同的 cacheKey 同时只会有一个在发起请求,后发起的会共用同一个请求 Promise
  • 参考: 缓存

cacheTime

  • 类型: number

  • 默认值: 10* 60 * 1000

  • 详情:

    当开启缓存后,你可以通过设置 cacheTime 来告诉我们缓存的过期时间。当缓存过期后,我们会将其删除。默认为 600000 毫秒,即 10 分钟

  • 参考: 缓存时间

staleTime

  • 类型: number

  • 默认值: 0

  • 详情:

    如果你能确保缓存下来的数据,在一定时间内不会有任何更新的,我们建议你设置一个合理的毫秒数

    • 默认为 0,意味着不保鲜,每次都会重新发起请求
    • 设置为 -1 则意味着缓存永不过期
  • 参考: 保鲜时间

setCache

  • 类型: (cacheKey: string, cacheData: CacheData) => void

    type CacheData = {
      data: R;
      params: P;
      time: number;
    };
    
  • 详情:

    自定义设置缓存

  • 参考: 自定义缓存

getCache

  • 类型: (cacheKey: string) => CacheData

    type CacheData = {
      data: R;
      params: P;
      time: number;
    };
    
  • 详情:

    自定义读取缓存

  • 参考: 自定义缓存

errorRetryCount 响应式

  • 类型: number | Ref<number>

  • 默认值: 0

  • 详情:

    最大错误重试次数

  • 参考: 错误重试次数

errorRetryInterval 响应式

manual

  • 类型: boolean

  • 默认值: false

  • 详情:

    manual 设置为 true 时,你需要手动触发 run 或者 runAsync 才会发起请求

  • 参考: 手动请求

defaultParams

  • 类型: P[]

  • 默认值: []

  • 详情:

    如果 manual 设置为 false ,在自动执行请求的时候,将会把 defaultParams 作为请求参数

ready 响应式

  • 类型: Ref<boolean> | () => boolean

  • 默认值: true

  • 详情:

    只有当 readytrue 时,才会发起请求。

    • 自动模式:当 manual=false 时,每次 readyfalse 变为 true 时,都会自动发起请求,并且会带上参数 options.defaultParams
    • 手动模式:当 manual=true 时,只要 readyfalse,则无法发起请求。
  • 参考: 依赖请求

initialData

  • 类型: R

  • 默认值: undefined

  • 详情:

    默认的 data

refreshDeps

  • 类型: WatchSource<any> | WatchSource<any>[]

  • 默认值: []

  • 详情:

    refreshDeps 里面的内容发生变化时,如果没有设置 refreshDepsAction, 就会触发 refresh 的重新执行。其本质只是对 watch在新窗口打开 的封装。

    watch(refreshDeps, refresh);
    

refreshDepsAction

  • 类型: () => void

  • 详情:

    refreshDeps 里面的内容发生变化时,会被调用。manual=true 时也会被触发

  • 参考: refreshDepsAction

onSuccess

  • 类型: (data: R, params: P[]) => void

  • 详情:

    Service resolve 时触发,参数为 dataparams

onError

  • 类型: (error: Error, params: P[]) => void

  • 详情:

    Service reject 时触发,参数为 errorparams

onBefore

  • 类型: (params: P[]) => void

  • 详情:

    Service 请求前触发, 参数为 params.

onAfter

  • 类型: (params: P[]) => void

  • 详情:

    Service 请求结束后触发, 参数为 params.

上次更新: 2023/7/6 03:23:08
贡献者: John