@gmcb/uv-ui 0.2.27 → 0.3.1

package/docs/api/utils/object.md

@@ -0,0 +1,171 @@
+## 对象操作
+
+### 按需引入
+
+如果未做全局[扩展配置](https://www.uvui.cn/components/setting.html)，可以按需引入：
+
+```js
+import { deepClone, deepMerge, getProperty } from '@gmcb/uv-ui/libs/function/index.js';
+```
+
+:::tip 注意
+由于JS对象包括的范围非常广，加上ES6又有众多的新特性，很难、也没必要做到囊括所有的类型和情况，这里说的"对象"，指的是普通的对象，不包括修改对象原型链，
+或者为"Function"，"Promise"等的情况，请留意。
+:::
+
+<br>
+
+### 对象深度克隆
+
+场景：  
+
+- 我们平时可能会遇到需要通过`console.log`打印一个对象，至执行打印的时刻，此对象为空，后面的逻辑中对此对象进行了修改赋值，但是我们在控制台直接看到的打印结果
+却是修改后的值，这让人匪夷所思，虽然我们可以通过`console.log(JSON.parse(JSON.stringify(object)))`的形式处理，但是需要写这长长的一串，难免让人心生抵触。
+
+- 当我们将一个对象(变量A)赋值给另一个变量(变量B)时，修改变量B，因为对象引用的特性，导致A也同时被修改，所以有时候我们需要将A克隆给B，这样修改B的时候，就不会
+导致A也被修改。
+
+### deepClone(object = {})
+
+- `object` <Object\> 需要被克隆的对象
+
+```js
+let a = {
+	name: 'mary'
+};
+
+// 直接赋值，为对象引用，即修改b等于修改a，因为a和b为同一个值
+let b = a;
+
+b.name = 'juli';
+console.log(b); // 结果为 {name: 'juli'}
+console.log(a); // 结果为 {name: 'juli'}
+
+
+// 深度克隆
+let b = uni.$uv.deepClone(a);
+
+b.name = 'juli';
+console.log(b); // 结果为 {name: 'juli'}
+console.log(a); // 结果为 {name: 'mary'}
+```
+
+
+### 对象深度合并
+
+在ES6中，我们可以很方便的使用`Object.assign`进行对象合并，但这只是浅层的合并，如果对象的属性为数组或者对象的时候，会导致属性内部的值丢失。
+  
+**注意：** 此处合并不同于`Object.assign`，因为`Object.assign(a, b)`会修改`a`的值为最终的结果(这往往不是我们所期望的)，但是`deepMerge(a, b)`并不会修改`a`的值。
+
+
+### deepMerge(target = {}, source = {})
+
+- `target` <Object\> 目标对象
+- `source` <Object\> 源对象
+
+`Object.assign`浅合并示例：
+
+```js
+let a = {
+	info: {
+		name: 'mary'
+	}
+}
+
+let b = {
+	info: {
+		age: '22'
+	}
+}
+
+// 使用Object.assign进行合并，注意此时a被修改了
+let c = Object.assign(a, b);
+
+// 我们期望的结果为：
+c = {
+	info: {
+		name: 'mary',
+		age: '22'
+	}
+}
+
+// 事实上，我们得到的结果却为：
+c = {
+	info: {
+		age: '22'
+	}
+}
+```
+
+深度合并示例：
+
+```js
+let a = {
+	info: {
+		name: 'mary'
+	}
+}
+
+let b = {
+	info: {
+		age: '22'
+	}
+}
+
+let c = uni.$uv.deepMerge(a, b);
+
+// c为我们期望的结果
+c = {
+	info: {
+		age: '22',
+		name: 'mary'
+	}
+}
+```
+
+
+### 链式读取对象属性
+
+读取属性时，我们需要从一个`对象`中进行操作，否则就会引起报错，因此uv-ui提供了一个链式属性的读取方式。  
+当然，我们也可以使用`可选链操作符`的形式去获取；如果需要兼容模板编译限制，推荐使用本工具方法统一处理。
+
+### getProperty(object, key)
+
+```js
+// 假设有如下一个对象
+const object = {
+	userInfo: {
+		address: {
+			province: '深圳'
+		}
+	}
+}
+
+// 可以通过如下写法获取province属性
+uni.$uv.getProperty(object, 'userInfo.address.province')
+
+// 可选链操作符形式
+console.log(object?.userInfo?.address?.province)
+```
+
+
+### 链式设置对象属性
+
+设置属性时，我们需要从一个`对象`中进行操作，否则就会引起报错，因此uv-ui提供了一个链式属性的设置方式。
+
+```js
+// 设置一个空对象
+const object = {}
+
+// 链式设置属性
+uni.$uv.setProperty(object, 'userInfo.address.province')
+
+// object将会变成如下对象：
+{
+	userInfo: {
+		address: {
+			province: '深圳'
+		}
+	}
+}
+```

package/docs/api/utils/queryParams.md

@@ -0,0 +1,68 @@
+## 对象转URL参数
+
+该方法，可以将一个对象形式参数转换成`get`传参所需参数形式，如把`{name: 'uvui', age: 1}`转换成`?name=uvui&age=1`  
+用途：可以用于`uni.navigateTo`接口传参等场景，无需自己手动拼接`URL`参数
+
+### 按需引入
+
+如果未做全局[扩展配置](https://www.uvui.cn/components/setting.html)，可以按需引入：
+
+```js
+// 引入
+import { queryParams } from '@gmcb/uv-ui/libs/function/index.js';
+// 调用
+queryParams(...);
+```
+
+### queryParams(data, isPrefix = true, arrayFormat = 'brackets')
+
+- `data` <Object\> 对象值，如`{name: 'uvui', age: 1}`  
+- `isPrefix` <Boolean\> 是否在返回的字符串前加上"?"，默认为`true`
+- `arrayFormat` <Boolean\> 属性为数组的情况下的处理办法，默认为`brackets`，见后面[arrayFormat参数说明](/api/utils/queryParams.html#arrayformat参数说明)
+
+```vue
+<script setup>
+import { onLoad } from '@dcloudio/uni-app';
+
+const data = {
+	name: 'uvui',
+	age: 1
+};
+
+onLoad(() => {
+	console.log(uni.$uv.queryParams(data)); // 结果为：?name=uvui&age=1
+});
+
+</script>
+```
+
+#### arrayFormat参数说明
+ 
+如果您传入的`data`对象内部某些属性值为数组的情况下，您可能需要留意这个参数的配置：   
+该参数可选值有4个：`indices`，`brackets`，`repeat`，`comma`，具体效果请见下方的注释说明
+
+```vue
+<script setup>
+import { onLoad } from '@dcloudio/uni-app';
+
+const data = {
+	name: '冷月夜',
+	fruits: ['apple', 'banana', 'orange']
+};
+
+onLoad(() => {
+	uni.$uv.queryParams(data, true, 'indices');
+	// 结果为：?name=冷月夜&fruits[0]=apple&fruits[1]=banana&fruits[2]=orange
+
+	uni.$uv.queryParams(data, true, 'brackets');
+	// 结果为：?name=冷月夜&fruits[]=apple&fruits[]=banana&fruits[]=orange
+
+	uni.$uv.queryParams(data, true, 'repeat');
+	// 结果为：?name=冷月夜&fruits=apple&fruits=banana&fruits=orange
+
+	uni.$uv.queryParams(data, true, 'comma');
+	// 结果为：?name=冷月夜&fruits=apple,banana,orange
+});
+
+</script>
+```

package/docs/api/utils/random.md

@@ -0,0 +1,23 @@
+## 随机数值
+
+### 按需引入
+
+如果未做全局[扩展配置](https://www.uvui.cn/components/setting.html)，可以按需引入：
+
+```js
+// 引入，实例中未写完，自己根据需求写
+import { random } from '@gmcb/uv-ui/libs/function/test.js';
+// 调用
+random(1,100);
+```
+
+### random(min, max)
+
+该方法可以返回在 `min` 和 `max` 之间的数值，要求 `min` 和 `max` 都为数值，且 `max` 大于或等于 `min`，否则返回0.
+
+- `min` <Number\> 最小值，最小值可以等于该值
+- `max` <Number\> 最大值，最大值可以等于该值
+
+```js
+console.log(uni.$uv.random(1, 3));
+```

package/docs/api/utils/randomArray.md

@@ -0,0 +1,28 @@
+## randomArray 数组乱序
+
+### 按需引入
+
+如果未做全局[扩展配置](https://www.uvui.cn/components/setting.html)，可以按需引入：
+
+```js
+// 引入
+import { randomArray } from '@gmcb/uv-ui/libs/function/index.js';
+// 调用
+randomArray(...);
+```
+
+### randomArray(Array)
+
+该函数可以打乱一维数组元素的顺序，这是随机过程：
+
+- `array` <Array\> 一维数组
+
+```vue
+<script setup>
+import { onLoad } from "@dcloudio/uni-app";
+onLoad(() => {
+  console.log(uni.$uv.randomArray([1, 2, 3, 4, 5, 6, 7, 8, 9]));
+});
+
+</script>
+```

package/docs/api/utils/route.md

@@ -0,0 +1,121 @@
+## route 路由跳转
+
+### 按需引入
+
+如果未做全局[扩展配置](https://www.uvui.cn/components/setting.html)，可以按需引入：
+
+```js
+// 引入
+import route from '@gmcb/uv-ui/libs/utils/route.js';
+// 调用
+route(...);
+```
+
+### route(OBJECT)
+
+路由跳转方法，内部是对uni多个路由跳转api的封装，更方便使用。支持路由拦截等多功能。
+
+**OBJECT参数说明：**
+
+| 参数名      |     类型       |      默认值      |   是否必填      |  说明   |
+| :- | :- | :- | :-  | :-  |
+| type | String  | navigateTo | false | 路由跳转方式，参考下面[Type Options](/api/utils/route.html#type-options) |
+| url | String  | -	 | false | `type`为`navigateBack`时不填，其他必填 |
+| delta | Number | 1  | false | `type`为`navigateBack`时用到，表示返回的页面数 |
+| params | Object | -  | false | 传递的对象形式的参数，如 { name: 'lisa', age: 18 } |
+| animationType | String | pop-in  | false | 只在APP生效，详见[窗口动画](https://uniapp.dcloud.io/api/router?id=animation) |
+| animationDuration | Number | 300  | false | 动画持续时间，单位ms |
+| events | Object | - | false | 页面间通信接口，用于监听被打开页面发送到当前页面的数据。hbuilderX 2.8.9+ 开始支持。详情参考[uni.navigateTo](https://uniapp.dcloud.net.cn/api/router.html#navigateto) |
+
+#### Type Options
+
+| 属性名 | 说明 |
+|:-|:-|
+| `navigateTo` 或 `to` | 同 uni.navigateTo() | 
+| `redirect` 或 `redirectTo` | 同 uni.redirectTo() | 
+| `switchTab` 或 `tab` | 同 uni.switchTab() | 
+| `reLaunch` 或 `launch` | 同 uni.reLaunch() |
+| `navigateBack`或`back` | 同 uni.navigateBack() |
+
+
+### 基本用法
+
+```js
+uni.$uv.route({
+	url: '/subpages/demo/demo',
+	params: {
+		name: 'uvui'
+	}
+})
+```
+
+### 路由拦截
+
+```js
+uni.$uv.route({
+	url: '/subpages/demo/demo',
+	intercept(params, next) {
+		console.log(params, next)
+		uni.showLoading({
+			title: '等待中...'
+		})
+		// 模拟处理等待
+		setTimeout(() => {
+			uni.hideLoading();
+			next(true);
+		}, 1000)
+	}
+})
+```
+
+### navigateTo监听器
+
+```js
+uni.$uv.route({
+	url: '/subpages/demo/demo',
+	events: {
+		// 为指定事件添加一个监听器，获取被打开页面传送到当前页面的数据
+		acceptDataFromOpenedPage(data) {
+			console.log(data)
+		},
+		someEvent(data) {
+			console.log(data)
+		}
+	}
+})
+```
+
+### 简写用法
+
+为了方便简写和调用，可以直接传递一个`url`地址替代`Object`，
+
+注意：只能执行`uni.navigateTo`类型的地址，**不支持跳转到Tabbar页面**，如果有参数需要携带，以对象形式写到方法的第二个参数中。
+
+```js
+// 无参数
+uni.$uv.route('/subpages/demo/demo');
+
+// 带参数
+uni.$uv.route('/subpages/demo/demo', {
+	name: 'uvui',
+	age: 1
+});
+```
+
+<style scoped>
+h3[id=route-object] + p + p + table thead tr th:nth-child(5){
+	width: 45%;
+}
+
+h3[id=route-object] + p + p + table thead tr th:nth-child(2){
+	width: 12%;
+}
+h4[id=type-options] + table {
+	width: 40%;
+}
+h4[id=type-options] + table thead tr th:nth-child(1),
+h4[id=type-options] + table thead tr th:nth-child(2)
+{
+	width: 50%;
+}
+</style>

package/docs/api/utils/test.md

@@ -0,0 +1,237 @@
+## Test 规则校验
+
+uv-ui内置了一些校验规则，如是否手机号，邮箱号，URL等  
+这些规则方法，挂载在`$uv.test`下面，如验证是否手机号：`$uv.test.mobile('13888889999')`，如果验证通过，返回`true`，否则返回`false`
+
+### 按需引入
+
+如果未做全局[扩展配置](https://www.uvui.cn/components/setting.html)，可以按需引入：
+
+```js
+// 引入，实例中未写完，自己根据需求写
+import { code, array, jsonString, object, email } from '@gmcb/uv-ui/libs/function/test.js';
+```
+
+### code(value, len = 6)
+
+校验是否验证码(要求为数字)，返回`true`或者`false`。
+
+- `value` <String\> 验证码字符串
+- `len` <Number\> 验证码长度，默认为6
+
+```js
+console.log(uni.$uv.test.code('4567', 4));
+```
+
+### array(array)
+
+校验是否数组，返回`true`或者`false`。
+
+- `array` <Array\> 数组
+
+```js
+console.log(uni.$uv.test.array([1, 2, 3]));
+```
+
+### jsonString(json)
+
+校验是否是Json字符串，返回`true`或者`false`。
+
+- `json` <Json\> Json字符串
+
+注意：请留意json字符串的要求：
+1. 整体为一个字符串
+2. 字符串对象内的属性需要用`""`双引号包含
+
+```js
+console.log(uni.$uv.test.jsonString('{"a": 1}'));
+```
+
+### object(object)
+
+校验是否是是对象，返回`true`或者`false`。
+
+- `object` <Object\> 对象
+
+```js
+console.log(uni.$uv.test.object({a: 1}));
+```
+
+### email(email)
+
+校验是否邮箱号，返回`true`或者`false`。
+
+- `email` <String\> 字符串
+
+```js
+console.log(uni.$uv.test.email('123465798@gmail.com'));
+```
+
+### mobile(mobile)
+
+校验是否手机号，返回`true`或者`false`。
+
+- `mobile` <String\> 字符串
+
+```js
+console.log(uni.$uv.test.mobile('13845678900'));
+```
+
+### url(url)
+
+校验是否URL链接，返回`true`或者`false`。
+
+- `url` <String\> 字符串
+
+```js
+console.log(uni.$uv.test.url('http://www.uv-uiui.com'));
+```
+
+### empty(value)
+
+校验值是否为空，返回`true`或者`false`。  
+此方法等同于`empty`名称，但是为了更语义化，推荐用`empty`名称。
+
+这里指的“空”，包含如下几种情况：
+- 值为`undefined`(一种类型)，非字符串`"undefined"`
+- 字符串长度为0，也即空字符串
+- 值为`false`(布尔类型)，非字符串`"false"`
+- 值为数值`0`(非字符串`"0"`)，或者`NaN`
+- 值为`null`，空对象`{}`，或者长度为0的数组
+
+- `value` <any\> 字符串
+
+```js
+console.log(uni.$uv.test.empty(''));
+```
+
+### date(date)
+
+效验是否普通日期
+
+验证一个字符串是否日期，返回`true`或者`false`，如下行为正确：
+- `2020-02-10`、`2020-02-10 08:32:10`、`2020/02/10 3:10`、`2020/02/10 03:10`、`2020/02-10 3:10`
+
+如下为错误：
+- `2020年02月10日`、`2020-02-10 25:32`
+
+总的来说，年月日之间可以用"/"或者"-"分隔(不能用中文分隔)，时分秒之间用":"分隔，数值不能超出范围，如月份不能为13，则检验成功，否则失败。
+
+- `date` <String\> 日期字符串
+
+```js
+console.log(uni.$uv.test.date('2020-02-10 08:32:10'));
+```
+
+### number(number)
+
+效验是否十进制数值，整数，小数，负数，带千分位数(2,359.08)等可以检验通过，返回`true`或者`false`。
+
+- `number` <String\> 数字
+
+```js
+console.log(uni.$uv.test.number('2020'));
+```
+
+### digits(number)
+
+效验是否整数，所有字符都在`0-9`之间，才校验通过，结果返回`true`或者`false`。
+
+- `number` <String\> 数字
+
+```js
+console.log(uni.$uv.test.digits('2020'));
+```
+
+### idCard(idCard)
+
+效验是否身份证号，包括尾数为"X"的类型，可以校验通过，结果返回`true`或者`false`。
+
+- `idCard` <String\> 身份证号
+
+```js
+console.log(uni.$uv.test.idCard('110101199003070134'));
+```
+
+### carNo(carNo)
+
+校验旧车牌号和新能源类型车牌号，结果返回`true`或者`false`。
+
+- `carNo` <String\> 车牌号
+
+```js
+console.log(uni.$uv.test.carNo('京A88888'));
+```
+
+### amount(amount)
+
+效验是否金额，最多两位小数，可以带千分位，结果返回`true`或者`false`。
+
+- `amount` <String\> 金额字符串
+
+```js
+console.log(uni.$uv.test.amount('3,233.08'));
+```
+
+### chinese(zh)
+
+效验是否汉字，可以为单个汉字，或者汉字组成的字符串，结果返回`true`或者`false`。
+
+- `zh` <String\> 中文字符串
+
+```js
+console.log(uni.$uv.test.chinese('更上一层楼'));
+```
+
+### letter(en)
+
+效验是否字母，只能为"a-z"或者"A-Z"之间的字符，结果返回`true`或者`false`。
+
+- `en` <String\> 字母串
+
+```js
+console.log(uni.$uv.test.letter('uv-ui'));
+```
+
+### enOrNum(str)
+
+效验是否字母或者数字，只能是字母或者数字，结果返回`true`或者`false`。
+
+- `str` <String\> 字母或者数字字符串
+
+```js
+console.log(uni.$uv.test.enOrNum('uv-ui'));
+```
+
+### contains(str, subStr)
+
+效验是否包含某个值，字符串中是否包含某一个子字符串，区分大小写，结果返回`true`或者`false`。
+
+- `str` <String\> 字符串
+- `subStr` <String\> 子字符串
+
+```js
+console.log(uni.$uv.test.contains('uv-ui', 'View'));
+```
+
+### range(number, range)
+
+效验数值是否在某个范围内，如30在"29-35"这个范围内，不在"25-28"这个范围内，结果返回`true`或者`false`。
+
+- `number` <Number\> 数值
+- `range` <Array\> 如"[25-35]"
+
+```js
+console.log(uni.$uv.test.range(35, [30, 34]));
+```
+
+### rangeLength(str, range)
+
+效验字符串长度是否在某个范围内，如"abc"长度为3，范围在"2-5"这个区间，结果返回`true`或者`false`。
+
+- `str` <String\> 数值
+- `range` <Array\> 如"[25, 35]"
+
+```js
+console.log(uni.$uv.test.rangeLength('abc', [3, 10]));
+```