公共 API

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

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

TS 泛型说明

R 是返回 data 的泛型

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

FRformatresult 返回的 data 的类型 (注:后面文档提到的 R 泛型,在使用了 formatresult 后均要使用 FR 代替)

Return Values

data

  • 类型: Ref<R | undefined>

  • 默认值: undefined

    接口返回的数据,如果有传入 formatResult,则为格式化后的 data

loading

  • 类型: Ref<boolean>

  • 默认值: false

    Service 请求的执行状态

reloading New in 1.2.0

  • 类型: Ref<boolean>

  • 默认值: false

    是否正在刷新,用于记录 reload() 是否正在触发。

params

  • 类型: Ref<P[]>

  • 默认值: []

    Service 的请求参数

  • 示例:

function getUser(name) {
  return fetch('api/user?' + new URLSearchParams({ name })).then(res => res.json());
}

const { params, run } = useRequest(getUser, {
  defaultParams: ['John'],
});
// 默认请求时,如果存在 defaultParams, 则 params.value 将会等于 defaultParams,否则为空数组

// 当 run 传入参数时,此时的参数将会同步到 params 里面
run('Benny'); // params.value 等于 ['Benny']

error

  • 类型: Ref<Error | undefined>

  • 默认值: undefined

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

queries

  • 类型: Queries<R, P>

  • 默认值: Object

    默认情况下,新请求的数据将会覆盖旧请求的数据。当启用 queryKey() 后, queries 能够同时存储多次请求的结果,实现并行的效果.

    注意

    queries 是一个 reactive在新窗口打开 对象

    Queries 的类型如下

    type Queries<R, P> = {
      loading: boolean;
      data: R | undefined;
      error: Error | undefined;
      params: P[];
      run: (...params: P[]) => Promise<R>;
      cancel: () => void;
      refresh: () => Promise<R>;
      mutate: (arg: (oldData: R) => R) => void | (newData: R) => void;
    }
    
  • 参考:并发请求

run

cancel

  • 类型: () => void

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

    注意

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

refresh

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

    使用当前的 params 重新调用 run

reload

  • 类型: () => void

    用于清空 queries 数据,以及所有请求状态(包括data)。如果 manualfalse 的情况下,还会使用 defaultParams 重新触发 run()

mutate

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

    直接修改 data 的结果

  • 参考:数据更改

Service

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

请求函数

  • 类型:

    • (...params: P[]) => Promise<R>
    • | (...params: P[]) => string
    • | (...params: P[]) => ({ url: string; [key: string]: any; })
  • 详情:

    可以通过传入一个返回值为 Promise字符串 或者 对象 的函数。这里我们更加推荐返回一个 Promise。你可以借助第三方的请求库(如 axios )来帮你生成一个用于发起获取资源的请求 Promise 函数。

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

字符串

  • 类型: string

  • 详情:

    如果你传入一个字符串,或者通过请求函数返回一个字符串的方式调用,那么我们将会使用全局下的 fetch()在新窗口打开 方法发起获取资源的请求,该字符串将会作为获取资源的 URL

对象

  • 类型: { url: string; [key: string]: any; }

  • 详情:

    如果你传入一个对象,或者通过请求函数返回一个对象的方式调用,那么我们将会使用全局下的 fetch()在新窗口打开 方法发起获取资源的请求。该对象必须包含一个属性名为 URL 的键值对,该值将会作为获取资源的 URL

Options

loadingDelay

  • 类型: number

  • 默认值: 0

  • 详情:

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

  • 参考: 延迟加载状态

pollingInterval

  • 类型: number

  • 默认值: undefined

  • 详情:

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

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

pollingWhenHidden

  • 类型: boolean

  • 默认值: false

  • 详情:

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

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

pollingWhenOffline

  • 类型: boolean

  • 默认值: false

  • 详情:

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

  • 参考: 网络离线时轮询

debounceInterval

  • 类型: number

  • 默认值: undefined

  • 详情:

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

  • 参考: 防抖

debounceOptions New in 1.2.2

  • 类型: Object
  • 默认值:
{
  leading: false,
  maxWait: undefined,
  trailing: true
}
  • 详情:

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

throttleInterval

  • 类型: number

  • 默认值: undefined

  • 详情:

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

  • 参考: 节流

throttleOptions New in 1.2.2

  • 类型: Object
  • 默认值:
{
  leading: true,
  trailing: true,
}
  • 详情:

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

refreshOnWindowFocus

refocusTimespan

cacheKey

  • 类型: string

  • 默认值: undefined

  • 详情:

    • 我们会缓存每次请求的 data , error , params , loading
    • 如果设置了 cacheKey , VueRequest 会将当前请求数据缓存起来。当下次组件初始化时,如果有缓存数据,我们会优先返回缓存数据,然后在背后发送新请求,待新数据返回后,重新触发数据更新并更新缓存数据,也就是 SWR 的能力。
    • 同一个 cacheKey 的请求,是全局共享的,也就是你可以提前加载数据。利用该特性,可以很方便的实现预加载。
  • 参考: 缓存

cacheTime

  • 类型: number

  • 默认值: 600000

  • 详情:

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

  • 参考: 缓存时间

staleTime

  • 类型: number

  • 默认值: 0

  • 详情:

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

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

errorRetryCount

  • 类型: number

  • 默认值: 0

  • 详情:

    最大错误重试次数

  • 参考: 错误重试次数

errorRetryInterval

manual

  • 类型: boolean

  • 默认值: false

  • 详情:

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

  • 参考: 手动请求

defaultParams

  • 类型: P[]

  • 默认值: []

  • 详情:

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

ready

  • 类型: Ref<boolean>

  • 默认值: true

  • 详情:

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

    • 该行为只会触发一次。如果想要多次触发,建议使用 refreshDeps 或者自己实现相关逻辑
  • 参考: 依赖请求

initialData

  • 类型: R

  • 默认值: undefined

  • 详情:

    默认的 data

refreshDeps

  • 类型: WatchSource<any>[]

  • 默认值: []

  • 详情:

    refreshDeps 的变化,会触发 refresh 的重新执行。其本质只是对 watch在新窗口打开 的封装

    watch(refreshDeps, refresh);
    
  • 参考: 依赖刷新

queryKey

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

  • 详情:

    根据 params,获取当前请求的 key,设置之后,我们会在 queries 中同时维护不同 key 值的请求状态。

  • 参考: 并发请求

formatResult

  • 类型: (data: R) => FR

  • 详情:

    格式化请求结果,入参为原本接口返回的 data,出参为处理过后的 data

    import { defineComponent } from 'vue';
    import { useRequest } from 'vue-request';
    
    export default defineComponent({
      name: 'App',
      setup() {
        const { data } = useRequest<number, any, string>('api/timestramp', {
          formatResult: data => {
            return new Date(data);
          },
        });
        return () => <div>{data.value}</div>;
      },
    });
    

onSuccess

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

  • 详情:

    Service resolve 时触发,参数为 dataparams

onError

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

  • 详情:

    Service reject 时触发,参数为 errorparams

onBefore

  • Type: (params: P[]) => void

  • Details:

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

onAfter

  • Type: (params: P[]) => void

  • Details:

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

上次更新: 6/6/2023, 4:05:10 AM
贡献者: John