@gmcb/uv-ui 0.2.26 → 0.3.0

package/docs/components/setting.md

@@ -0,0 +1,111 @@
+# 扩展配置
+
+`@gmcb/uv-ui` 注册后会向 `uni.$uv` 注入工具、请求实例、路由方法和配置对象。本页说明插件注册、局部引用、主题样式和 `setConfig` 的推荐用法。
+
+## 注册插件
+
+在 uni-app 入口注册：
+
+```ts
+import { createSSRApp } from 'vue';
+import uvUI from '@gmcb/uv-ui';
+import App from './App.vue';
+
+export function createApp() {
+  const app = createSSRApp(App);
+  app.use(uvUI);
+  return {
+    app,
+  };
+}
+```
+
+注册后可以使用：
+
+```ts
+uni.$uv.trim(' abc ');
+uni.$uv.random(1, 3);
+uni.$uv.route('/pages/index/index');
+uni.$uv.http.get('/api/example');
+```
+
+## 组件实例能力
+
+部分能力依赖组件实例上下文，例如 `getRect`。Vue 3 `<script setup>` 中可以通过 `getCurrentInstance()` 访问：
+
+```vue
+<script setup>
+import { onReady } from '@dcloudio/uni-app';
+import { getCurrentInstance } from 'vue';
+
+const { proxy } = getCurrentInstance();
+
+onReady(() => {
+  proxy.$uv.getRect('.demo').then((rect) => {
+    console.log(rect);
+  });
+});
+
+</script>
+```
+
+节点布局相关说明见 [getRect](/api/utils/getRect.md)。
+
+## 局部引用
+
+不需要全局注册时，也可以直接从包内工具路径按需引用：
+
+```ts
+import { os, sys, timeFormat } from '@gmcb/uv-ui/libs/function/index.js';
+import { trim } from '@gmcb/uv-ui/libs/function/test.js';
+import route from '@gmcb/uv-ui/libs/utils/route.js';
+
+console.log(os());
+console.log(sys());
+console.log(trim(' abc '));
+console.log(timeFormat(Date.now(), 'yyyy-mm-dd'));
+route('/pages/index/index');
+```
+
+深度引用路径依赖包内发布结构，升级前应确认目标文件仍存在。
+
+## 主题样式
+
+在 `uni.scss` 或统一主题入口引入主题变量：
+
+```scss
+@import '@gmcb/uv-ui/theme.scss';
+```
+
+在 `App.vue` 或全局样式入口引入基础样式：
+
+```scss
+@import '@gmcb/uv-ui/index.scss';
+```
+
+基础样式包含常用工具类，例如 `uv-line-1`、`uv-border`、`uv-border-top`、`uv-hover-class`。
+
+## setConfig
+
+`setConfig` 用于修改 `uni.$uv.config` 和组件默认 props。需要在 `app.use(uvUI)` 之后执行：
+
+```ts
+import uvUI from '@gmcb/uv-ui';
+
+app.use(uvUI);
+
+uni.$uv.setConfig({
+  config: {
+    unit: 'rpx',
+  },
+  props: {
+    text: {
+      color: {
+        default: 'red',
+      },
+    },
+  },
+});
+```
+
+注意：`app-vue` 不支持全局使用 `uni.$uv.setConfig` 设置 props 时，请在目标平台验证实际效果。

package/docs/components/settingDesc.md

@@ -0,0 +1,66 @@
+## 配置的原理
+
+### 注册 JS 工具库
+
+`@gmcb/uv-ui` 内部集成了常用 JS 工具，例如 `random`、`trim`、`queryParams`、`http` 等。Vue 3 项目需要在 `main.js` 中通过 `app.use(uvUI)` 注册：
+
+```js
+import App from './App';
+import { createSSRApp } from 'vue';
+import uvUI from '@gmcb/uv-ui';
+
+export function createApp() {
+	const app = createSSRApp(App);
+	app.use(uvUI);
+	return { app };
+}
+```
+
+注册后，普通模块可通过 `uni.$uv` 使用工具：
+
+```js
+console.log(uni.$uv.random(1, 10));
+console.log(uni.$uv.trim(' abc '));
+```
+
+组件实例相关能力可在 `<script setup>` 中通过实例代理访问：
+
+```vue
+<script setup>
+import { getCurrentInstance } from 'vue';
+
+const { proxy } = getCurrentInstance();
+proxy.$uv.toast('保存成功');
+
+</script>
+```
+
+### 引入 SCSS 主题变量
+
+主题变量应写入项目根目录的 `uni.scss`：
+
+```scss
+@import '@gmcb/uv-ui/theme.scss';
+```
+
+### 引入基础样式
+
+基础样式建议在 `App.vue` 中全局引入：
+
+```vue
+<style lang="scss">
+@import '@gmcb/uv-ui/index.scss';
+</style>
+```
+
+### easycom
+
+easycom 可以让 `uv-*` 组件按需自动引入：
+
+```json
+{
+	"easycom": {
+		"^uv-(.*)": "@gmcb/uv-ui/components/uv-$1/uv-$1.vue"
+	}
+}
+```

package/docs/components/skeleton.md

@@ -0,0 +1,105 @@
+## Skeleton 骨架屏 <to-api/>
+
+<demo-model url="/pages/componentsD/skeleton/skeleton"></demo-model>
+
+::: tip ✈
+
+**组件名：uv-skeleton**
+
+[点击下载&安装](https://ext.dcloud.net.cn/plugin?name=uv-skeleton)
+
+:::
+
+骨架屏一般用于页面在请求远程数据尚未完成时，页面用灰色块预显示本来的页面结构，给用户更好的体验。  
+
+::: warning 说明
+由于```VUE```和```NVUE```的特性不同，组件动画在```VUE```上为由左到右形式，在```NVUE```上为明暗显隐的形式。
+:::
+
+### 平台兼容性
+
+|App（vue）|App（nvue）|H5|小程序|VUE2|VUE3|
+|:-:|:-:|:-:|:-:|:-:|:-:|
+|√|√|√|√|√|√|
+
+### 基本使用
+
+组件由`标题`，`段落`和`头像`组件组件，其中`段落`需要通过`rows`参数配置才显示，可以通过`title`和`avatar`是否显示`标题`和`头像` 。  
+该组件的使用，有几个需要注意的点，如下：
+- `title`(可选)，是否显示`标题`占位行，该占位行不布满全屏宽度，同时与`段落`的距离较大以做明显区分，默认为`true`
+- `avatar`(可选)，是否在左上角位置显示圆形的`头像`占位区域
+- `rows`(可选)，`段落`的行数
+- `loading`(必选)，是否加载中状态，如果为`true`则显示骨架屏组件占位，否则显示插槽中的内容
+
+数据请求完成后，将`loading`设置为`false`，会隐藏骨架组件
+
+```vue
+<template>
+	<uv-skeleton rows="3" title loading></uv-skeleton>
+</template>
+```
+
+### 加载中动画
+
+设置`animate`为`true`，加载中的骨架块将会有一个动画效果，用以加强视觉效果。
+
+```vue
+<uv-skeleton :loading="true" :animate="true"></uv-skeleton>
+```
+
+### 显示头像
+```vue
+<uv-skeleton :loading="true" avatar rows="1"></uv-skeleton>
+```
+
+### 插槽内容
+
+可以通过插槽写入展示的内容，当请求结束，将```loading```设置为```false```，此时会隐藏骨架组件，同时展示插槽内容。
+
+```vue
+<template>
+	<uv-skeleton rows="2" :loading="loading" avatar :title="false">
+		<text>loading为false时，将会展示此处插槽内容</text>
+	</uv-skeleton>
+</template>
+<script setup>
+import { ref } from 'vue';
+import { onLoad } from '@dcloudio/uni-app';
+
+const loading = ref(true);
+onLoad(() => {
+  setTimeout(() => {
+    loading.value = false;
+  }, 2000);
+});
+
+</script>
+```
+
+### 完整示例
+
+::: tip 完整示例下载地址
+
+[https://ext.dcloud.net.cn/plugin?name=uv-ui](https://ext.dcloud.net.cn/plugin?name=uv-ui)
+
+:::
+
+### API
+---
+
+### Skeleton Props
+
+| 参数			| 说明																				| 类型								| 默认值	|  可选值	|
+|:-				|:-																					|:-									|:-		|:-			|
+| loading		| 是否显示骨架占位图，设置为`false`将会展示子组件内容									| Boolean							| true	| true &#124; false		|
+| animate		| 是否开启动画效果																	| Boolean							| true	| true &#124; false		|
+| rows			| 段落占位图行数																		| Number &#124; String				| 0		| -			|
+| rowsWidth		| 段落占位图的宽度，可以为百分比，数值，带单位字符串等，可通过数组传入指定每个段落行的宽度	| String &#124; Array &#124; Number	| 100%	| -			|
+| rowsHeight	| 段落的高度																			| String &#124; Array &#124; Number | 18	| -			|
+| title			| 是否展示标题占位图																	| Boolean							| true	| true &#124; false		|
+| titleWidth	| 标题的宽度																			| String &#124; Number				| 50%	| -			|
+| titleHeight	| 标题的高度																			| String &#124; Number				| 18	| -			|
+| avatar		| 是否展示头像占位图																	| Boolean							| false	| true &#124; false		|
+| avatarSize	| 头像占位图大小																		| String &#124; Number				| 32	| -			|
+| avatarShape	| 头像占位图的形状，circle-圆形，square-方形											| String							| circle| circle &#124; square	|
+

package/docs/components/skeletons.md

@@ -0,0 +1,323 @@
+## Skeletons 骨架屏（新版） <to-api/>
+
+<demo-model url="/pages/componentsD/skeletons/skeletons"></demo-model>
+
+::: tip ✈
+
+**组件名：uv-skeletons**
+
+[点击下载&安装](https://ext.dcloud.net.cn/plugin?name=uv-skeletons)
+
+:::
+
+骨架屏一般用于页面在请求远程数据尚未完成时，在内容加载出来前展示与内容布局结构一致的灰白块，提升用户视觉体验。
+
+新版骨架屏与老版本使用参数有很大的区别，所以才有了新版本，无法替换老版本。
+
+新版骨架屏比老版本骨架屏更加灵活，理论上简单的左右上下布局结构均可以轻松实现，样式自由度较高，只要你会写css，推荐使用新版。
+
+### 平台兼容性
+
+|App（vue）|App（nvue）|H5|小程序|VUE2|VUE3|
+|:-:|:-:|:-:|:-:|:-:|:-:|
+|√|√|√|√|√|√|
+
+:::warning 注意事项
+
+> 为了避免错误使用，给大家带来不好的开发体验，请在使用组件前仔细阅读下面的注意事项，可以帮你避免一些错误。
+1. 由于`vue`和`nvue`的特性不同，组件动画在`vue`上为由左到右变化形式，在`nvue`上为明暗显隐的形式。
+
+:::
+
+### 基本使用
+
+该组件主要由 `loading` 和 `skeleton` 两个参数控制，骨架屏的具体内容由 `skeleton` 中的参数决定，这点非常重要，理论上只需要按照约定配置好该参数，就可以实现想要的结构，如下：
+
+- `loading`(必选)，是否加载中状态，如果为`true`则显示骨架屏组件占位，否则显示插槽中的内容
+- `skeleton`，数组形式 [Object,Object,...]。
+	- Object.type 类型，type的类型有多种见下方[参数说明](/components/skeletons.html#skeletons-options)。实际上type的意义不大，除flex类型外（下面会是单独说明该用法），其他的类型都可以自定义任意样式，默认为line。
+	- Object.num 表示重复几个，默认为1。
+	- Object.gap 重复几个之间的垂直间隔，**只有Object.num大于1才会生效**，默认 `20rpx`。
+
+```vue
+<template>
+	<view>
+		<uv-skeletons :loading="loading" :skeleton="skeleton"></uv-skeletons>
+	</view>
+</template>
+<script setup>
+import { ref } from "vue";
+const loading = ref(true);
+const skeleton = ref([{
+  type: 'line',
+  num: 3,
+  gap: '20rpx'
+}]);
+
+</script>
+```
+
+### 自定义样式
+
+- 通过 `skeleton` 中的 `style` 参数，可以自定义样式。
+	- `style` 的类型可以是 array | string | object，示例中的代码都有体现，仅为演示示例，样式根据需求自定义。
+	- `style` 的array类型，例如：['height: 100rpx;',null,null]，代表第一个line高度为100rpx，其余的line使用默认样式。
+	- `style` 的string和object类型，实际上是一样的，都是设置3个line均使用设置的样式。
+
+```vue
+<template>
+	<view>
+		<uv-skeletons :loading="loading" :skeleton="skeleton"></uv-skeletons>
+	</view>
+</template>
+<script setup>
+import { ref } from "vue";
+const loading = ref(true);
+const skeleton = ref([{
+  type: 'line',
+  num: 3,
+  gap: '20rpx',
+  style: ['width: 200rpx;marginBottom: 50rpx;', 'height: 100rpx;', 'width: 500rpx;']
+  // style: 'width: 200rpx;marginBottom: 50rpx;'
+  // style: {width: '200rpx',marginBottom: '50rpx'}
+}]);
+
+</script>
+```
+
+### 横向并列布局
+
+- 通过 `skeleton` 中的参数 `type` 为 `flex`，可以实现横向并列布局。
+- Object.children 该参数的用法与上述一致。**注意：children下不支持再有children**
+- `type` 还有 avatar、custom 类型，下面示例可以看出。
+	- avatar类型，为了好理解，增加了头像类型，有自己的默认样式，实际上也可使使用style进行样式控制。
+	- custom类型，完全自定义样式的可以使用该类型，这样做的目的仅仅是为了好理解。
+
+```vue
+<template>
+	<view>
+		<uv-skeletons :loading="loading" :skeleton="skeleton"></uv-skeletons>
+	</view>
+</template>
+<script setup>
+import { ref } from "vue";
+const loading = ref(true);
+const skeleton = ref([{
+  type: 'flex',
+  num: 1,
+  children: [{
+    type: 'avatar',
+    num: 1,
+    style: 'marginRight: 10rpx;'
+  }, {
+    type: 'line',
+    num: 3,
+    gap: '30rpx',
+    style: ['width: 200rpx;', null, 'width:400rpx;']
+  }, {
+    type: 'custom',
+    num: 1,
+    style: 'width: 200rpx;height:200rpx;marginLeft: 10rpx;'
+  }]
+}]);
+
+</script>
+```
+
+### 混合布局 + 插槽内容
+
+- 可以通过插槽写入展示的内容，当请求结束，将```loading```设置为```false```，此时会隐藏骨架组件，同时展示插槽内容。
+- `skeleton` 参数还可以是一个 `Number`，表示上下之间的间距，单位为 `rpx`。30 代表上下之间的间距为 `30rpx`，示例如下：
+
+```vue
+<template>
+	<view class="uv-page">
+		<uv-skeletons :loading="loading" :skeleton="skeleton" :animate="animate">
+			<view class="uv-skeletons__row uv-skeletons__row1">
+				<view class="uv-skeletons__row1--left">
+					<image class="img" src="https://via.placeholder.com/200x200.png/3c9cff"></image>
+				</view>
+				<view class="uv-skeletons__row1--right">
+					<uv-text text="uv-ui破釜沉舟之兼容vue3+2、nvue、app、h5" color="#222" size="30rpx" lines="1"></uv-text>
+					<uv-text text="在经过改进后全面支持vue3" color="#222" size="30rpx" lines="1" margin="6rpx 0 0"></uv-text>
+					<uv-text text="欢迎大家使用" lines="1" color="#222" size="30rpx" margin="6rpx 0 0"></uv-text>
+				</view>
+			</view>
+			<view style="height: 30rpx;"></view>
+			<view class="uv-skeletons__row uv-skeletons__row2">
+				<image class="img" src="https://via.placeholder.com/200x200.png/3c9cff"></image>
+				<image class="img" src="https://via.placeholder.com/200x200.png/f9ae3d"></image>
+				<image class="img" src="https://via.placeholder.com/200x200.png/5ac725"></image>
+				<image class="img" src="https://via.placeholder.com/200x200.png/f56c6c"></image>
+				<image class="img" src="https://via.placeholder.com/200x200.png/909399"></image>
+			</view>
+			<view style="height: 30rpx;"></view>
+			<view class="uv-skeletons__row uv-skeletons__row3">
+				<view class="uv-skeletons__row3--left">
+					<uv-text text="uv-ui破釜沉舟之兼容vue3+2、nvue、app、h5、多端小程序的uni-app生态框架" color="#222" size="30rpx" bold lines="1"></uv-text>
+					<uv-text text="大部分组件基于uView2.x，在经过改进后全面支持vue3，部分组件做了进一步的优化，支持单独导入，方便开发者选择导入需要的组件。" lines="1" color="#222" size="30rpx" margin="8rpx 0 0"></uv-text>
+					<uv-text text="uv-ui来源于社区，也回归到社区，正是有一群热爱uni-app生态的同学推着它前行，而我们也一如既往的承诺，uv-ui永久开源，永远免费。我们会在部分组件下载时配置广告抵消一部分成本，希望大家理解。" lines="1" color="#222" size="30rpx" margin="8rpx 0 0"></uv-text>
+				</view>
+				<view class="uv-skeletons__row3--right">
+					<image class="img" src="https://via.placeholder.com/200x200.png/3c9cff"></image>
+				</view>
+			</view>
+		</uv-skeletons>
+	</view>
+</template>
+<script setup>
+import { ref } from "vue";
+const loading = ref(true);
+const animate = ref(true);
+const skeleton = ref([{
+  type: 'flex',
+  num: 1,
+  children: [{
+    type: 'custom',
+    num: 1,
+    style: 'width:136rpx;height:136rpx;marginRight: 30rpx;'
+  }, {
+    type: 'line',
+    num: 3,
+    style: [null, 'width:360rpx;', 'width:200rpx;']
+  }]
+}, 30, {
+  type: 'flex',
+  children: [{
+    type: 'custom',
+    style: 'width:98rpx;height:160rpx;'
+  }, {
+    type: 'custom',
+    style: 'width:98rpx;height:160rpx;marginLeft:50rpx;'
+  }, {
+    type: 'custom',
+    style: 'width:98rpx;height:160rpx;marginLeft:50rpx;'
+  }, {
+    type: 'custom',
+    style: 'width:98rpx;height:160rpx;marginLeft:50rpx;'
+  }, {
+    type: 'custom',
+    style: 'width:98rpx;height:160rpx;marginLeft:50rpx;'
+  }]
+}, 30, {
+  type: 'flex',
+  children: [{
+    type: 'line',
+    num: 3,
+    gap: '30rpx'
+  }, {
+    type: 'custom',
+    style: 'width:160rpx;height:160rpx;marginLeft: 30rpx;'
+  }]
+}]);
+
+</script>
+<style lang="scss" scoped>
+	.uv-page {
+		padding: 15px 30rpx 40px;
+	}
+	.uv-skeletons__row {
+		/* #ifndef APP-NVUE */
+		display: flex;
+		/* #endif */
+		flex-direction: row;
+	}
+	.uv-skeletons__row1 {
+		&--left {
+			width: 136rpx;
+			height: 136rpx;
+			margin-right: 30rpx;
+			.img {
+				width: 136rpx;
+				height: 136rpx;
+			}
+		}
+		&--right {
+			flex: 1;
+		}
+	}
+	.uv-skeletons__row2 {
+		justify-content: space-between;
+		.img {
+			width: 98rpx;
+			height: 160rpx;
+		}
+	}
+	.uv-skeletons__row3 {
+		&--left {
+			flex: 1;
+		}
+		&--right {
+			.img {
+				width: 160rpx;
+				height: 160rpx;
+			}
+		}
+	}
+</style>
+```
+
+### 完整示例
+
+::: tip 完整示例下载地址
+
+[https://ext.dcloud.net.cn/plugin?name=uv-ui](https://ext.dcloud.net.cn/plugin?name=uv-ui)
+
+:::
+
+### API
+---
+
+### Skeletons Props
+
+| 参数 | 类型 | 默认值 | 说明 |
+|:-|:-|:-|:-|
+| loading | Boolean | true | 是否显示骨架 |
+| animate | Boolean | true | 是否开启动画效果 |
+| skeleton | Array | [] | 骨架内容，具体用法请看下方[Skeleton Options](/components/skeletons.html#skeletons-options)参数说明 |
+
+#### Skeletons Options
+
+该参数非常重要，该配置决定能不能正常显示骨架内容。该参数的格式为：[Object,Number]，Number值代表垂直间隔距离
+
+| 属性名 | 说明 |
+|:-|:-|
+| Object.type | 骨架类型，组件内置了四种：line - 段落结构；avatar - 头像形状；flex - 并列，需要有children属性；custom - 自定义类型，理论上和line、avatar没区别，其实都可以完全自定义样式 | 
+| Object.num | 重复数量，`[{type:'line',num:3}]`意思是3个段落结构骨架 |
+| Object.gap | 骨架下边距，`[{type:'line',num:3,gap: '30rpx'}]`意思是3个段落结构骨架的下边距均为`30rpx`。**注意：只有Object.num大于1才会生效** |
+| Object.style | 骨架样式，类型是Array/Object/String，Array依次对应重复骨架的样式，数组中也可使用Object/String；Object和String代表重复的骨架均用该样式。具体使用参考上述案例 |
+| Number | 表示数组上一项和下一项的间隔距离，单位 `rpx`。上述示例有所体现：[混合布局-插槽内容](/components/skeletons.html#混合布局-插槽内容) |
+
+:::warning 注意
+示例依赖了 `uv-ui` `uv-text` 等多个组件，直接拷贝示例代码将无法正常运行。
+请到 [组件下载页面](https://ext.dcloud.net.cn/plugin?name=uv-skeletons) ，在页面右侧选择 使用 `HBuilderX导入示例项目` 。
+:::
+
+<style scoped>
+h3[id=skeletons-props] + table thead tr th:nth-child(1),
+h3[id=skeletons-props] + table thead tr th:nth-child(2),
+h3[id=skeletons-props] + table thead tr th:nth-child(3)
+{
+	width: 18%;
+}
+h3[id=skeletons-methods] + table thead tr th:nth-child(2)
+{
+	width: 70%;
+}
+h3[id=skeletons-events] + table thead tr th:nth-child(2),
+h3[id=skeletons-events] + table thead tr th:nth-child(3)
+{
+	width: 40%;
+}
+h4[id=skeletons-options] + p + table {
+	width: 80%;
+}
+h4[id=skeletons-options] + p + table thead tr th:nth-child(1)
+{
+	width: 20%;
+}
+h4[id=skeletons-options] + p + table thead tr th:nth-child(2)
+{
+	width: 80%;
+}
+</style>