@gmcb/uv-ui 0.2.27 → 0.3.1

package/docs/api/utils/fastUse.md

@@ -0,0 +1,246 @@
+## 便捷工具
+
+此专题内容为一些方便用户快速，便捷使用的小工具，可能是uv-ui的一些方法的简易版，或者对uni的一些方法进行二次封装，方便用户
+快速使用。
+
+### 按需引入
+
+如果未做全局[扩展配置](https://www.uvui.cn/components/setting.html)，可以按需引入：
+
+```js
+// 引入，实例中未写完，自己根据需求写
+import { os, sys, platform } from '@gmcb/uv-ui/libs/function/index.js';
+import platform from '@gmcb/uv-ui/libs/function/platform.js';
+```
+ 
+### os()
+
+此方法用于返回平台的名称，为小写的`ios`或`android`  
+
+```js
+uni.$uv.os()
+```
+
+
+### sys()
+
+此方法用于获取设备的信息，相当于uni.getSystemInfoSync()的效果  
+
+```js
+uni.$uv.sys()
+```
+
+
+### platform
+
+此`属性`用于获取当前运行的平台名称，相较于`uni-app`系统自带的条件编译的区别是，此方式让我们可以通过`js`的`if | else if`进行判断，
+您可以结合实际场景进行使用。  
+
+- 注意：此属性返回的结果，和`uni-app`的条件编译名称有差别，并且结果都为小写。
+
+
+使用前配置：如果您的项目为`vue-cli`模式，必须要在`根目录`的`vue.config.js`进行配置才有效，如下：
+
+```js
+// vue.config.js，如没有此文件则手动创建
+module.exports = {
+    transpileDependencies: ['@gmcb/uv-ui']
+}
+```
+
+使用：
+
+```js
+// 返回'h5'
+uni.$uv.platform
+
+// 条件判断
+const { platform } = uni.$u
+if(platform === 'app') {
+	......
+} else if(platform === 'nvue') {
+	......
+}
+```
+
+#### 各平台对应返回值如下表：
+
+| 平台							| 返回值		|
+|:-								|:-			|
+| VUE3，HBuilderX 3.2.0+						        |    vue3       |
+| App					        |    plus       |
+| App nvue					        |    nvue       |
+| H5					        |    h5       |
+| 微信小程序					        |    weixin       |
+| 支付宝小程序					        |    alipay       |
+| 百度小程序					        |    baidu       |
+| 字节跳动小程序、飞书小程序						        |    toutiao       |
+| QQ小程序						        |    qq       |
+| 快手小程序						        |    kuaishou       |
+| 360小程序						        |    360       |
+| 微信小程序/支付宝小程序/百度小程序/字节跳动小程序/QQ小程序/360小程序						        |    mp       |
+| 快应用通用(包含联盟、华为)						        |    webview       |
+| 快应用联盟						        |    webview-union       |
+| 快应用华为						        |    webview-huawei       |
+
+### range(min, max, value)
+
+此方法用于限制`value`的大小，如果其在`min`和`max`之间，则不变；如果其小于`min`，则取`min`值；如果其大于`max`，则取`max`值。
+
+```js
+// 最终结果为5
+uni.$uv.range(1, 5, 8)
+
+// 最终结果为4
+uni.$uv.range(1, 5, 4)
+```
+
+
+### getPx(value [, unit = false])
+
+此方法用于返回带单位的值的数值结果，如果第二个参数为`true`，返回的结果将会带上`px`的单位；可接受的值如下：
+
+- 带`upx`和`rpx`单位，返回使用`uni.upx2px`转换后，为`px`单位的结果
+- 带`px`单位，返回去掉`px`单位的具体数值
+- 具体数值，如`5`，将会返回`5`
+
+```js
+// 返回10
+uni.$uv.getPx('10rpx')
+
+// 返回12
+uni.$uv.getPx('12px')
+
+// 返回14
+uni.$uv.getPx(14)
+
+// 返回类似10px的结果
+uni.$uv.getPx('20rpx', true)
+```
+
+
+### sleep(value)
+
+延时一定时间进行回调，类似于`promise`的使用方式
+
+- `value`，数值，单位默认为`ms`
+
+```js
+// 300ms后触发回调
+uni.$uv.sleep(300).then(() => {
+	console.log('定时结束')
+})
+```
+
+
+### $parent.call(instance [, name])
+
+用于抹平各端差异，在组件中向上获取父组件或者页面的实例。
+
+- `instance`，实例，传`this`即可，不可修改
+- `name`，可选，页面或者父组件的`name`属性值，不传则默认查找页面(最顶层)的实例
+
+```vue
+<!-- 页面内容 -->
+<template>
+	<child></child>
+</template>
+
+<script setup>
+defineOptions({
+	name: 'page'
+});
+
+</script>
+
+<!-- 组件内容 -->
+<script setup>
+import { getCurrentInstance, onMounted } from 'vue';
+
+const { proxy } = getCurrentInstance();
+
+onMounted(() => {
+	// 将会得到父页面实例
+	uni.$uv.$parent.call(proxy, 'page');
+});
+
+</script>
+```
+
+
+### addStyle(style [, target = 'object'])
+
+用于将`字符串`形式的内联样式样式转为`对象`形式，或者将`对象`形式的样式写法转为`字符串`形式。
+
+- `style`，样式，可为对象或者字符串形式
+- `target`，可选，转换结果的类型，默认为`object`；如果为`object`则返回对象形式的结果，如果为`string`则返回字符串形式的结果
+
+```js
+// 将会返回'padding: 10px; margin: 20px'
+const style = { padding: '10px', margin: '20px' }
+uni.$uv.addStyle(style, 'string')
+
+// 将会返回{ padding: '10px', margin: '20px' }
+const style = "padding: 10px; margin: 20px"
+uni.$uv.addStyle(style)
+```
+
+
+### addUnit(value [, unit = 'px'])
+
+用于给值加上单位，如果值已有单位，则直接原样返回，如果值为`数值`，则加上`unit`参数的单位。
+
+- `value`，可为`5`，`5px`，`6rpx`，`100%`等格式的值
+- `unit`，可选，默认为`px`，如果第一个参数为`数值`，则拼接上此单位
+
+```js
+// 返回5px
+uni.$uv.addUnit(5)
+uni.$uv.addUnit('5px')
+
+// 返回5rpx
+uni.$uv.addUnit(5, 'rpx')
+```
+
+
+### priceFormat(value [, decimals = 0 [, decimalPoint = '.' [, thousandsSeparator = ',']]])
+
+此方法可用于对数值形式的金额进行格式化
+
+- value，需要格式化的金额数值，只能为数值，如`300.52`，`300`，而不能为诸如带千分位的写法`3,000.5`
+- decimals，可选，格式化后小数点的位数，默认为`0`，小数最后一位会进行四舍五入
+- decimalPoint，可选，小数点的符号，默认为`.`
+- thousandsSeparator，可选，千分位分隔符，默认为英文逗号`,`
+
+```js
+// 返回3,002.37
+uni.$uv.priceFormat(3002.365, 2)
+
+// 返回3,002
+uni.$uv.priceFormat(3002.365)
+```
+
+
+### page()
+
+此方法用于获取当前页面的路径，返回的路径以`/`开头。
+
+```js
+// 返回类似/pages/example/components的结果
+uni.$uv.page()
+```
+
+### pages()
+ <!-- <badge text="2.0.22" /> -->
+
+本方法为`getCurrentPages()`的封装，用于获取当前页面栈的实例，以数组形式按栈的顺序给出，第一个元素为首页，最后一个元素为当前页面。
+
+```js
+uni.$uv.pages()
+```
+
+<style scoped>
+h4[id=各平台对应返回值如下表] + table thead tr th:nth-child(2){
+	width: 40%;
+}
+</style>

package/docs/api/utils/getRect.md

@@ -0,0 +1,238 @@
+## dom获取节点布局信息 （nvue）
+
+```vue
+<script setup>
+import { ref } from 'vue';
+
+// #ifdef APP-NVUE
+const dom = uni.requireNativePlugin('dom');
+// #endif
+
+const nodeRef = ref(null);
+
+function queryRect() {
+  return new Promise(resolve => {
+    dom.getComponentRect(nodeRef.value, res => {
+      resolve(res.size);
+    });
+  });
+}
+
+</script>
+```
+## getRect 获取节点布局信息 （vue）
+
+此方法封装自uni的[nodesRef.boundingClientRect](https://uniapp.dcloud.io/api/ui/nodes-info?id=nodesrefboundingclientrect)，它极大简化了
+使用复杂度，内部使用`Promise`，可以让用户同步获取节点信息。
+
+### getRect(selector, all = false)
+
+- `selector` <String\> 此参数为元素节点，可以是`id`或者`class`，比如"#user-name"，".box"
+- `all` <Boolean\> 是否返回全部节点信息，当页面有多个相同`selector`的元素时，`all`为`true`，会以数组形式返回所有节点的信息(结果为数组，数组元素为对象)，否则只返回第一个节点的信息(结果为一个对象)
+
+注意：该方法返回的结果，共有如下有用信息：
+
+```js
+res = {
+	left: 0,
+	right: 414,
+	top: 323,
+	height: 2597,
+	bottom: 2920,
+	width: 414
+}
+```
+
+受限于`nodesRef.boundingClientRect`，其上结果中的`left`，`top`，`right`，`bottom`，是会随着页面滚动而变化的，因为这个查询的相对于屏幕窗口，而不是
+相对于页面根元素的，但`width`，`height`，是恒定不变的，所以一般情况我们推荐您想要获取节点宽高的时候采用这个方法。
+
+:::warning 注意
+由于`onLoad`生命周期元素尚未创建完成，请勿在此生命周期使用此方法，如果是页面，应该在`onReady`生命周期，组件内应该在`mounted`生命周期调用。
+如果要查询的目标，是通过服务端获取数据后才渲染的，那么应该在获取数据后，通过 Vue 3 的 `nextTick` 调用此方法。
+:::
+
+### 异步使用方法
+
+通过`then`调用即可
+
+```vue
+<script setup>
+import { getCurrentInstance } from 'vue';
+
+const { proxy } = getCurrentInstance();
+
+function getElInfo() {
+	proxy.$uv.getRect('.user-avatar').then(res => {
+		console.log(res);
+	});
+}
+
+</script>
+```
+
+
+### 同步使用方法
+
+该方法的使用场景为您下一步的操作需要获取元素的节点后才能进行的情况，可以通过`async/await`方式调用，注意，无论是生命周期还是`methods`中的方法，都可以在
+其前面添加`async`修饰符
+
+```vue
+<script setup>
+import { getCurrentInstance } from 'vue';
+
+const { proxy } = getCurrentInstance();
+
+async function getElInfo() {
+	const rectInfo = await proxy.$uv.getRect('.user-avatar');
+	console.log(rectInfo);
+}
+
+</script>
+```
+
+### 在 Vue 3 `<script setup>` 中使用方法
+
+```vue
+<script setup>
+	import { onReady } from '@dcloudio/uni-app';
+	import { getCurrentInstance } from 'vue';
+	const { proxy } = getCurrentInstance();
+	onReady(()=>{
+		proxy.$uv.getRect('.demo').then(res=>{
+			console.log(res)
+		})
+	})
+
+</script>
+```
+
+### 请求数据后再获取节点信息
+
+此场景为元素内容为后端获取数据填充的，节点填充数据前后，元素的大小尺寸是不一样的，所以需要在获取后再执行此方法，这里通过 `nextTick` 调用，
+是因为它会等待数据赋值，元素创建完成后再执行，此时才是准确的尺寸，以下演示，为uv-ui自带的[http 请求](/api/request/http.html)方法调用
+
+```html
+<template>
+	<view>
+		<view class="user-name">
+			{{userName}}
+		</view>
+	</view>
+</template>
+
+<script setup>
+import { getCurrentInstance, nextTick, ref } from 'vue';
+import { onLoad } from '@dcloudio/uni-app';
+
+const { proxy } = getCurrentInstance();
+const userName = ref('');
+
+function getElInfo() {
+	uni.$uv.http.post('http://www.example.com/user/info').then(async res => {
+		userName.value = res.name;
+		await nextTick();
+		const rect = await proxy.$uv.getRect('.user-avatar');
+		console.log(rect);
+	});
+}
+
+onLoad(() => {
+	getElInfo();
+});
+
+</script>
+```
+
+### 获取全部节点信息
+
+设置第二个参数为`true`，此场景为页面有多个相同类名的元素，需要获取所有同类名节点信息时候使用，返回结果为一个数组
+
+```html
+<template>
+	<view>
+		<view class="item">
+			uv-ui
+		</view>
+		<view class="item">
+			<view>红豆生南国，春来发几枝</view>
+			<view>愿君多采撷，此物最相思</view>
+		</view>
+	</view>
+</template>
+
+<script setup>
+import { getCurrentInstance } from 'vue';
+import { onReady } from '@dcloudio/uni-app';
+
+const { proxy } = getCurrentInstance();
+
+function getElInfo() {
+	proxy.$uv.getRect('.item', true).then(rect => {
+		// rect为一个数组(内有2个元素)，因为页面有2个.item节点
+		console.log(rect);
+	});
+}
+
+onReady(() => {
+	getElInfo();
+});
+
+</script>
+```
+
+
+### 如何让让某个元素滚动到页面顶部
+
+这里说的顶部，指的是导航栏的下方，比如我们点击某个操作，页面自动滚动，指定元素位于导航栏下方时停止。  
+我们需要结合`onPageScroll`生命周期，获得实时的页面滚动条位置。
+
+
+```html
+<template>
+	<view class="wrap">
+		<view class="item">
+			uv-ui
+		</view>
+		<view class="item">
+			uv-ui
+		</view>
+		<view class="item">
+			uv-ui
+		</view>
+		<view class="item">
+			uv-ui
+		</view>
+		<view class="item object-item" @tap="scrollEl">
+			点我，我就会滚动到导航栏下方
+		</view>
+	</view>
+</template>
+
+<script setup>
+import { getCurrentInstance, ref } from 'vue';
+import { onPageScroll } from '@dcloudio/uni-app';
+
+const { proxy } = getCurrentInstance();
+const scrollTop = ref(0);
+
+onPageScroll(e => {
+	scrollTop.value = e.scrollTop;
+});
+
+function scrollEl() {
+	proxy.$uv.getRect('.object-item').then(res => {
+		uni.pageScrollTo({
+			scrollTop: scrollTop.value + res.top,
+			duration: 0
+		});
+	});
+}
+
+</script>
+
+<style lang="scss" scoped>
+	.wrap {
+		height: 200vh;
+	}
+</style>
+```

package/docs/api/utils/guid.md

@@ -0,0 +1,41 @@
+## guid 全局唯一标识符
+
+### 按需引入
+
+如果未做全局[扩展配置](https://www.uvui.cn/components/setting.html)，可以按需引入：
+
+```js
+// 引入
+import { guid } from '@gmcb/uv-ui/libs/function/index.js';
+// 调用
+guid(...);
+```
+
+### guid(length = 32, firstU = true, radix = 62)
+
+该函数可以生产一个全局唯一、随机的guid，默认首字母为`u`，可以用于当做元素的id或者class名等需要唯一，随机字符串的地方，因为id或者class不能以数字开头。
+
+- `length` <Number | null\> guid的长度，默认为`32`，如果取值`null`，则按`rfc4122标准`生成对应格式的随机数
+- `firstU` <Boolean\> 首字母是否为"u"，如果首字母为数字情况下，不能用作元素的`id`或者`class`，默认为`true`
+- `radix` <Number\> 生成的基数，默认为`62`，用于生成随机数字符串为"0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz"，
+如果取2，那么返回的结果就是前两位0和1(可以理解为二进制)的随机结果，如果为7，返回的字符串就是0-7(理解为八进制)之间，
+10为十进制，以此类推。
+
+**说明**：这个方法三个参数都有默认的值，所以您调用的时候，可以无需传递任何参数也是可以的，并且**建议您这样做**。
+
+```vue
+<template>
+	<view :class="className"></view>
+</template>
+<script setup>
+import { computed } from "vue";
+import { onLoad } from "@dcloudio/uni-app";
+const className = computed(() => {
+  return uni.$uv.guid(20);
+});
+onLoad(() => {
+  console.log(uni.$uv.guid());
+});
+
+</script>
+```

package/docs/api/utils/index.md

@@ -0,0 +1,55 @@
+# 工具
+
+`@gmcb/uv-ui` 的工具能力会在插件注册后挂载到 `uni.$uv`，也可以从 `@gmcb/uv-ui/libs` 深度按需引用。
+
+## 使用方式
+
+全局使用：
+
+```ts
+uni.$uv.trim(' abc ');
+uni.$uv.timeFormat(Date.now(), 'yyyy-mm-dd');
+uni.$uv.route('/pages/index/index');
+```
+
+按需引用：
+
+```ts
+import { trim } from '@gmcb/uv-ui/libs/function/test.js';
+import { timeFormat } from '@gmcb/uv-ui/libs/function/index.js';
+import route from '@gmcb/uv-ui/libs/utils/route.js';
+```
+
+## 工具分类
+
+| 文档 | 说明 |
+| --- | --- |
+| [全局使用](./intro.md) | `uni.$uv` 和按需引用说明。 |
+| [快速使用](./fastUse.md) | 平台、系统和常用快捷方法。 |
+| [路由](./route.md) | `uni.$uv.route` 路由跳转。 |
+| [queryParams](./queryParams.md) | 对象转 URL 参数。 |
+| [时间](./time.md) | 时间格式化和相对时间。 |
+| [防抖节流](./debounce.md) | `debounce` 和 `throttle`。 |
+| [校验](./test.md) | 常用校验规则。 |
+| [对象](./object.md) | 深拷贝、深合并和属性读取。 |
+| [随机数](./random.md) | 随机数。 |
+| [随机数组](./randomArray.md) | 数组乱序。 |
+| [guid](./guid.md) | 唯一 ID。 |
+| [trim](./trim.md) | 去除空格。 |
+| [颜色转换](./colorSwitch.md) | 颜色渐变、HEX/RGB 转换。 |
+| [节点布局](./getRect.md) | 获取节点尺寸和位置。 |
+
+## 相关 API
+
+| 文档 | 说明 |
+| --- | --- |
+| [HTTP 请求](../request/http.md) | `uni.$uv.http` 请求实例和拦截器。 |
+| [API 集中管理](../request/apiManage.md) | 请求 API 统一管理方式。 |
+| [颜色值](../configs/color.md) | 内置颜色配置。 |
+| [小程序分享](../mixins/mpShare.md) | 小程序分享 mixin。 |
+
+## 路径约定
+
+- 文档目录为 `docs/api/utils`。
+- 站点路径归入 `/api/*/*.html`。
+- 历史工具分类路径不再作为本包文档入口。

package/docs/api/utils/intro.md

@@ -0,0 +1,25 @@
+# 全局使用，请按照[扩展配置](https://www.uvui.cn/components/setting.html)进行配置后即可正常使用。
+
+### 全局使用
+
+此js函数方法，为uv-ui框架提供的一部分功能，它的实现，需要通过js调用，而不是组件的形式。 
+
+工具库中的所有方法，如果按照[扩展配置](/components/setting.html)进行配置后，均挂载在`$uv`对象下，调用方法如下：
+
+示例：
+
+```js
+console.log(uni.$uv.trim(' abc '));	// 去除两端空格
+```
+
+### 按需使用
+
+如果未做全局[扩展配置](https://www.uvui.cn/components/setting.html)，可以按需引入，具体引入路径等请到具体API中查看：
+
+示例：
+
+```js
+import { trim } from '@gmcb/uv-ui/libs/function/test.js';
+// 使用
+console.log(trim('你好   '))
+```