# request

**Repository Path**: xy_zi/request

## Basic Information

- **Project Name**: request
- **Description**: uniapp vue3 组合式API请求插件
- **Primary Language**: JavaScript
- **License**: ISC
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2022-04-01
- **Last Updated**: 2024-03-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: uni-app, vue3, CompositionApi

## README

# request

* request为uni-app的vue3项目、web的vue3项目中的常规请求插件。
* API为组合式API风格，其中浏览器兼容性同步vue3。
* 支持请求前置执行/后置执行/异常执行/完成执行
* 使用Typescript重构，有更友好的语法提示
* 基础API是默认参数及方法，动态参数及方法动态加载
* 需先创建 createReqeust ，后使用 useRequest

## 文档
### 当前文档

[当前文档](https://gitee.com/xy_zi/request)

### 历史文档

* [2.X文档](https://gitee.com/xy_zi/request/blob/master/version/2.X.md)
* [1.X文档](https://gitee.com/xy_zi/request/blob/master/version/1.X.md)
* [0.X文档](https://gitee.com/xy_zi/request/blob/master/version/0.X.md)

## 入门
### 引入

```sh
npm install @xyzi/request
```

* main.js

```js
import { createRequest } from '@xyzi/request'

createRequest(function(args) {
	// 自定义请求
})
```

### 使用

```html
<script setup>
	import { useRequest } from '@xyzi/request'
	const {
		request, //请求方法
		option, //请求参数reactive
		state, //响应参数ref
		isLoading, //是否请求中ref
		isError, //是否失败ref
	} = useRequest(() => ({
		option: { //请求参数初始化
			url: "/",
			data: {},
		},
		state: [] //响应参数初始化
		isLoading: false //是否请求中初始化
	}))
 </script>
```

### 动态参数

| 名称																						| 描述						| 版本	|
|--																							|--							|--		|
|[lifetime](https://gitee.com/xy_zi/request/blob/master/README_PLUGINS.md#lifetime)			| 执行阶段					| 3.0.0	|
|[debounce](https://gitee.com/xy_zi/request/blob/master/README_PLUGINS.md#debounce)			| 防抖请求					| 3.0.0	|
|[throttle](https://gitee.com/xy_zi/request/blob/master/README_PLUGINS.md#throttle)			| 节流请求					| 3.0.0	|
|[lifecycle](https://gitee.com/xy_zi/request/blob/master/README_PLUGINS.md#lifecycle)		| 生命周期钩子执行请求		| 3.0.0	|
|[watchOption](https://gitee.com/xy_zi/request/blob/master/README_PLUGINS.md#watchoption)	| 监听 option 执行请求		| 3.0.0	|
|[watchtruly](https://gitee.com/xy_zi/request/blob/master/README_PLUGINS.md#watchtruly)		| 监听函数返回值为truly执行	| 3.0.0	|
|[emit](https://gitee.com/xy_zi/request/blob/master/README_PLUGINS.md#emit)					| 发布订阅请求				| 3.0.0	|
|[loop](https://gitee.com/xy_zi/request/blob/master/README_PLUGINS.md#loop)					| 轮询请求					| 3.0.0	|
|[retry](https://gitee.com/xy_zi/request/blob/master/README_PLUGINS.md#retry)				| 错误重试请求				| 3.0.0	|
|[extra](https://gitee.com/xy_zi/request/blob/master/README_PLUGINS.md#extra)				| 自定义参数、方法			| 3.0.0	|
|[getters](https://gitee.com/xy_zi/request/blob/master/README_PLUGINS.md#getters)			| 计算属性					| 3.0.0	|
|[initOptions](https://gitee.com/xy_zi/request/blob/master/README_PLUGINS.md#initoptions)	| 初始化参数					| 3.0.0	|
|[storage](https://gitee.com/xy_zi/request/blob/master/README_PLUGINS.md#storage)			| 持久化参数					| 3.1.0	|
|[emitData](https://gitee.com/xy_zi/request/blob/master/README_PLUGINS.md#emitdata)			| 发布订阅 option.data		| 3.1.0	|

## 其他
### uniapp

* createRequest

```js
createRequest((args) => new Promise((success, fail) => uni.request(Object.assign(args, { success, fail }))))
createRequest('upload', (args) => new Promise((success, fail) => uni.uploadFile(Object.assign(args, { success, fail }))))
```

### axios

* createRequest

```js
createRequest((args) => axios(args))
```

# 基础API
## createRequest
### 基础

初始化主函数

```js
createReqeust(func): {setting}
createRequest(name, func): {setting}
```

#### 参数

* name：主函数名称，默认 undefined
* func：主函数

### 说明
#### name

* 可声明多个主函数，通过[name](#name)加以区分，在[defineRequest](#definerequest)的【name】属性区分调用
* 需要使用 [defineRequest](#definerequest) 显示声明出的 useRequest 

```js
// 第一步
createRequest('upload', function(args) {})
// 第二步
const useUpload = defineRequest('upload', () => ({}))
// 第三步
const {	request } = useUpload(() => ({}))
```

#### setting

主要是扩展或修改全局参数

* lifecycle

扩展 lifecycle 钩子, 扩展的钩子可以在 defineRequest/useRequest 参数 [lifecycle](https://gitee.com/xy_zi/request/blob/master/README_PLUGINS.md#lifecycle) 中使用

```js
import { createReqeust, useReqeust} from '@xyzi/request'
import { onPullDownRefresh,	onReachBottom, onShow } from '@dcloudio/uni-app'
const request = createReqeust(function(){ })
request.setting('lifecycle', { onPullDownRefresh, onReachBottom, onShow })
useRequest(()=>({
	lifecycle: {
		onPullDownRefresh...
		onReachBottom...
		onShow...
	}
}))
```



## defineRequest
### 基础

声明 useRequest 函数

```js
defineRequest(() => options): useRequest
defineRequest(name, () => options): useRequest
```

#### 参数

* name：使用的 createRequest 主函数名称，默认 undefined
* options：当前 useRequest 默认参数，参数结构同 [useRequest](#userequest) 

#### 返回值

* useRequest 函数

### 说明
#### 默认 useRequest

默认 useRequest 是一个使用默认主函数、没有任何默认参数的 defineRequest 返回函数。

```js
import { useRequest } from '@xyzi/request'
```

#### 自定义 useRequest

通过 defineRequest 可自定义 useRequest 函数，自定义 useRequest 可指定默认参数。

**使用时实际参数优先级大于自定义默认参数**

```js
import { defineRequest } from '@xyzi/request'
const useRequest = defineRequest(() => ({ }))	// 自定义默认参数
const { request } = useRequest(() => ({ }))		// 使用时实际参数
```

## useRequest
### 基础
#### 参数

* option：请求参数初始值，默认 {}
* state：响应参数初始值
* isLoading：是否加载中初始值，默认 false

#### 返回值

* option：请求参数
* request：请求方法
* state：响应参数
* isLoading：是否请求中
* isError：是否请求失败