@gmcb/uv-ui 0.2.27 → 0.3.1

package/docs/api/request/http.md

@@ -0,0 +1,451 @@
+# 使用该功能前，请按照[扩展配置](https://www.uvui.cn/components/setting.html)进行配置后即可正常使用。
+
+## 示例项目
+
+#### `uv-ui` 项目中有相关使用的代码，可以下载示例进行查看：[https://ext.dcloud.net.cn/plugin?id=12287](https://ext.dcloud.net.cn/plugin?id=12287)
+
+## Http请求
+
+**如果你已经很熟悉相关介绍，可以直接到实践中查看：[实践](/api/request/http.html#实践)**
+
+该插件适用于普遍的请求场景，支持`post`、`get`、`put`和`delete`，以及上传下载等请求，有如下特点：
+- 基于`Promise`对象实现更简单的`request`使用方式，支持请求和响应拦截
+- 支持全局挂载
+- 支持多个全局配置实例
+- 支持自定义验证器
+- 支持文件上传/下载
+- 支持task 操作
+- 支持自定义参数
+- 支持多拦截器
+- 对参数的处理比`uni.request`更强
+
+### 平台差异说明
+
+|App|H5|微信小程序|支付宝小程序|百度小程序|头条小程序|QQ小程序|
+|:-:|:-:|:-:|:-:|:-:|:-:|:-:|
+|√|√|√|√|√|√|√|
+
+:::tip 说明
+此插件集成自优秀的开源请求库：[luch-request](https://www.quanzhan.co/luch-request/)。uv-ui对其进行了简单封装以及说明，如有不全之处，
+可参考[luch-request](https://www.quanzhan.co/luch-request/)官方文档。
+:::
+
+### 基本使用
+
+```js
+uni.$uv.http.middleware(config)
+uni.$uv.http.request(config)
+uni.$uv.http.get(url[, config])
+uni.$uv.http.upload(url[, config])
+uni.$uv.http.delete(url[, data[, config]])
+uni.$uv.http.head(url[, data[, config]])
+uni.$uv.http.post(url[, data[, config]])
+uni.$uv.http.put(url[, data[, config]])
+uni.$uv.http.connect(url[, data[, config]])
+uni.$uv.http.options(url[, data[, config]])
+uni.$uv.http.trace(url[, data[, config]])
+```
+
+### 全局配置
+可选的配置项有如下：
+```js
+{
+    baseURL: '',
+    header: {},
+    method: 'GET',
+    dataType: 'json',
+    // #ifndef MP-ALIPAY
+    responseType: 'text',
+    // #endif
+    // 注：如果局部custom与全局custom有同名属性，则后面的属性会覆盖前面的属性，相当于Object.assign(全局，局部)
+    custom: {}, // 全局自定义参数默认值
+    // #ifdef H5 || APP-PLUS || MP-ALIPAY || MP-WEIXIN
+    timeout: 60000,
+    // #endif
+    // #ifdef APP-PLUS
+    sslVerify: true,
+    // #endif
+    // #ifdef H5
+    // 跨域请求时是否携带凭证（cookies）仅H5支持（HBuilderX 2.6.15+）
+    withCredentials: false,
+    // #endif
+    // #ifdef APP-PLUS
+    firstIpv4: false, // DNS解析时优先使用ipv4 仅 App-Android 支持 (HBuilderX 2.8.0+)
+    // #endif
+    // 局部优先级高于全局，返回当前请求的task,options。请勿在此处修改options。非必填
+    // getTask: (task, options) => {
+    // 相当于设置了请求超时时间500ms
+    //   setTimeout(() => {
+    //     task.abort()
+    //   }, 500)
+    // },
+    // 全局自定义验证器。参数为statusCode 且必存在，不用判断空情况。
+    validateStatus: (statusCode) => { // statusCode 必存在。此处示例为全局默认配置
+        return statusCode >= 200 && statusCode < 300
+    }
+}
+```
+
+可以通过`uni.$uv.http.setConfig()`方法进行全局配置，比如配置请求的全局域名`baseUrl`：
+```js
+uni.$uv.http.setConfig((config) => {
+    /* config 为默认全局配置*/
+    config.baseURL = `https://www.example.com`; /* 根域名 */
+    return config
+})
+```
+
+
+### GET请求
+
+需要注意的是，`get`请求与`post`请求略有不同，`get`请求所有参数都在方法的第二个参数中，而`post`请求的第二个参数为请求参数`params`，而第三个参数才为配置项。
+```js
+// 基本用法，注意：get请求的参数以及配置项都在第二个参数中
+uni.$uv.http.get('/user/login', {params: {userName: 'name', password: '123456'}}).then(res => {
+
+}).catch(err => {
+
+})
+
+// 局部修改配置，局部配置优先级高于全局配置
+uni.$uv.http.get('/user/login', {
+    params: {userName: 'name', password: '123456'}, /* 会加在url上 */
+    header: {}, /* 会与全局header合并，如有同名属性，局部覆盖全局 */
+    dataType: 'json',
+    // 注：如果局部custom与全局custom有同名属性，则后面的属性会覆盖前面的属性，相当于Object.assign(全局，局部)
+    custom: {auth: true}, // 可以加一些自定义参数，在拦截器等地方使用。比如这里我加了一个auth，可在拦截器里拿到，如果true就传token
+    // #ifndef MP-ALIPAY
+    responseType: 'text',
+    // #endif
+    // #ifdef H5 || APP-PLUS || MP-ALIPAY || MP-WEIXIN
+    timeout: 60000, // H5(HBuilderX 2.9.9+)、APP(HBuilderX 2.9.9+)、微信小程序（2.10.0）、支付宝小程序
+    // #endif
+    // #ifdef APP-PLUS
+    sslVerify: true, // 验证 ssl 证书 仅5+App安卓端支持（HBuilderX 2.3.3+）
+    // #endif
+    // #ifdef APP-PLUS
+    firstIpv4: false, // DNS解析时优先使用ipv4 仅 App-Android 支持 (HBuilderX 2.8.0+)
+    // #endif
+    // #ifdef H5
+    withCredentials: false, // 跨域请求时是否携带凭证（cookies）仅H5支持（HBuilderX 2.6.15+）
+    // #endif
+    // 返回当前请求的task, options。请勿在此处修改options。非必填
+    getTask: (task, options) => {
+         // 相当于设置超时时间500ms
+         // setTimeout(() => {
+         //   task.abort()
+         // }, 500)
+    },
+    //validateStatus: (statusCode) => { // statusCode 必存在。此处示例为全局默认配置。演示，非必填选项
+	//	return statusCode >= 200 && statusCode < 300
+	//}
+}).then(res => {
+
+}).catch(err => {
+
+})
+```
+
+
+### POST请求
+
+需要注意的是，get请求与post请求略有不同，get请求所有参数都在方法的第二个参数中，而post请求的第二个参数为请求参数params，而第三个参数才为配置项。
+
+```js
+// 基本用法，注意：post的第三个参数才为配置项
+uni.$uv.http.post('/user/login', {userName: 'name', password: '123456'} ).then(res => {
+
+}).catch(err => {
+
+})
+
+// 局部修改配置，局部配置优先级高于全局配置
+uni.$uv.http.post('/user/login', {userName: 'name', password: '123456'}, {
+    params: {}, /* 会加在url上 */
+    header: {}, /* 会与全局header合并，如有同名属性，局部覆盖全局 */
+    dataType: 'json',
+    // 注：如果局部custom与全局custom有同名属性，则后面的属性会覆盖前面的属性，相当于Object.assign(全局，局部)
+    custom: {auth: true}, // 可以加一些自定义参数，在拦截器等地方使用。比如这里我加了一个auth，可在拦截器里拿到，如果true就传token
+    // #ifndef MP-ALIPAY
+    responseType: 'text',
+    // #endif
+    // #ifdef H5 || APP-PLUS || MP-ALIPAY || MP-WEIXIN
+    timeout: 60000, // H5(HBuilderX 2.9.9+)、APP(HBuilderX 2.9.9+)、微信小程序（2.10.0）、支付宝小程序
+    // #endif
+    // #ifdef APP-PLUS
+    sslVerify: true, // 验证 ssl 证书 仅5+App安卓端支持（HBuilderX 2.3.3+）
+    // #endif
+   // #ifdef APP-PLUS
+    firstIpv4: false, // DNS解析时优先使用ipv4 仅 App-Android 支持 (HBuilderX 2.8.0+)
+    // #endif
+    // #ifdef H5
+    withCredentials: false, // 跨域请求时是否携带凭证（cookies）仅H5支持（HBuilderX 2.6.15+）
+    // #endif
+    // 返回当前请求的task, options。请勿在此处修改options。非必填
+    getTask: (task, options) => {
+         // 相当于设置超时时间500ms
+         // setTimeout(() => {
+         //   task.abort()
+         // }, 500)
+    },
+    //validateStatus: (statusCode) => { // statusCode 必存在。此处示例为全局默认配置。演示，非必填选项
+  	//	return statusCode >= 200 && statusCode < 300
+  	//}
+}).then(res => {
+
+}).catch(err => {
+
+})
+```
+
+
+### UPLOAD请求
+
+具体参数说明：[uni.uploadFile](https://uniapp.dcloud.io/api/request/network-file)
+
+```js
+uni.$uv.http.upload('api/upload/img', {
+    params: {}, /* 会加在url上 */
+    // #ifdef APP-PLUS || H5
+    files: [], // 需要上传的文件列表。使用 files 时，filePath 和 name 不生效。App、H5（ 2.6.15+）
+    // #endif
+    // #ifdef MP-ALIPAY
+    fileType: 'image/video/audio', // 仅支付宝小程序，且必填。
+    // #endif
+    filePath: '', // 要上传文件资源的路径。
+    // 注：如果局部custom与全局custom有同名属性，则后面的属性会覆盖前面的属性，相当于Object.assign(全局，局部)
+    custom: {auth: true}, // 可以加一些自定义参数，在拦截器等地方使用。比如这里我加了一个auth，可在拦截器里拿到，如果true就传token
+    name: 'file', // 文件对应的 key , 开发者在服务器端通过这个 key 可以获取到文件二进制内容
+    // #ifdef H5 || APP-PLUS
+    timeout: 60000, // H5(HBuilderX 2.9.9+)、APP(HBuilderX 2.9.9+)
+    // #endif
+    header: {},  /* 会与全局header合并，如有同名属性，局部覆盖全局 */
+    formData: {}, // HTTP 请求中其他额外的 form data
+    // 返回当前请求的task, options。请勿在此处修改options。非必填
+    getTask: (task, options) => {
+      // task.onProgressUpdate((res) => {
+      //   console.log('上传进度' + res.progress);
+      //   console.log('已经上传的数据长度' + res.totalBytesSent);
+      //   console.log('预期需要上传的数据总长度' + res.totalBytesExpectedToSend);
+      //
+      //   // 测试条件，取消上传任务。
+      //   if (res.progress > 50) {
+      //     uploadTask.abort();
+      //   }
+      // });
+    },
+    //validateStatus: (statusCode) => { // statusCode 必存在。此处示例为全局默认配置。演示，非必填选项
+    //	return statusCode >= 200 && statusCode < 300
+    //}
+}).then(res => {
+	// 返回的res.data 已经进行JSON.parse
+}).catch(err => {
+
+})
+```
+
+
+### DOWNLOAD请求
+
+具体参数说明：[uni.downloadFile](https://uniapp.dcloud.io/api/request/network-file?id=downloadfile)
+
+```js
+uni.$uv.http.download('api/download', {
+    params: {}, /* 会加在url上 */
+    // #ifdef H5 || APP-PLUS
+    timeout: 3000, // H5(HBuilderX 2.9.9+)、APP(HBuilderX 2.9.9+)
+    // #endif
+    header: {}, /* 会与全局header合并，如有同名属性，局部覆盖全局 */
+    custom: {}, // 自定义参数
+    // 返回当前请求的task, options。非必填
+    getTask: (task, options) => {
+		// setTimeout(() => {
+		//   task.abort()
+		// }, 500)
+    },
+    //validateStatus: (statusCode) => { // statusCode 必存在。此处示例为全局默认配置。演示，非必填选项
+   	//	return statusCode >= 200 && statusCode < 300
+   	//}
+}).then(res => {
+
+}).catch(err => {
+
+})
+```
+
+
+### 请求拦截器
+
+```js
+uni.$uv.http.interceptors.request.use((config) => { // 可使用async await 做异步操作
+	config.header = {
+		...config.header,
+		a: 1 // 演示拦截器header加参
+	}
+	// 演示custom 用处
+	// if (config.custom.auth) {
+	//   config.header.token = 'token'
+	// }
+	// if (config.custom.loading) {
+	//  uni.showLoading()
+	// }
+	// 演示
+	// if (!token) { // 如果token不存在，return Promise.reject(config) 会取消本次请求
+	// 	return Promise.reject(config)
+	// }
+	return config
+}, config => { // 可使用async await 做异步操作
+	return Promise.reject(config)
+})
+```
+
+### 响应拦截器
+
+```js
+uni.$uv.http.interceptors.response.use((response) => {
+	/* 对响应成功做点什么 可使用async await 做异步操作*/
+	// if (response.data.code !== 200) { // 服务端返回的状态码不等于200，则reject()
+	//    	return Promise.reject(response) // return Promise.reject 可使promise状态进入catch
+	// if (response.config.custom.verification) { // 演示自定义参数的作用
+	//   	return response.data
+	// }
+	console.log(response)
+	return response
+}, (response) => {
+	/*  对响应错误做点什么 （statusCode !== 200）*/
+	console.log(response)
+	return Promise.reject(response)
+})
+```
+
+
+### 实践
+
+:::tip 提示
+uv-ui的请求相关完整示例，可以下载示例项目查看，请求和响应拦截器在`util/request`目录下，是单独的js文件`requestInterceptors.js`和`responseInterceptors.js`，请求和响应后的扩展逻辑可以在相应文件里面添加。
+:::
+
+假设我们项目中需要用到请求和响应拦截器，并且在请求拦截器中需要调用`vuex`中的变量，可按如下步骤进行操作(仅供参考)：
+
+#### 1. 全局配置，以及请求，响应拦截器定义
+
+在`/utils/request/index.js`中，写入如下内容：
+```js
+import store from '@/store';
+
+export const Request = () => {
+    // 初始化请求配置
+    uni.$uv.http.setConfig((config) => {
+        /* config 为默认全局配置*/
+        config.baseURL = 'https://www.example.com'; /* 根域名 */
+        return config
+    })
+	
+	// 请求拦截
+	uni.$uv.http.interceptors.request.use((config) => { // 可使用async await 做异步操作
+	    // 初始化请求拦截器时，会执行此方法，此时data为undefined，赋予默认{}
+	    config.data = config.data || {}
+		// 根据custom参数中配置的是否需要token，添加对应的请求头
+		if(config?.custom?.auth) {
+			config.header.token = store.state.userInfo.token
+		}
+	    return config 
+	}, config => { // 可使用async await 做异步操作
+	    return Promise.reject(config)
+	})
+	
+	// 响应拦截
+	uni.$uv.http.interceptors.response.use((response) => { /* 对响应成功做点什么 可使用async await 做异步操作*/
+		const data = response.data
+
+		// 自定义参数
+		const custom = response.config?.custom
+		if (data.code !== 200) { 
+			// 如果没有显式定义custom的toast参数为false的话，默认对报错进行toast弹出提示
+			if (custom.toast !== false) {
+				uni.$uv.toast(data.message)
+			}
+
+			// 如果需要catch返回，则进行reject
+			if (custom?.catch) {
+				return Promise.reject(data)
+			} else {
+				// 否则返回一个pending中的promise，请求不会进入catch中
+				return new Promise(() => { })
+			}
+		}
+		return data.data === undefined ? {} : data.data
+	}, (response) => { 
+		// 对响应错误做点什么 （statusCode !== 200）
+		return Promise.reject(response)
+	})
+}
+```
+
+
+#### 2. 引用配置
+
+我们可以在 `main.js` 中引用 `/utils/request/index.js`。Vue 3 项目中，在 `createSSRApp(App)` 并注册 `uvUI` 后初始化请求封装：
+
+```js
+import App from './App'
+import { createSSRApp } from 'vue'
+import uvUI from '@gmcb/uv-ui'
+import { Request } from '@/utils/request/index'
+
+export function createApp() {
+	const app = createSSRApp(App)
+	app.use(uvUI)
+	Request(app)
+	return {
+		app
+	}
+}
+```
+
+#### 3. Api集中管理
+
+在`/common/api.js`中编写请求接口：
+
+```js
+// post请求，获取菜单
+export const postMenu = (params, config = {}) => uni.$uv.http.post('/ebapi/public_api/index', params, config)
+
+// get请求，获取菜单，注意：get请求的配置等，都在第二个参数中，详见前面解释
+export const getMenu = (data) => uni.$uv.http.get('/ebapi/public_api/index', data)
+```
+
+#### 4. 发送请求
+
+```js
+import { postMenu, getMenu } from '/config/api.js';
+
+// 发出post，假设需要带上token
+postMenu({ custom: { auth: true }}).then(() => {
+	
+}).catch(() =>{
+	
+})
+
+// await等待，注意与async结合使用
+await postMenu({ custom: { auth: true }})
+
+// 假设不需要在响应拦截器中自动弹出的toast，以及不想写catch(如果promise中进行reject，但是却没有catch的话会报错)
+postMenu({ custom: { auth: true, toast: false, catch: false }}).then(() => {
+	
+})
+
+// get请求
+getMenu({ custom: { auth: true }}).then(() => {
+	
+}).catch(() =>{
+	
+})
+
+// 也可以直接通过uni.$uv.post发出请求，注意此处需要写上接口地址
+uni.$uv.http.post('/common/menu', { custom: { auth: true }}).then(() => {
+	
+}).catch(() =>{
+	
+})
+```

package/docs/api/utils/colorSwitch.md

@@ -0,0 +1,78 @@
+## 颜色转换
+
+### 按需引入
+
+如果未做全局[扩展配置](https://www.uvui.cn/components/setting.html)，可以按需引入：
+
+```js
+// 引入
+import { rgbToHex, hexToRgb, colorGradient } from '@gmcb/uv-ui/libs/function/colorGradient.js';
+```
+
+### rgbToHex(rgb)  
+
+RGB转十六进制Hex，该函数可以将一个RGB颜色值转换成一个Hex的十六进制颜色值
+
+- `rgb` <String\> RGB颜色值，如`rgb(230, 231, 233)`
+
+```vue
+<script setup>
+import { onLoad } from '@dcloudio/uni-app';
+
+onLoad(() => {
+	console.log(uni.$uv.rgbToHex('rgb(13, 145, 20)'));
+});
+</script>
+```
+
+### hexToRgb(hex)
+
+十六进制Hex转RGB，该函数可以将一个Hex的十六进制颜色值转换成一个RGB颜色值
+
+- `hex` <String\> HEx颜色值，如`#0afdce`
+
+```vue
+<script setup>
+import { onLoad } from '@dcloudio/uni-app';
+
+onLoad(() => {
+	console.log(uni.$uv.hexToRgb('#0afdce'));
+});
+</script>
+```
+
+### colorGradient(startColor, endColor, step) 
+
+颜色渐变。该函数实现两个颜色值之间等分取值，返回一个数组，元素为十六进制形式的颜色值，数组长度为`step`值。 
+例如：colorGradient('rgb(250, 250, 250)', 'rgb(252, 252, 252)', 3)，得到的结果为["#fafafa", "#fafafa", "#fbfbfb"]
+
+- `startColor` <String\> 开始颜色值，可以是HEX或者RGB颜色值，如`#0afdce`或者`rgb(120, 130, 150)`
+- `endColor` <String\> 结束颜色值，可以是HEX或者RGB颜色值，如`#0afdce`或者`rgb(120, 130, 150)`
+- `step` <Number\> 均分值，把开始值和结束值平均分成多少份
+
+```vue
+<script setup>
+import { onLoad } from '@dcloudio/uni-app';
+
+onLoad(() => {
+	console.log(uni.$uv.colorGradient('rgb(250,250,250)', 'rgb(252,252,252)', 3));
+	// 结果为：["#fafafa", "#fafafa", "#fbfbfb"]
+});
+</script>
+```
+
+### colorToRgba(color, opacity = 0.3) 
+
+颜色透明度。该函数可以接受一个`十六进制`或者`rgb`格式的颜色值(不能接受命名式颜色格式，比如`white`)，返回此颜色的`rgba`格式值，如下：
+
+- `color` <String\> 颜色值，只能`hex`或者`rgba`格式
+- `opacity` <Number\> 不透明度值，取值为0-1之间
+
+
+```js
+uni.$uv.colorToRgba('#000000', 0.35);
+// 结果为 rgba(0, 0, 0, 0.35)
+
+uni.$uv.colorToRgba('rgb(255, 180, 0)', 0.4);
+// 结果为 rgba(255, 180, 0, 0.4)
+```

package/docs/api/utils/debounce.md

@@ -0,0 +1,104 @@
+## throttle & debounce节流防抖
+
+### 按需引入
+
+如果未做全局[扩展配置](https://www.uvui.cn/components/setting.html)，可以按需引入：
+
+#### 节流
+
+```js
+// 引入
+import throttle from '@gmcb/uv-ui/libs/function/throttle.js';
+// 调用
+throttle(()=>{
+	console.log('执行')
+})
+```
+
+#### 防抖
+
+```js
+// 引入
+import debounce from '@gmcb/uv-ui/libs/function/debounce.js';
+// 调用
+debounce(()=>{
+	console.log('执行')
+})
+```
+
+### 何谓节流和防抖？
+
+- 节流  
+节流的意思是，规定时间内，只触发一次。比如我们设定500ms，在这个时间内，无论点击按钮多少次，它都只会触发一次。具体场景可以是抢购时候，由于有无数人
+快速点击按钮，如果每次点击都发送请求，就会给服务器造成巨大的压力，但是我们进行节流后，就会大大减少请求的次数。
+
+- 防抖  
+防抖的意思是，在连续的操作中，无论进行了多长时间，只有某一次的操作后在指定的时间内没有再操作，这一次才被判定有效。具体场景可以搜索框输入关键字过程中实时
+请求服务器匹配搜索结果，如果不进行处理，那么就是输入框内容一直变化，导致一直发送请求。如果进行防抖处理，结果就是当我们输入内容完成后，一定时间(比如500ms)没有再
+输入内容，这时再触发请求。
+
+结合以上两种情况，回到我们最实际的场景，比如防止表单提交按钮被多次触发，我们应该选择使用`节流`而不是`防抖`方案。
+
+:::tip 温馨提示
+uv-ui内置的按钮组件`uv-button`内部已做节流处理，无需外部再做节流处理。配置`throttle-time`参数，可以设置节流的时间，详见[Button 按钮](/components/button.html)
+:::
+
+### 节流
+
+#### throttle(func, wait = 500, immediate = true)
+
+规定时间内，只触发一次，可以通过设置`immediate`来决定触发的时机在这个时间的开始，还是结束的时候执行。
+
+- `func` <Function\> 触发回调执行的函数
+- `wait` <Number\> 时间间隔，单位ms
+- `immediate` <Boolean\> 在开始还是结束处触发，比如设置`wait`为1000ms，如果在一秒内进行了5次操作，只触发一次，如果`immediate`为`true`，那么就会在第一次操作
+触发回调，如果为`false`，就会在第5次操作触发回调。
+
+
+```vue
+<template>
+	<view>
+		<button @click="btnClick">对酒当歌</button>
+	</view>
+</template>
+<script setup>
+function btnClick() {
+  uni.$uv.throttle(toNext, 500);
+}
+function toNext() {
+  console.log('btnBClick');
+}
+
+</script>
+```
+
+
+
+### 防抖
+
+#### debounce(func, wait = 500, immediate = false)
+
+在连续的操作中，无论进行了多长时间，只有某一次的操作后在指定的时间内没有再操作，这一次才被判定有效
+
+- `func` <Function\> 触发回调执行的函数
+- `wait` <Number\> 时间间隔，单位ms
+- `immediate` <Number\> 在开始还是结束处触发，如非特殊情况，一般默认为`false`即可
+
+
+```vue
+<template>
+	<view>
+		<button @click="btnClick">对酒当歌</button>
+	</view>
+</template>
+<script setup>
+function btnClick() {
+  uni.$uv.debounce(toNext, 500);
+}
+function toNext() {
+  console.log('btnBClick');
+}
+
+</script>
+
+```