公共 API

VueRequest 通常由 Return Values、Service 和 Options 三个部分组成

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

TS 泛型说明

R 是返回 data 的泛型

P 是 params 的泛型 （注：该泛型受到 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 响应式

类型： boolean | Ref<boolean>
默认值： false
详情：
当设置为 true 时，则在浏览器窗口触发 focus在新窗口打开和 visibilitychange在新窗口打开时，会重新发起请求。
参考： 聚焦时重新请求

refocusTimespan 响应式

类型： number | Ref<number>
默认值： 5 * 1000
详情：
当 refreshOnWindowFocus 设置为 true 时，你可以通过设置间隔的毫秒数，来限制 refresh 的执行间隔，默认为 5000ms
参考： 重新聚焦间隔时间

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 响应式

类型： number | Ref<number>
默认值： 0
详情：
默认情况下，VueRequest 使用二进制指数退避算法在新窗口打开来帮你计算出合适的间隔时间，你也可以通过设置 errorRetryInterval 来覆盖默认行为
参考： 错误重试间隔时间

manual

类型： boolean
默认值： false
详情：
当 manual 设置为 true 时，你需要手动触发 run 或者 runAsync 才会发起请求
参考： 手动请求

defaultParams

类型： P[]
默认值： []
详情：
如果 manual 设置为 false ，在自动执行请求的时候，将会把 defaultParams 作为请求参数

ready 响应式

类型： Ref<boolean> | () => boolean
默认值： true
详情：
只有当 ready 为 true 时，才会发起请求。
- 自动模式：当 manual=false 时，每次 ready 从 false 变为 true 时，都会自动发起请求，并且会带上参数 options.defaultParams。
- 手动模式：当 manual=true 时，只要 ready 为 false，则无法发起请求。
参考： 依赖请求

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 时触发，参数为 data 和 params

onError

类型： (error: Error, params: P[]) => void
详情：
当 Service reject 时触发，参数为 error 和 params

onBefore

类型： (params: P[]) => void
详情：
Service 请求前触发, 参数为 params.

onAfter

类型： (params: P[]) => void
详情：
Service 请求结束后触发, 参数为 params.

# 公共 API

# Return Values

# data

# loading

# params

# error

# run

# runAsync

# cancel

# refresh

# refreshAsync

# mutate

# Service

# Options

# loadingDelay 响应式

# loadingKeep 响应式

# pollingInterval 响应式

# pollingWhenHidden

# pollingWhenOffline

# debounceInterval 响应式

# debounceOptions 响应式

# throttleInterval 响应式

# throttleOptions 响应式

# refreshOnWindowFocus 响应式

# refocusTimespan 响应式

# cacheKey

# cacheTime

# staleTime

# setCache

# getCache

# errorRetryCount 响应式

# errorRetryInterval 响应式

# manual

# defaultParams

# ready 响应式

# initialData

# refreshDeps

# refreshDepsAction

# onSuccess

# onError

# onBefore

# onAfter