@gmcb/uv-ui 0.2.27 → 0.3.1

package/docs/components/vtabs.md

@@ -0,0 +1,332 @@
+## Vtabs 垂直选项卡 <to-api/>
+
+<demo-model url="/pages/componentsD/vtabs/vtabs"></demo-model>
+
+::: tip ✈
+
+**组件名：uv-vtabs**
+
+[点击下载&安装](https://ext.dcloud.net.cn/plugin?name=uv-vtabs)
+
+:::
+
+该组件主要用于分类选择，开箱即用，简单配置参数即可使用，左右自动进行联动，不用自己再去做复杂的计算，组件内部已经完成相关计算。联动和不联动两种可选方式，联动-左右均可滚动，不联动-右边区域只会在选中时显示。
+
+### 平台兼容性
+
+|App（vue）|App（nvue）|H5|小程序|VUE2|VUE3|
+|:-:|:-:|:-:|:-:|:-:|:-:|
+|√|√|√|√|√|√|
+
+### 使用案例1-联动
+
+- 通过设置`chain=true`开启联动，联动即是：右边区域展示全部内容，并且滚动时左边选项自动定位选中项。
+- 该用法需要配合`uv-vtabs-item`使用，且需要将内容部分循环渲染，这样才能达到联动效果，具体使用参考下方案例。
+- 如果头部有内容，必须传`hdHeight`参数，否则会导致联动时计算不准确；头部没有内容不需要传该参数，默认为0。
+
+```vue
+<template>
+	<view class="content">
+		<view style="height: 100rpx;background: #ecf5ff;color: #909193;display: flex;justify-content: center;text-align: center;">
+			<text style="font-size: 28rpx;">欢迎使用多功能组件uv-vtabs，这是头部内容，有头部内容必须传hdHeight参数</text>
+		</view>
+		<uv-vtabs
+			:chain="chain"
+			:list="list"
+			:height="height"
+			hdHeight="100rpx"
+			@change="change">
+			<template v-for="(item,index) in list" :key="index">
+				<uv-vtabs-item :index="index">
+					<view class="item"
+						v-for="(item2,index2) in item.childrens"
+						:key="index2">
+						<view class="item-title">
+							<text class="text">{{item2.name}}</text>
+						</view>
+						<view class="item-content">
+							<text class="text">{{item2.desc}}</text>
+						</view>
+					</view>
+					<view 
+						class="gap"
+						v-if="index<list.length-1">
+						<uv-gap bg-color="#f1f1f1" height="4"></uv-gap>
+					</view>
+				</uv-vtabs-item>
+			</template>
+			<uv-gap bg-color="#fff" height="600"></uv-gap>
+		</uv-vtabs>
+	</view>
+</template>
+
+<script setup>
+import { ref, computed } from "vue";
+import { onReady } from "@dcloudio/uni-app";
+const getList = [{
+  name: 'uv-ui简介',
+  childrens: [{
+    name: 'uv-ui简介',
+    desc: '1. uv-ui最初是在uview2.x的基础上进行改进优化，支持vue3等优化，最重要的是支持单独导入直接使用，无需在main.js中进行配置。\n\n2. uv-ui来源于社区，也回归到社区，正是有一群热爱uni-app生态的同学推着它前行，而我们也一如既往的承诺，uv-ui永久开源，永远免费。但是会在下载处进行广告配置，作为开发团队的研发费用的部分来源，所以希望大家理解。'
+  }]
+}, {
+  name: 'uv-ui特点',
+  childrens: [{
+    name: '全端兼容',
+    desc: 'uv-ui 支持 App（vue）、App（nvue）、H5、小程序和 Vue 3，支持 nvue 原生渲染。uv-ui 的组件都是多端自适应的，底层会抹平很多小程序平台的差异或 bug。'
+  }, {
+    name: '集成工具',
+    desc: '@gmcb/uv-ui 包集成了网络请求 HTTP 及常用工具函数，无需自己再去寻找，并且直接挂载在uni上面，方便使用，只需要在mian.js中引入即可，更多工具请参考：https://www.uvui.cn/api/request/http.html。使用方式请参考：https://www.uvui.cn/components/setting.html。'
+  }, {
+    name: '主题扩展',
+    desc: '@gmcb/uv-ui 包中的 theme.scss 为主题文件，直接在uni.scss中引入主题即可，可以根据自己的需求进行扩展。下面也有说明具体使用方式。使用方法请参考：https://www.uvui.cn/components/setting.html'
+  }]
+}, {
+  name: '更新日志',
+  badge: {
+    show: true,
+    value: 5
+  },
+  childrens: [{
+    name: '更新日志',
+    desc: 'uv-ui的重大更新在更新日志中都有所说明，如果在开发的过程中遇到文档不完善，可以提供给我们，我们会持续完善，非常感谢大家的支持。更新日志：https://www.uvui.cn/components/changelog.html'
+  }]
+}, {
+  name: '设计规范',
+  childrens: [{
+    name: '设计规范',
+    desc: '为了约束合成更多优秀的组件和模板，打造优质的体验，我们拟定了一些UI界面设计和建议。同时部分之间会有依赖，这是为了减少代码冗余的同时提高开发效率，模块化是我们的基础。如果大家有好的建议，可以提出进行改进。'
+  }]
+}, {
+  name: '交流反馈',
+  childrens: [{
+    name: '交流反馈',
+    desc: 'uv-ui为采用MIT许可证的开源项目，使用完全免费。欢迎加QQ群交流反馈，一起学习，共同进步。QQ群： 549833913'
+  }]
+}];
+const list = ref([]);
+const chain = ref(true);
+const height = computed(() => {
+  return uni.getSystemInfoSync().windowHeight - uni.upx2px(100);
+});
+function change(index) {
+  console.log('选项改变：', index);
+}
+onReady(() => {
+  // 模拟接口请求数据
+  uni.showLoading({
+    title: '加载中'
+  });
+  setTimeout(() => {
+    list.value = getList;
+    uni.hideLoading();
+  }, 500);
+});
+
+</script>
+<style scoped lang="scss">
+	.header {
+		padding: 30rpx;
+		font-size: 30rpx;
+		color: #333;
+	}
+	.item {
+		padding: 10rpx 20rpx;
+		&-title {
+			.text {
+				font-weight: 700;
+				font-size: 32rpx;
+				color: #111;
+			}
+		}
+		&-content {
+			padding: 20rpx 0;
+			.text {
+				line-height: 48rpx;
+				font-size: 30rpx;
+				color: #111;
+				/* #ifndef APP-NVUE */
+				word-break: break-all;
+				/* #endif */
+			}
+		}
+	}
+	.gap {
+		padding: 0 30rpx;
+	}
+</style>
+```
+
+### 使用案例2-不联动
+
+- 通过设置`chain=false`关闭联动，联动即是：右边区域展示全部内容，并且滚动时左边选项自动定位选中项。
+- 该用法需要配合`uv-vtabs-item`使用，需要手动处理右边渲染的数据，具体使用参考下方案例。
+
+```vue
+<template>
+	<view class="content">
+		<uv-vtabs 
+			:chain="chain"
+			:list="list"
+			:barItemBadgeStyle="{right:'20px',top:'12px'}"
+			@change="change">
+			<uv-vtabs-item>
+				<view 
+					class="item"
+					v-for="(item2,index2) in list2"
+					:key="index2">
+					<view class="item-title">
+						<text class="text">{{item2.name}}</text>
+					</view>
+					<view class="item-content">
+						<text class="text">{{item2.desc}}</text>
+					</view>
+				</view>
+			</uv-vtabs-item>
+		</uv-vtabs>
+	</view>
+</template>
+
+<script setup>
+import { ref, computed } from "vue";
+import { onReady } from "@dcloudio/uni-app";
+const getList = [{
+  name: 'uv-ui简介',
+  childrens: [{
+    name: 'uv-ui简介',
+    desc: '1. uv-ui最初是在uview2.x的基础上进行改进优化，支持vue3等优化，最重要的是支持单独导入直接使用，无需在main.js中进行配置。\n\n2. uv-ui来源于社区，也回归到社区，正是有一群热爱uni-app生态的同学推着它前行，而我们也一如既往的承诺，uv-ui永久开源，永远免费。但是会在下载处进行广告配置，作为开发团队的研发费用的部分来源，所以希望大家理解。'
+  }]
+}, {
+  name: 'uv-ui特点',
+  childrens: [{
+    name: '全端兼容',
+    desc: 'uv-ui 支持 App（vue）、App（nvue）、H5、小程序和 Vue 3，支持 nvue 原生渲染。uv-ui 的组件都是多端自适应的，底层会抹平很多小程序平台的差异或 bug。'
+  }, {
+    name: '集成工具',
+    desc: '@gmcb/uv-ui 包集成了网络请求 HTTP 及常用工具函数，无需自己再去寻找，并且直接挂载在uni上面，方便使用，只需要在mian.js中引入即可，更多工具请参考：https://www.uvui.cn/api/request/http.html。使用方式请参考：https://www.uvui.cn/components/setting.html。'
+  }, {
+    name: '主题扩展',
+    desc: '@gmcb/uv-ui 包中的 theme.scss 为主题文件，直接在uni.scss中引入主题即可，可以根据自己的需求进行扩展。下面也有说明具体使用方式。使用方法请参考：https://www.uvui.cn/components/setting.html'
+  }]
+}, {
+  name: '更新日志',
+  badge: {
+    isDot: true
+  },
+  childrens: [{
+    name: '更新日志',
+    desc: 'uv-ui的重大更新在更新日志中都有所说明，如果在开发的过程中遇到文档不完善，可以提供给我们，我们会持续完善，非常感谢大家的支持。更新日志：https://www.uvui.cn/components/changelog.html'
+  }]
+}, {
+  name: '设计规范',
+  childrens: [{
+    name: '设计规范',
+    desc: '为了约束合成更多优秀的组件和模板，打造优质的体验，我们拟定了一些UI界面设计和建议。同时部分之间会有依赖，这是为了减少代码冗余的同时提高开发效率，模块化是我们的基础。如果大家有好的建议，可以提出进行改进。'
+  }]
+}, {
+  name: '交流反馈',
+  childrens: [{
+    name: '交流反馈',
+    desc: 'uv-ui为采用MIT许可证的开源项目，使用完全免费。欢迎加QQ群交流反馈，一起学习，共同进步。QQ群： 549833913'
+  }]
+}];
+const list = ref([]);
+const chain = ref(false);
+const value = ref(0);
+const list2 = computed(() => {
+  const _list = list.value[value.value]?.childrens;
+  return _list ? _list : [];
+});
+function change(index) {
+  console.log('选项改变：', index);
+  value.value = index;
+}
+onReady(() => {
+  // 模拟接口请求数据
+  uni.showLoading({
+    title: '加载中'
+  });
+  setTimeout(() => {
+    list.value = getList;
+    uni.hideLoading();
+  }, 200);
+});
+
+</script>
+<style scoped
+	lang="scss">
+	.header {
+		padding: 30rpx;
+		font-size: 30rpx;
+		color: #333;
+	}
+	.item {
+		padding: 10rpx 20rpx;
+		&-title {
+			.text {
+				font-weight: 700;
+				font-size: 32rpx;
+				color: #111;
+			}
+		}
+		&-content {
+			padding: 20rpx 0;
+			.text {
+				line-height: 48rpx;
+				font-size: 30rpx;
+				color: #111;
+				/* #ifndef APP-NVUE */
+				word-break: break-all;
+				/* #endif */
+			}
+		}
+	}
+	.gap {
+		padding: 0 30rpx;
+	}
+</style>
+```
+
+### 完整示例
+
+::: tip 完整示例下载地址
+
+[https://ext.dcloud.net.cn/plugin?name=uv-ui](https://ext.dcloud.net.cn/plugin?name=uv-ui)
+
+:::
+
+### API
+---
+
+### Vtabs Props 
+
+| 参数			| 说明	| 类型		| 默认值	| 可选值	|
+| :-			| :- | :-		| :-	| :-	|
+| list | 选项数组，元素为对象，如`[{name:'uv-ui简介'}]`。元素对象中可设置徽标显示，如`[{name:'更新日志', badge: {isDot: true}}]`，设置更多参数参考[uv-badge](/components/badge.html)组件。 | Array | [] | - |
+| keyName | 从list元素对象中读取的键名 | String | name | - |
+| current | 当前选中项，从0开始 | Number | 0 | - |
+| hdHeight `1.0.4` | 头部内容的高度，头部有内容必传，否则会有联动误差 | Number &#124; String | 0 | - |
+| chain | 是否开启联动，开启后右边区域可以滑动查看内容。注意：`chain=true`时`VtabsItem`的`index`属性必传，见下方。 | Boolean | true | true &#124; false |
+| height | 整个列表的高度，默认auto或空则为屏幕高度 | Number|String | 屏幕高度`sys().windowHeight` | - |
+| barWidth | 左边选项区域的宽度 | Number|String | 180rpx | - |
+| barScrollable | 左边选项区域是否允许滚动 | Boolean | true | true &#124; false |
+| barBgColor | 左边选项区域的背景颜色 | String | $uv-bg-color | - |
+| barStyle | 左边选项区域的自定义样式 | Object | - | - |
+| barItemStyle | 左边选项区域「每个」选项的自定义样式 | Object | - | - |
+| barItemActiveStyle | 左边选项区域「选中」选项的自定义样式 | Object | - | - |
+| barItemActiveLineStyle | 左边选项区域「选中选项竖线条」的自定义样式，如设置竖条颜色，需设置背景色：`:bar-item-active-line-style="{background: '#2878FF'}"` | Object | - | - |
+| barItemBadgeStyle | 左边选项区域选中选项徽标的自定义样式，**主要用于调整徽标位置**，案例见上面 [使用案例2-不联动](/components/vtabs.html#使用案例2-不联动) | Object | - | - |
+| contentStyle | 右边区域自定义样式 | Object | - | - |
+
+### VtabsItem Props 
+
+| 参数			| 说明	| 类型		| 默认值	| 可选值	|
+| :-			| :- | :-		| :-	| :-	|
+| index | 内容区索引值，`chain=true`开启时必传，具体传值详情在示例中查看 | Number &#124; String | 0 | - |
+
+### Vtabs Events
+
+|事件名		|说明											|回调参数	|
+|:-			|:-												|:-			|
+| @change | 选择改变时触发 | 选项索引值 |
+| @scrolltolower `1.0.4` | 内容滚动到底部触发 | 选项索引值 |

package/docs/components/vueUse.md

@@ -0,0 +1,45 @@
+## 简要介绍 app.use 的原理
+
+uv-ui 会努力做好框架的内容，同时我们也希望您能学习到一些更深入的知识。
+
+在 uni-app Vue 3 项目中，插件通常在 `createApp()` 中通过 `app.use()` 注册：
+
+```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 };
+}
+```
+
+这里我们把 `uvUI` 传递给了 `app.use()`。Vue 3 会检查插件对象是否提供 `install` 方法，如果有，就调用它，并把当前应用实例 `app` 作为第一个参数传入。简化后的逻辑可以理解为：
+
+```js
+app.use = function (plugin, ...options) {
+	if (typeof plugin.install === 'function') {
+		plugin.install(app, ...options);
+	} else if (typeof plugin === 'function') {
+		plugin(app, ...options);
+	}
+
+	return app;
+}
+```
+
+有了上面的分析，我们知道 uv-ui 内部会定义一个 `install` 方法。Vue 3 插件通常会在这个方法里注册全局能力：
+
+```js
+const install = app => {
+	app.config.globalProperties.$uv = uni.$uv;
+};
+
+export default {
+	install
+};
+```
+
+注册后，项目中可以优先通过 `uni.$uv.xxx` 使用工具能力；在组件实例内，也可以通过实例代理访问 `$uv`。

package/docs/components/vuexDetail.md

@@ -0,0 +1,103 @@
+## Vue 3 中简化 Vuex 写法的基本原理
+
+`vuex` 传统写法简单，但是也很繁琐：
+
+1. 我们需要在`vuex`中定义`state`和`mutations`
+2. 我们需要在每个用到 `vuex` 变量的地方，都引入 `useStore`，再通过 `computed` 暴露给模板
+3. 修改`vuex`变量的时候，还需要通过`commit`提交
+4. 由于`vuex`变量是保存在运行内存中的，刷新浏览器`vuex`变量会消失，还需要通过其他手段实现变量的存续
+
+- 针对上面的第1点，我们写了一个统一的`mutations`，用于更新所有的`state`变量，这样可以免去每个变量都要写一个对应的`mutations`步骤，同时在
+这个统一的`mutations`中，根据配置判断是否在变量更新的时候，把它存进本地`Local Storage`，这样H5刷新或者APP下次启动，就会自动把这些变量赋值给
+`state`
+
+具体实现如下(当然，这可能不是最优的写法)
+
+```js
+// store/index.js
+
+import { createStore } from 'vuex';
+import { getProperty, setProperty } from '@gmcb/uv-ui/libs/function/index.js';
+
+function saveLifeData(key, value) {
+	uni.setStorageSync(key, value);
+}
+
+const store = createStore({
+	state: {
+		user: {
+			name: ''
+		},
+		version: ''
+	},
+	mutations: {
+		uvStore(state, payload) {
+			setProperty(state, payload.name, payload.value);
+			const saveKey = payload.name.split('.')[0];
+			saveLifeData(saveKey, getProperty(state, saveKey));
+		}
+	}
+});
+
+export default store;
+```
+
+- 针对上面第二点，Vue 3 推荐封装组合式函数，在需要的页面中显式引入。这样依赖关系更清晰，也不会把状态注入到所有页面。
+
+```js
+// composables/useUvStore.js
+import { computed } from 'vue';
+import { useStore } from 'vuex';
+
+export function useUvStore(keys = []) {
+	const store = useStore();
+	const state = {};
+
+	keys.forEach(key => {
+		state[key] = computed(() => store.state[key]);
+	});
+
+	function uvStore(name, value) {
+		store.commit('uvStore', {
+			name,
+			value
+		});
+	}
+
+	return {
+		...state,
+		uvStore
+	};
+}
+```
+
+
+- 针对上面的第3点，因为我们通过统一的`mutations`的去更新`state`，自然就需要一个统一方法去触发`mutations`，用以替代原来的`commit`方法，
+可以在页面中通过组合式函数统一调用：
+
+```vue
+<template>
+	<view>
+		<view>{{ user.name }}</view>
+		<uv-button @click="updateName">修改姓名</uv-button>
+	</view>
+</template>
+
+<script setup>
+import { useUvStore } from '@/composables/useUvStore.js';
+
+const { user, uvStore } = useUvStore(['user']);
+
+function updateName() {
+	uvStore('user.name', '史诗');
+}
+</script>
+```
+
+当我们要修改某一个 `state` 值的时候，就调用 `uvStore('name', value)`。如果项目规模较大，也可以直接使用 Pinia，避免继续扩展 Vuex 的全局写法。
+
+- 针对第4点，其实已经在第1点中解决了。
+
+上面的做法，只是抛砖引玉的做了一个思路的解析，如果您有更好的思路，也可以和我们分享。
+
+说明：确保您是新项目的情况下，或者您对这个实现方法很清楚，才使用这个方法。