useRequest

沈孟平

最后更新于 2026-04-23 19:53:53

提示

注意：此组件主要适用于本模板的 axios 封装请求函数，如果需要使用其他请求函数，请确保请求函数返回值类型与示例一致：

{
  "data": {
    "msg": "ok",
    "code": 200,
    "data": "you want type"
  }
}

这个主要是针对此模板的请求进行了封转和简化，可根据此系统的 axios 封装的 http 请求函数进行良好的类型推断。它还支持 防抖、节流、轮询、默认参数、取消错误 loading 等功能。

配置项

名称	类型	默认值	说明
manual	boolean	true	是否手动触发请求；设为 false 时会在初始化时自动执行
defaultParams	Params	undefined	默认参数；调用 run(params) 时会和传入参数合并
throttle	number	0	节流时间，单位 ms
debounce	number	0	防抖时间，单位 ms；优先级高于 throttle
polling	number	undefined	轮询间隔，单位 ms
cancelLoadingWhenErr	boolean	undefined	当错误是取消请求产生时，是否保持 loading 状态
onSuccess	(data: Data) => void	undefined	请求成功后的回调
shallow	boolean	true	是否使用 shallowRef 保存 data

返回值

名称	类型	说明
data	Ref<Data | undefined>	请求成功后的业务数据，默认取返回结果中的 data.data
loading	Ref<boolean>	请求进行中状态
err	Ref<Error | undefined>	请求错误信息
response	Ref<Awaited<ReturnType<T>> | undefined>	原始响应对象
run	(params?: Params, withDefaultParams?: boolean) => Promise<Data | undefined>	手动触发请求，支持与 defaultParams 合并
pollingControl	Pausable | undefined	开启轮询时返回的控制器，可暂停或恢复轮询

行为说明

• 同时传了 debounce 和 throttle 时，会优先走防抖。
• manual: false 时会立即按 defaultParams 自动执行一次。
• 如果返回值里存在 err，data 会被清空为 undefined。
• response 会始终保留原始返回结果，适合你要读取 data.data 之外的字段时使用。

什么时候把 shallow 设为 false

默认情况下，data 使用 shallowRef，这样在大多数列表和查询场景下性能更稳。

如果你要把返回结果继续交给深层响应式逻辑使用，例如：

• 作为 AtForm 的 deps
• 作为级联、树形、异步回显选项
• 需要深度 watch 返回对象内部字段

这时建议把 shallow 设为 false，让返回值改为深层响应式。

适合的场景

• 列表页查询
• 表单选项异步加载
• 需要轮询状态的任务页
• 依赖当前模板请求返回结构做类型推断的接口调用

Demo