cancellableXHR

使用 XMLHttpRequest 发起可取消的网络请求，支持进度监听、超时控制和错误区分。

前置依赖

依赖参数

参数名	类型	说明
deps.XMLHttpRequest	XMLHttpRequestConstructor	浏览器或宿主环境提供的 XMLHttpRequest 构造函数

环境要求

• 浏览器 / WebView / 小程序：原生支持 XMLHttpRequest

函数签名

function cancellableXHR(
  url: string,
  options: CancellableXHROptions,
  deps: CancellableXHRDeps
): CancellableXHRResult

interface CancellableXHRDeps {
  XMLHttpRequest: XMLHttpRequestConstructor
}

interface CancellableXHROptions {
  method?: string
  headers?: Record<string, string>
  body?: BodyInit | Document | null
  responseType?: XMLHttpRequestResponseType
  withCredentials?: boolean
  timeout?: number
  onProgress?: (event: any) => void
}

interface CancellableXHRResult {
  promise: Promise<XMLHttpRequest>
  cancel: (reason?: any) => void
  xhr: XMLHttpRequest
}

参数

参数名	类型	必填	说明
url	string	是	请求地址
options.method	string	否	HTTP 方法，默认为 GET
options.headers	Record<string, string>	否	请求头
options.body	BodyInit | Document | null	否	请求体
options.responseType	XMLHttpRequestResponseType	否	响应类型，默认 ''
options.withCredentials	boolean	否	是否发送凭证
options.timeout	number	否	超时时间（毫秒）
options.onProgress	(event: any) => void	否	上传/下载进度回调
deps.XMLHttpRequest	XMLHttpRequestConstructor	是	环境提供的构造函数

返回值

类型	说明
promise	Promise<XMLHttpRequest>，请求成功 resolve，失败/取消 reject
cancel	(reason?: any) => void，调用后立即终止请求
xhr	XMLHttpRequest 实例，可直接读取响应数据

工作原理

1. 创建 XHR 实例：从依赖注入的构造函数创建 XMLHttpRequest，配置方法、URL、响应类型等参数。
2. 绑定事件：
   • load：状态码 200-299 判定为成功，resolve Promise。
   • error：网络层错误（DNS、断网等）reject。
   • timeout：超时后 reject，错误名为 TimeoutError。
   • abort：调用 cancel() 或外部中止时 reject，错误名为 AbortError。
   • progress：可选的进度回调，便于显示上传/下载进度。
3. 设置请求头与请求体：遍历 headers，调用 setRequestHeader，最后执行 send(body)。
4. 取消逻辑：cancel(reason) 调用 xhr.abort()，Promise 会以 AbortError 拒绝，避免组件卸载/路由切换导致的内存泄漏。

结合 cancellableFetch 可以覆盖现代 Fetch 和传统 XHR 的所有可取消场景：前者更适合通用网络请求，后者适合需要上传/下载进度、二进制流或旧环境兼容的需求。