mirror of
https://github.com/tenrok/axios.git
synced 2026-06-17 19:21:29 +03:00
Jay
334 lines
9.0 KiB
Markdown
334 lines
9.0 KiB
Markdown
# API 参考
|
|
|
|
以下是 axios 包中所有可用函数和类的列表。这些函数可在你的项目中使用和导入。所有函数和类均受我们遵循语义化版本的承诺保护，即在未发布主版本变更的情况下，这些 API 将保持稳定不变。
|
|
|
|
## 实例
|
|
|
|
`axios` 实例是你用于发起 HTTP 请求的主要对象，它是一个创建 `Axios` 类新实例的工厂函数。`axios` 实例提供了多个请求方法，详见文档的[请求别名](/pages/advanced/request-method-aliases)章节。
|
|
|
|
## 类
|
|
|
|
### `Axios`
|
|
|
|
`Axios` 类是发起 HTTP 请求的核心类，是一个创建 `Axios` 类新实例的工厂函数。该类提供多个 HTTP 请求方法，详见文档的[请求别名](/pages/advanced/request-method-aliases)章节。
|
|
|
|
#### `constructor`
|
|
|
|
创建一个新的 `Axios` 实例，构造函数接受一个可选的配置对象作为参数。
|
|
|
|
```ts
|
|
constructor(instanceConfig?: AxiosRequestConfig);
|
|
```
|
|
|
|
#### `request`
|
|
|
|
处理请求调用和响应解析，是发起 HTTP 请求的核心方法。接受一个配置对象作为参数，返回一个解析为响应对象的 Promise。
|
|
|
|
```ts
|
|
request(configOrUrl: string | AxiosRequestConfig<D>, config: AxiosRequestConfig<D>): Promise<AxiosResponse<T>>;
|
|
```
|
|
|
|
### `CancelToken` <Badge type="danger" text="已废弃，请改用 AbortController" />
|
|
|
|
`CancelToken` 类基于 `tc39/proposal-cancelable-promises` 提案，用于创建可取消 HTTP 请求的令牌。该类现已废弃，推荐使用 `AbortController` API。
|
|
|
|
从 0.22.0 版本起，`CancelToken` 类已废弃，将在未来版本中移除。建议改用 `AbortController` API。
|
|
|
|
该类主要为了向后兼容而保留导出，未来将被移除。我们强烈不建议在新项目中使用，因此不再对其 API 进行文档说明。
|
|
|
|
## 函数
|
|
|
|
### `AxiosError`
|
|
|
|
`AxiosError` 类是 HTTP 请求失败时抛出的错误类，继承自 `Error` 类并添加了额外属性。
|
|
|
|
#### `constructor`
|
|
|
|
创建一个新的 `AxiosError` 实例，构造函数接受可选的 message、code、config、request 和 response 作为参数。
|
|
|
|
```ts
|
|
constructor(message?: string, code?: string, config?: InternalAxiosRequestConfig<D>, request?: any, response?: AxiosResponse<T, D>);
|
|
```
|
|
|
|
#### `properties`
|
|
|
|
`AxiosError` 类提供以下属性：
|
|
|
|
```ts
|
|
// 配置实例。
|
|
config?: InternalAxiosRequestConfig<D>;
|
|
|
|
// 错误代码。
|
|
code?: string;
|
|
|
|
// 请求实例。
|
|
request?: any;
|
|
|
|
// 响应实例。
|
|
response?: AxiosResponse<T, D>;
|
|
|
|
// 表示该错误是否为 AxiosError 的布尔值。
|
|
isAxiosError: boolean;
|
|
|
|
// 错误状态码。
|
|
status?: number;
|
|
|
|
// 将错误转换为 JSON 对象的辅助方法。
|
|
toJSON: () => object;
|
|
|
|
// 错误原因。
|
|
cause?: Error;
|
|
```
|
|
|
|
### `AxiosHeaders`
|
|
|
|
`AxiosHeaders` 类是用于管理 HTTP 请求头的工具类，提供添加、删除和获取请求头等操作方法。
|
|
|
|
此处仅列出主要方法，完整方法列表请参阅类型声明文件。
|
|
|
|
#### `constructor`
|
|
|
|
创建一个新的 `AxiosHeaders` 实例，构造函数接受一个可选的请求头对象作为参数。
|
|
|
|
```ts
|
|
constructor(headers?: RawAxiosHeaders | AxiosHeaders | string);
|
|
```
|
|
|
|
#### `set`
|
|
|
|
向请求头对象添加一个请求头。
|
|
空字符串或仅包含空白字符的请求头名称会被忽略。
|
|
|
|
```ts
|
|
set(headerName?: string, value?: AxiosHeaderValue, rewrite?: boolean | AxiosHeaderMatcher): AxiosHeaders;
|
|
set(headers?: RawAxiosHeaders | AxiosHeaders | string, rewrite?: boolean): AxiosHeaders;
|
|
```
|
|
|
|
#### `get`
|
|
|
|
从请求头对象获取一个请求头。
|
|
|
|
```ts
|
|
get(headerName: string, parser: RegExp): RegExpExecArray | null;
|
|
get(headerName: string, matcher?: true | AxiosHeaderParser): AxiosHeaderValue;
|
|
```
|
|
|
|
#### `has`
|
|
|
|
检查请求头对象中是否存在某个请求头。
|
|
|
|
```ts
|
|
has(header: string, matcher?: AxiosHeaderMatcher): boolean;
|
|
```
|
|
|
|
#### `delete`
|
|
|
|
从请求头对象移除一个请求头。
|
|
|
|
```ts
|
|
delete(header: string | string[], matcher?: AxiosHeaderMatcher): boolean;
|
|
```
|
|
|
|
#### `clear`
|
|
|
|
从请求头对象移除所有请求头。
|
|
|
|
```ts
|
|
clear(matcher?: AxiosHeaderMatcher): boolean;
|
|
```
|
|
|
|
#### `normalize`
|
|
|
|
规范化请求头对象。
|
|
|
|
```ts
|
|
normalize(format: boolean): AxiosHeaders;
|
|
```
|
|
|
|
#### `concat`
|
|
|
|
合并多个请求头对象。
|
|
|
|
```ts
|
|
concat(...targets: Array<AxiosHeaders | RawAxiosHeaders | string | undefined | null>): AxiosHeaders;
|
|
```
|
|
|
|
#### `toJSON`
|
|
|
|
将请求头对象转换为 JSON 对象。
|
|
|
|
```ts
|
|
toJSON(asStrings: true): Record<string, string>;
|
|
toJSON(asStrings?: false): Record<string, string | string[]>;
|
|
```
|
|
|
|
### `CanceledError` <Badge type="tip" text="继承自 AxiosError" />
|
|
|
|
`CanceledError` 类是 HTTP 请求被取消时抛出的错误类，继承自 `AxiosError` 类。
|
|
|
|
### `Cancel` <Badge type="tip" text="CanceledError 的别名" />
|
|
|
|
`Cancel` 类是 `CanceledError` 类的别名，为向后兼容而保留导出，将在未来版本中移除。
|
|
|
|
### `isCancel`
|
|
|
|
检查某个错误是否为 `CanceledError` 的函数，可用于区分主动取消和意外错误。
|
|
|
|
```ts
|
|
isCancel<T = any>(value: any): value is CanceledError<T>;
|
|
```
|
|
|
|
```js
|
|
import axios from "axios";
|
|
|
|
const controller = new AbortController();
|
|
|
|
axios.get("/api/data", { signal: controller.signal }).catch((error) => {
|
|
if (axios.isCancel(error)) {
|
|
console.log("Request was cancelled:", error.message);
|
|
} else {
|
|
console.error("Unexpected error:", error);
|
|
}
|
|
});
|
|
|
|
controller.abort("User navigated away");
|
|
```
|
|
|
|
### `isAxiosError`
|
|
|
|
检查某个错误是否为 `AxiosError` 的函数。在 `catch` 块中使用此函数，可安全访问 axios 特有的错误属性，如 `error.response` 和 `error.config`。
|
|
|
|
```ts
|
|
isAxiosError(value: any): value is AxiosError;
|
|
```
|
|
|
|
```js
|
|
import axios from "axios";
|
|
|
|
try {
|
|
await axios.get("/api/resource");
|
|
} catch (error) {
|
|
if (axios.isAxiosError(error)) {
|
|
// error.response、error.config、error.code 均可使用
|
|
console.error("HTTP error", error.response?.status, error.message);
|
|
} else {
|
|
// 非 axios 错误（例如编程错误）
|
|
throw error;
|
|
}
|
|
}
|
|
```
|
|
|
|
### `all` <Badge type="danger" text="已废弃，请改用 Promise.all" />
|
|
|
|
`all` 函数接受一组 Promise 并返回一个在所有 Promise 都完成后才完成的单一 Promise，现已废弃，推荐使用 `Promise.all` 方法。
|
|
|
|
从 0.22.0 版本起，`all` 函数已废弃，将在未来版本中移除。建议改用 `Promise.all` 方法。
|
|
|
|
### `spread`
|
|
|
|
`spread` 函数可将一个参数数组展开为函数调用的多个参数，在你需要将数组参数传递给接收多个参数的函数时非常实用。
|
|
|
|
```ts
|
|
spread<T, R>(callback: (...args: T[]) => R): (array: T[]) => R;
|
|
```
|
|
|
|
### `toFormData`
|
|
|
|
将普通 JavaScript 对象（包括嵌套对象）转换为 `FormData` 实例，在需要从对象中以编程方式构建 multipart 表单数据时非常实用。
|
|
|
|
```ts
|
|
toFormData(sourceObj: object, formData?: FormData, options?: FormSerializerOptions): FormData;
|
|
```
|
|
|
|
```js
|
|
import { toFormData } from "axios";
|
|
|
|
const data = { name: "Jay", avatar: fileBlob };
|
|
const form = toFormData(data);
|
|
// form 现在是一个可直接发送的 FormData 实例
|
|
await axios.post("/api/users", form);
|
|
```
|
|
|
|
### `formToJSON`
|
|
|
|
将 `FormData` 实例转换回普通 JavaScript 对象，在需要以结构化格式读取表单数据时非常实用。
|
|
|
|
```ts
|
|
formToJSON(form: FormData): object;
|
|
```
|
|
|
|
```js
|
|
import { formToJSON } from "axios";
|
|
|
|
const form = new FormData();
|
|
form.append("name", "Jay");
|
|
form.append("role", "admin");
|
|
|
|
const obj = formToJSON(form);
|
|
console.log(obj); // { name: "Jay", role: "admin" }
|
|
```
|
|
|
|
### `getAdapter`
|
|
|
|
通过名称或名称数组解析并返回一个适配器函数。axios 在内部使用此函数为当前环境选择最合适的适配器。
|
|
|
|
```ts
|
|
getAdapter(adapters: string | string[]): AxiosAdapter;
|
|
```
|
|
|
|
```js
|
|
import { getAdapter } from "axios";
|
|
|
|
// 显式获取 fetch 适配器
|
|
const fetchAdapter = getAdapter("fetch");
|
|
|
|
// 按优先级列表获取最合适的适配器
|
|
const adapter = getAdapter(["fetch", "xhr", "http"]);
|
|
```
|
|
|
|
### `mergeConfig`
|
|
|
|
合并两个 axios 配置对象，使用与 axios 内部合并默认配置和请求级选项相同的深度合并策略。后者的值优先级更高。
|
|
|
|
```ts
|
|
mergeConfig<T>(config1: AxiosRequestConfig<T>, config2: AxiosRequestConfig<T>): AxiosRequestConfig<T>;
|
|
```
|
|
|
|
```js
|
|
import { mergeConfig } from "axios";
|
|
|
|
const base = { baseURL: "https://api.example.com", timeout: 5000 };
|
|
const override = { timeout: 10000, headers: { "X-Custom": "value" } };
|
|
|
|
const merged = mergeConfig(base, override);
|
|
// { baseURL: "https://api.example.com", timeout: 10000, headers: { "X-Custom": "value" } }
|
|
```
|
|
|
|
## 常量
|
|
|
|
### `HttpStatusCode`
|
|
|
|
包含 HTTP 状态码命名常量的对象，可用于编写更具可读性的条件判断，避免直接使用数字字面量。
|
|
|
|
```js
|
|
import axios, { HttpStatusCode } from "axios";
|
|
|
|
try {
|
|
const response = await axios.get("/api/resource");
|
|
} catch (error) {
|
|
if (axios.isAxiosError(error)) {
|
|
if (error.response?.status === HttpStatusCode.NotFound) {
|
|
console.error("Resource not found");
|
|
} else if (error.response?.status === HttpStatusCode.Unauthorized) {
|
|
console.error("Authentication required");
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
## 其他
|
|
|
|
### `VERSION`
|
|
|
|
`axios` 包的当前版本号字符串，随每次发布更新。
|