mirror of https://github.com/allinssl/allinssl
285 lines
6.9 KiB
Markdown
285 lines
6.9 KiB
Markdown
# useAxios 使用文档
|
||
|
||
## 基本介绍
|
||
|
||
`useAxios` 是一个基于 Vue 3 的 Axios 封装钩子函数，它提供了一种简洁的方式来管理 HTTP 请求。通过这个钩子函数，你可以轻松地处理请求状态、加载状态、错误处理、请求取消等功能。
|
||
|
||
## 核心函数
|
||
|
||
### useAxios
|
||
|
||
```typescript
|
||
function useAxios<T = unknown, Z = Record<string, unknown>>(instance: HttpClient): useAxiosReturn<T, Z>
|
||
```
|
||
|
||
**参数**:
|
||
|
||
- `instance`: HttpClient 实例，用于发送 HTTP 请求
|
||
|
||
**返回值**:
|
||
包含以下属性和方法的对象：
|
||
|
||
**状态属性**:
|
||
|
||
- `loadingMask`: 加载遮罩配置，类型为 `Ref<{ status: boolean } & LoadingMaskOptions>`
|
||
- `message`: 是否显示响应消息，类型为 `Ref<boolean>`
|
||
- `dialog`: 确认框配置，类型为 `Ref<{ status: boolean } & CustomDialogOptions>`
|
||
- `loading`: 是否正在加载，类型为 `Ref<boolean>`
|
||
- `error`: 错误信息，类型为 `ShallowRef<Error | null | string>`
|
||
- `response`: 原始响应对象，类型为 `ShallowRef<AxiosResponse<T> | null>`
|
||
- `data`: 响应数据，类型为 `Ref<T>`
|
||
- `defaultData`: 默认数据，类型为 `Ref<T>`
|
||
- `statusCode`: HTTP 状态码，类型为 `ComputedRef<HttpStatusCode | null>`
|
||
- `aborted`: 是否被中断，类型为 `Ref<boolean>`
|
||
- `urlRef`: 请求 URL，类型为 `Ref<string>`
|
||
- `paramsRef`: 请求参数，类型为 `Ref<Z>`
|
||
|
||
**方法**:
|
||
|
||
- `execute(url: string, params?: Z)`: 执行请求，返回 `Promise<T>`
|
||
- `setParams(params: Z)`: 设置请求参数并执行请求，返回 `Promise<T>`
|
||
- `setUrl(url: string, params?: Z)`: 设置请求 URL 和参数并执行请求，返回 `Promise<T>`
|
||
- `cancel(url: string)`: 取消特定请求
|
||
- `cancelAll()`: 取消所有请求
|
||
- `start(params?: Z)`: 使用当前 URL 和参数重新发起请求，返回 `Promise<T>`
|
||
|
||
## 使用示例
|
||
|
||
### 基本用法
|
||
|
||
```typescript
|
||
import { useAxios, HttpClient } from '@baota/hooks/axios'
|
||
|
||
// 创建 HTTP 客户端实例
|
||
const httpClient = new HttpClient({
|
||
baseURL: 'https://api.example.com',
|
||
})
|
||
|
||
// 创建请求钩子
|
||
const api = useAxios<UserData, UserParams>(httpClient)
|
||
|
||
// 发送请求
|
||
const fetchUser = async (userId: string) => {
|
||
try {
|
||
const result = await api.execute('/user/info', { userId })
|
||
console.log('用户数据:', result)
|
||
return result
|
||
} catch (error) {
|
||
console.error('获取用户数据失败:', error)
|
||
}
|
||
}
|
||
```
|
||
|
||
### 配置加载遮罩
|
||
|
||
```typescript
|
||
import { useAxios, HttpClient } from '@baota/hooks/axios'
|
||
|
||
const httpClient = new HttpClient({
|
||
baseURL: 'https://api.example.com',
|
||
})
|
||
|
||
const api = useAxios(httpClient)
|
||
|
||
// 配置加载遮罩
|
||
api.loadingMask.value = {
|
||
status: true, // 启用加载遮罩
|
||
text: '正在加载数据，请稍候...', // 自定义加载文本
|
||
}
|
||
|
||
// 发送请求时会自动显示加载遮罩
|
||
api.execute('/data/list', { page: 1 })
|
||
```
|
||
|
||
### 配置确认对话框
|
||
|
||
```typescript
|
||
import { useAxios, HttpClient } from '@baota/hooks/axios'
|
||
|
||
const httpClient = new HttpClient({
|
||
baseURL: 'https://api.example.com',
|
||
})
|
||
|
||
const api = useAxios(httpClient)
|
||
|
||
// 配置确认对话框
|
||
api.dialog.value = {
|
||
status: true, // 启用确认对话框
|
||
title: '确认操作',
|
||
content: '确定要执行此操作吗？',
|
||
positiveText: '确定',
|
||
negativeText: '取消',
|
||
}
|
||
|
||
// 发送请求前会先显示确认对话框
|
||
api.execute('/user/delete', { userId: '123' })
|
||
```
|
||
|
||
### 启用响应消息提示
|
||
|
||
```typescript
|
||
import { useAxios, HttpClient } from '@baota/hooks/axios'
|
||
|
||
const httpClient = new HttpClient({
|
||
baseURL: 'https://api.example.com',
|
||
})
|
||
|
||
const api = useAxios(httpClient)
|
||
|
||
// 启用响应消息提示
|
||
api.message.value = true
|
||
|
||
// 发送请求后会自动显示响应中的消息
|
||
// 假设响应格式为 { status: boolean, message: string, data: any }
|
||
api.execute('/user/update', { userId: '123', name: '张三' })
|
||
```
|
||
|
||
### 取消请求
|
||
|
||
```typescript
|
||
import { useAxios, HttpClient } from '@baota/hooks/axios'
|
||
|
||
const httpClient = new HttpClient({
|
||
baseURL: 'https://api.example.com',
|
||
})
|
||
|
||
const api = useAxios(httpClient)
|
||
|
||
// 发送请求
|
||
const fetchData = () => {
|
||
api.execute('/data/large-file')
|
||
}
|
||
|
||
// 取消特定请求
|
||
const cancelFetch = () => {
|
||
api.cancel('/data/large-file')
|
||
}
|
||
|
||
// 取消所有请求
|
||
const cancelAllRequests = () => {
|
||
api.cancelAll()
|
||
}
|
||
```
|
||
|
||
### 重新发送请求
|
||
|
||
```typescript
|
||
import { useAxios, HttpClient } from '@baota/hooks/axios'
|
||
|
||
const httpClient = new HttpClient({
|
||
baseURL: 'https://api.example.com',
|
||
})
|
||
|
||
const api = useAxios(httpClient)
|
||
|
||
// 首次发送请求
|
||
api.execute('/data/list', { page: 1 })
|
||
|
||
// 更新参数并重新发送请求
|
||
const nextPage = () => {
|
||
api.setParams({ page: api.paramsRef.value.page + 1 })
|
||
}
|
||
|
||
// 使用当前参数重新发送请求
|
||
const refresh = () => {
|
||
api.start()
|
||
}
|
||
```
|
||
|
||
### 监听请求状态
|
||
|
||
```typescript
|
||
import { useAxios, HttpClient } from '@baota/hooks/axios'
|
||
import { watch } from 'vue'
|
||
|
||
const httpClient = new HttpClient({
|
||
baseURL: 'https://api.example.com',
|
||
})
|
||
|
||
const api = useAxios(httpClient)
|
||
|
||
// 监听加载状态
|
||
watch(api.loading, (isLoading) => {
|
||
console.log('加载状态:', isLoading)
|
||
})
|
||
|
||
// 监听错误状态
|
||
watch(api.error, (error) => {
|
||
if (error) {
|
||
console.error('请求错误:', error)
|
||
}
|
||
})
|
||
|
||
// 监听响应数据
|
||
watch(api.data, (data) => {
|
||
console.log('响应数据:', data)
|
||
})
|
||
```
|
||
|
||
## 高级用法
|
||
|
||
### 设置默认数据
|
||
|
||
```typescript
|
||
import { useAxios, HttpClient } from '@baota/hooks/axios'
|
||
|
||
const httpClient = new HttpClient({
|
||
baseURL: 'https://api.example.com',
|
||
})
|
||
|
||
const api = useAxios<{ list: any[]; total: number }>(httpClient)
|
||
|
||
// 设置默认数据
|
||
api.defaultData.value = { list: [], total: 0 }
|
||
|
||
// 当请求失败时，data 会被重置为默认数据
|
||
api.execute('/data/list', { page: 1 })
|
||
```
|
||
|
||
### 类型化请求和响应
|
||
|
||
```typescript
|
||
import { useAxios, HttpClient } from '@baota/hooks/axios'
|
||
|
||
// 定义响应数据类型
|
||
interface UserData {
|
||
id: string
|
||
name: string
|
||
email: string
|
||
role: string
|
||
}
|
||
|
||
// 定义请求参数类型
|
||
interface UserParams {
|
||
userId: string
|
||
}
|
||
|
||
const httpClient = new HttpClient({
|
||
baseURL: 'https://api.example.com',
|
||
})
|
||
|
||
// 创建类型化的请求钩子
|
||
const api = useAxios<UserData, UserParams>(httpClient)
|
||
|
||
// 发送类型化的请求
|
||
const fetchUser = async (userId: string) => {
|
||
const user = await api.execute('/user/info', { userId })
|
||
// user 的类型为 UserData
|
||
console.log(`用户名: ${user.name}, 角色: ${user.role}`)
|
||
}
|
||
```
|
||
|
||
## 注意事项
|
||
|
||
1. `useAxios` 默认使用 POST 方法发送请求，如需使用其他 HTTP 方法，需要在 HttpClient 实例中配置。
|
||
|
||
2. 响应消息提示功能要求响应数据格式包含 `status` 和 `message` 字段。
|
||
|
||
3. 加载遮罩、确认对话框和响应消息提示功能依赖于 `@baota/naive-ui/hooks` 提供的相关组件。
|
||
|
||
4. 取消请求功能基于 Axios 的 AbortController 实现，可以通过 URL 来标识和取消特定请求。
|
||
|
||
5. 当请求被取消时，`aborted` 状态会被设置为 `true`，可以通过监听此状态来处理请求取消的情况。
|
||
|
||
6. 错误处理会自动显示错误消息，并将错误信息存储在 `error` 状态中。
|