allinssl/frontend/packages/vue/hooks/docs/useAxios.md

useAxios 使用文档

基本介绍

useAxios 是一个基于 Vue 3 的 Axios 封装钩子函数，它提供了一种简洁的方式来管理 HTTP 请求。通过这个钩子函数，你可以轻松地处理请求状态、加载状态、错误处理、请求取消等功能。

核心函数

useAxios

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>

使用示例

基本用法

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)
	}
}

配置加载遮罩

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 })

配置确认对话框

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' })

启用响应消息提示

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: '张三' })

取消请求

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()
}

重新发送请求

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()
}

监听请求状态

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)
})

高级用法

设置默认数据

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 })

类型化请求和响应

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 状态中。