@gmcb/uv-ui 0.2.26 → 0.3.0

package/docs/components/backTop.md

@@ -0,0 +1,181 @@
+## BackTop 返回顶部 <to-api/>
+
+<demo-model url="/pages/componentsD/backtop/backtop"></demo-model>
+
+::: tip ✈
+
+**组件名：uv-back-top**
+
+[点击下载&安装](https://ext.dcloud.net.cn/plugin?name=uv-back-top)
+
+:::
+
+该组件一个用于长页面，滑动一定距离后，出现返回顶部按钮，点击按钮快速返回顶部的场景。
+
+
+### 平台兼容性
+
+|App（vue）|App（nvue）|H5|小程序|VUE2|VUE3|
+|:-:|:-:|:-:|:-:|:-:|:-:|
+|√|√|√|√|√|√|
+
+### 基本使用
+
+由于返回顶部需要实时监听滚动条的位置，从而判断返回的按钮该出现还是隐藏，由于组件无法得知页面的滚动条信息，只能在**页面**的`onPageScroll`生命周期中获得滚动条的位置。故需要在页面监听`onPageScroll`生命周期，实时获得滚动条的位置，通过Props传递给组件。
+
+::: warning 注意
+1. `nvue` 页面需要给页面最外层元素设置 `ref='uv-back-top'`
+2. `onPageScroll` 周期函数中获取值也有些区别，`nvue`中为`e.detail.scrollTop`，`vue`中为`e.scrollTop`
+:::
+
+```vue
+<template>
+	<view class="wrap" ref="backTop">
+		<text>滑动页面，返回顶部按钮将出现在右下角</text>
+		<uv-back-top :scroll-top="scrollTop"></uv-back-top>
+	</view>
+</template>
+<script setup>
+import { ref } from 'vue';
+
+const backTop = ref(null);
+const scrollTop = ref(0);
+
+</script>
+<style lang="scss" scoped>
+	.wrap {
+		height: 2000px;
+	}
+</style>
+```
+
+
+### 改变返回顶部按钮的出现时机
+
+通过`top`属性设置页面滚动多少距离时，出现返回顶部的按钮
+
+```vue
+<template>
+	<view class="wrap" style="height: 2000px;" ref="backTop" top="600">
+		<text>滑动页面，返回顶部按钮将出现在右下角</text>
+		<uv-back-top :scroll-top="scrollTop"></uv-back-top>
+	</view>
+</template>
+<script setup>
+import { ref } from 'vue';
+
+const backTop = ref(null);
+const scrollTop = ref(0);
+
+</script>
+```
+
+### 自定义返回顶部的图标和提示
+
+- 通过`icon`属性设置返回顶部按钮的图标，可以是`uv-ui`内置的图标，或者图片路径
+- 通过`text`属性设置返回顶部按钮的文字提示信息，如果需要修改文字的颜色和大小，可以通过`customStyle`参数
+
+```vue
+<template>
+	<view class="wrap" style="height: 2000px;" ref="backTop" top="600">
+		<text>滑动页面，返回顶部按钮将出现在右下角</text>
+		<uv-back-top :scroll-top="scrollTop" icon="arrow-up" text="返回"></uv-back-top>
+	</view>
+</template>
+<script setup>
+import { ref } from 'vue';
+
+const backTop = ref(null);
+const scrollTop = ref(0);
+
+</script>
+```
+
+### 其他自定义样式
+
+- 通过`iconStyle`属性自定义图标的样式，比如颜色，大小等
+- 通过`customStyle`属性设置返回按钮的背景颜色，大小等
+- 通过`mode`属性设置按钮的形状，`circle`为圆形，`square`为方形
+
+::: warning 注意
+如果通过`icon`参数传入图片路径的话，需要通过`iconStyle`参数设置图片的`width`和`height`属性
+:::
+
+```vue
+<template>
+	<view class="wrap" style="height: 2000px;" ref="backTop" top="600">
+		<text>滑动页面，返回顶部按钮将出现在右下角</text>
+		<uv-back-top 
+			:scroll-top="scrollTop" 
+			icon="arrow-up" 
+			text="返回"
+			:mode="mode"
+			:iconStyle="iconStyle"
+			:customStyle="customStyle"
+		></uv-back-top>
+	</view>
+</template>
+<script setup>
+import { ref } from 'vue';
+
+const backTop = ref(null);
+const scrollTop = ref(0);
+const mode = ref('square');
+const customStyle = ref({
+  fontSize: '24rpx',
+  color: '#2979ff'
+});
+const iconStyle = ref({
+  fontSize: '32rpx',
+  color: '#2979ff'
+});
+
+</script>
+```
+
+### 完整示例
+
+::: tip 完整示例下载地址
+
+[https://ext.dcloud.net.cn/plugin?name=uv-ui](https://ext.dcloud.net.cn/plugin?name=uv-ui)
+
+:::
+
+### API
+---
+
+### BackTop Props
+
+| 参数			| 说明					| 类型					| 默认值		|  可选值	|
+|:-				|:-						|:-						|:-				|:-			|
+| mode			| 按钮形状，`circle`为圆形，`square`为方形 | String				| circle		| circle &#124; square	|
+| icon			| `uv-ui`内置图标名称，或图片路径				| String				| arrow-upward	| -			|
+| text			| 返回顶部按钮的提示文字						| String				| -				| -			|
+| duration		| 返回顶部过程中的过渡时间，单位`ms`				| String &#124; Number	| 100			| -			|
+| scrollTop		| 页面的滚动距离，通过`onPageScroll`生命周期获取| String &#124; Number	| 0				| -			|
+| top			| 滚动条滑动多少距离时显示，单位`px(rpx)`				| String &#124; Number	| 400			| -			|
+| bottom		| 返回按钮位置到屏幕底部的距离，单位`px(rpx)`			| String &#124; Number	| 100			| -			|
+| right			| 返回按钮位置到屏幕右边的距离，单位`px(rpx)`	| String &#124; Number	| 20			| -			|
+| z-index		| 返回顶部按钮的层级						| String &#124; Number	| 9				| -			|
+| iconStyle		| 图标的样式，对象形式					| Object				| -				| -			|
+| customStyle	| 按钮外层的自定义样式					| Object				| -				| -			|
+
+### BackTop Methods
+| 方法名								| 说明					| 
+| :-| :-	|
+| backToTop	| 自定义内容的时，可以调用此方法返回顶部	 |
+
+### BackTop Slots
+
+|名称	|说明						|
+|:-		|:-							|
+| default	| 自定义返回按钮的所有内容		|
+
+<style scoped>
+h3[id=backtop-slots] + table thead tr th:nth-child(2){
+	width: 70%;
+}
+h3[id=backtop-methods] + table thead tr th:nth-child(2){
+	width: 70%;
+}
+</style>

package/docs/components/badge.md

@@ -0,0 +1,117 @@
+## Badge 徽标数（数字角标） <to-api/>
+
+<demo-model url="/pages/componentsD/badge/badge"></demo-model>
+
+::: tip ✈
+
+**组件名：uv-badge**
+
+[点击下载&安装](https://ext.dcloud.net.cn/plugin?name=uv-badge)
+
+:::
+
+该组件一般用于显示未读的消息或数量提示，可以配合`uv-tabs`、`uv-vtabs`等组件使用。有圆点和圆包含文字两种形式，默认`error`背景色。
+
+### 平台兼容性
+
+|App（vue）|App（nvue）|H5|小程序|VUE2|VUE3|
+|:-:|:-:|:-:|:-:|:-:|:-:|
+|√|√|√|√|√|√|
+
+### 基本使用
+
+- 通过`value`参数定义徽标内容
+- 通过`type`设置主题。重申一次，uv-ui中，所有组件的`type`参数都只有5个固定的可选值，分别是`primary`(蓝色-主色)，`warning`(黄色-警告)，
+`error`(红色-错误)，`success`(绿色-成功)，`info`(灰色-信息)
+- 通过`max`参数控制最大值，超过最大值会显示 '{max}+'
+
+```vue
+<template>
+	<view style="padding: 20px;">
+		<view class="box">
+			<uv-badge type="error" max="99" :value="100"></uv-badge>
+		</view>
+	</view>
+</template>
+<style lang="scss" scoped>
+	.box {
+		width: 50px;
+		height: 50px;
+		background-color: #909193;
+	}
+</style>
+```
+
+### 设置徽标的类型为一个圆点
+
+通过`:isDot="true"`属性设置，该形式组件没有内容，只显示一个圆点
+
+```vue
+<uv-badge :isDot="true" type="success"></uv-badge>
+```
+
+### 设置数字的显示方式 `overflow` `ellipsis` `limit`
+
+- `overflow`会根据max字段判断，超出显示`${max}+`
+- `ellipsis`会根据max判断，超出直接显示`...`
+- `limit`会依据1000作为判断条件，超出1000，显示`${value/1000}K`，比如2.2k、3.34w，最多保留2位小数
+
+```vue
+<template>
+	<view style="padding: 20px;">
+		<view class="box">
+			<uv-badge numberType="overflow" type="error" max="99" :value="100"></uv-badge>
+		</view>
+		<view class="box">
+			<uv-badge numberType="ellipsis" type="error" max="99" :value="10000"></uv-badge>
+		</view>
+		<view class="box">
+			<uv-badge numberType="limit" type="error" max="99" :value="100"></uv-badge>
+		</view>
+	</view>
+</template>
+<style lang="scss" scoped>
+	.box {
+		width: 50px;
+		height: 50px;
+		background-color: #909193;
+	}
+</style>
+```
+
+### 完整示例
+
+::: tip 完整示例下载地址
+
+[https://ext.dcloud.net.cn/plugin?name=uv-ui](https://ext.dcloud.net.cn/plugin?name=uv-ui)
+
+:::
+
+### API
+---
+
+### Badge Props
+
+| 参数		| 说明																								| 类型					| 默认值		|  可选值							|
+|:-			|:-																									|:-						|:-			|:-									|
+| value		| 展示的数字，大于 `max` 时显示为 `${max}+`；为`0`且`show-zero`为`false`时隐藏			| String &#124; Number	| -			| -									|
+| isDot		| 不展示数字，只有一个小点																				| Boolean				| false		| true &#124; false								|
+| show		| 组件是否显示																						| Boolean				| true		| true &#124; false								|
+| max		| 最大值，超过最大值会显示 '{max}+'																		| String &#124; Number	| 99		| -									|
+| type		| 主题类型																							| String				| error		| error &#124; warning &#124; success &#124; primary &#124; info|
+| showZero	| 当数值为 0 时，是否展示 Badge																			| Boolean				| false		| true	&#124; false							|
+| bgColor	| 背景颜色，优先级比`type`高。如设置该属性，`type`参数就会失效														| String				| -			| -									|
+| color		| 字体颜色																							| String				| #ffffff	| -									|
+| shape		| 徽标形状，circle-四角均为圆角，horn-左下角为直角														| String				| circle	| circle &#124; horn								|
+| numberType| 置数字的显示方式，详细见上方文档																		| String				| overflow	| overflow &#124; ellipsis &#124; limit					|
+| inverted	| 是否反转背景和字体颜色																				| Boolean				| false		| true	&#124; false							|
+| absolute	| 组件是否绝对定位，为`true`时，`offset`参数才有效														| Boolean				| false		| true	&#124; false				|
+| offset	| 设置badge的位置偏移，格式为 [x, y]，也即设置的为`top`和`right`的值，`absolute`为`true`时有效				| Array					| -			| -									|
+| customStyle | 自定义外部样式 | Object | - | - |
+
+
+<style scoped>
+h3[id=badge-props] + table thead tr th:nth-child(2){
+	width: 40%;
+}
+</style>

package/docs/components/button.md

@@ -0,0 +1,196 @@
+## Button 按钮 <to-api/>
+
+<demo-model url="/pages/componentsA/button/button"></demo-model>
+
+::: tip ✈
+
+**组件名：uv-button**
+
+[点击下载&安装](https://ext.dcloud.net.cn/plugin?name=uv-button)
+
+:::
+
+该组件内部实现以uni-app`button`组件为基础，进行二次封装，主要区别在于：
+- 按钮`type`值有更多的主题颜色
+- 按钮`size`值有更多的尺寸可选
+
+### 平台兼容性
+
+|App（vue）|App（nvue）|H5|小程序|VUE2|VUE3|
+|:-:|:-:|:-:|:-:|:-:|:-:|
+|√|√|√|√|√|√|
+
+:::warning 注意事项
+
+> 为了避免错误使用，给大家带来不好的开发体验，请在使用组件前仔细阅读下面的注意事项，可以帮你避免一些错误。
+1. 本组件在 `button` 组件基础上扩展更多实用功能，部分属性与官方组件属性完全一致，由于 `button` 组件比较特殊，它有一些其他小程序平台的特定能力，更详细说明请参uni-app方文档：[uni-app之button组件](https://uniapp.dcloud.io/component/button)。 
+2. 由于微信小程序的限制，在微信小程序中设置了 `form-type` 的 `uv-button` 无法触发 `form` 组件的 `@submit` 事件(H5和APP正常)，详见微信小程序文档[Bug & Tip部分](https://developers.weixin.qq.com/miniprogram/dev/component/button.html)。
+3. 如果需要给 `uv-button` 设置宽度，建议给按钮外面套一个view元素，控制view的宽度，或者使用 `customStyle` 属性进行设置。
+:::
+
+### 基本使用
+文字内容通过`text`传入
+
+```vue
+<uv-button text="月落"></uv-button>
+```
+
+### 设置按钮的多种形态
+
+- `type`值可选的有`default`(默认)、`primary`、`success`、`info`、`warning`、`error`
+- 通过`plain`值设置是否镂空
+- 通过`hairline`值设置是否细边
+- 通过`disabled`值设置是否禁用
+- 通过`loading`值设置是否开启加载图标，`loadingText`设置加载中文字
+- 通过`icon`值设置是否显示图标
+- 通过`shape`值设置按钮形状，circle为圆角
+- 通过`color`值设置按钮渐变颜色
+- 通过`size`值设置按钮的大小
+
+```vue
+<template>
+	<view style="padding: 20px;">
+		<uv-button type="primary" text="确定"></uv-button>
+		<uv-button type="primary" :plain="true" text="镂空"></uv-button>
+		<uv-button type="primary" :plain="true" :hairline="true" text="细边"></uv-button>
+		<uv-button type="primary" :disabled="disabled" text="禁用"></uv-button>
+		<uv-button type="primary" loading loadingText="加载中"></uv-button>
+		<uv-button type="primary" icon="map" text="图标按钮"></uv-button>
+		<uv-button type="primary" shape="circle" text="按钮形状"></uv-button>
+		<uv-button text="渐变色按钮" color="linear-gradient(to right, rgb(66, 83, 216), rgb(213, 51, 186))"></uv-button>
+		<uv-button type="primary" size="small" text="大小尺寸"></uv-button>
+	</view>
+</template>
+<script setup>
+import { ref } from 'vue';
+
+const disabled = ref(true);
+
+</script>
+```
+
+### 定义需要用到的外部样式
+
+1. 针对非微信小程序平台，组件的根元素就是uni-app`button`组件，所以修改按钮的样式很容易，直接给组件定义`类名`或者嵌入`内联样式`即可。  
+2. 如果是微信小程序，编译后页面会有组件同名的元素存在，导致样式传递有问题。 
+3. 如果是为了修改按钮与其他元素之间的距离或者宽度等，可以给按钮外面套一个`view`元素，控制这个`view`与其他元素的距离或者宽度，即可达到同等效果。  
+
+所以：我们提供了一个`custom-style`参数，推荐用户可以用对象形式传递样式给组件内部，注意驼峰命名。
+
+```vue
+<template>
+	<view>
+		<uv-button :custom-style="customStyle" color="#fff" text="雪月夜"></uv-button>
+	</view>
+</template>
+<script setup>
+import { computed } from 'vue';
+
+const customStyle = computed(() => {
+  return {
+    height: '80rpx',
+    background: '#3c9cff',
+    color: '#fff',
+    borderRadius: '40rpx',
+    //圆角
+    // nvue中必须是下方的写法
+    'border-top-right-radius': '40rpx',
+    'border-bottom-left-radius': '40rpx',
+    'border-bottom-right-radius': '40rpx'
+  };
+});
+
+</script>
+```
+
+
+### 各家小程序开放能力的对接
+
+`uv-ui`已对接`uni-app`档关于[uni-app方button组件](https://uniapp.dcloud.net.cn/component/button)的所有开放能力(截止2023-06-29)`uni-app`文档说明使用即可，如果有发现遗漏的地方，请加群反馈。
+
+### 完整示例
+
+::: tip 完整示例下载地址
+
+[https://ext.dcloud.net.cn/plugin?name=uv-ui](https://ext.dcloud.net.cn/plugin?name=uv-ui)
+
+:::
+
+### API
+---
+
+### Button Props
+
+
+|属性名					|说明																					|类型					|默认值	|可选值	|
+|:-						|:-																						|:-						|:-		|:-		|
+|hairline				|是否显示按钮的细边框																		|Boolean				|true	| true &#124; false	|
+|type					|按钮的样式类型																			|String					|info	|info &#124; primary &#124; error &#124; warning &#124; success	|
+|size					|按钮的大小																				|String					|normal |normal &#124; large &#124; mini	|
+|shape					|按钮外观形状，见[上方说明](/components/button.html#设置按钮的多种形态)																	|String					|square	|square &#124; circle	|
+|plain					|按钮是否镂空，背景色透明																	|Boolean				|false	|true &#124; false	|
+|disabled				|是否禁用																				|Boolean				|false	|true &#124; false	|
+|loading				|按钮名称前是否带 loading 图标															|Boolean				|false	|true &#124; false	|App-nvue 平台，在 ios 上为雪花，Android上为圆圈|
+|loadingText			|加载中提示文字																			|String					|-		|-		|
+|loadingMode			|加载状态图标类型																			|String					|spinner| 更多值参考[LoadingIcon模式类型](https://www.uvui.cn/components/loadingIcon.html#%E6%A8%A1%E5%BC%8F%E7%B1%BB%E5%9E%8B) |
+|loadingSize			|加载图标大小																				|String &#124; Number	|15		|-		|
+|openType				|开放能力，具体请看uniapp稳定关于button组件部分说明[uni-app方button组件](https://uniapp.dcloud.net.cn/component/button)										|String					|-		|-		|
+|formType				|用于 \<form\> 组件，点击分别会触发 \<form\> 组件的 submit/reset 事件						|String					|-		|-		|
+|appParameter			|打开 APP 时，向 APP 传递的参数，open-type=launchApp时有效 （注：只微信小程序、QQ小程序有效）	|String					|-		|-		|
+|hoverStopPropagation	|指定是否阻止本节点的祖先节点出现点击态，微信小程序有效（默认 true）							|Boolean				|true	| true &#124; false	|
+|lang					|指定返回用户信息的语言，zh_CN 简体中文，zh_TW 繁体中文，en 英文								|String					|en		|-		|
+|sessionFrom			|会话来源，openType="contact"时有效														|String					|-		|-		|
+|sendMessageTitle		|会话内消息卡片标题，openType="contact"时有效												|String					|-		|-		|
+|sendMessagePath		|会话内消息卡片点击跳转小程序路径，openType="contact"时有效									|String					|-		|-		|
+|sendMessageImg			|会话内消息卡片图片，openType="contact"时有效												|String					|-		|-		|
+|showMessageCard		|是否显示会话内消息卡片，设置此参数为 true，用户进入客服会话会在右下角显示"可能要发送的小程序"提示，用户点击后可以快速发送小程序消息，openType="contact"时有效	|String	|-	|-	|-	|
+|dataName				|额外传参参数，用于小程序的data-xxx属性，通过target.dataset.name获取							|String					|-		|-		|
+|throttleTime			|节流，一定时间内只能触发一次，单位毫秒														|String &#124; Number	|0		|-		|
+|hoverStartTime			|按住后多久出现点击态，单位毫秒																|String &#124; Number	|0		|-		|
+|hoverStayTime			|手指松开后点击态保留时间，单位毫秒															|String &#124; Number	|200	|-		|
+|text					|按钮文字，之所以通过props传入，是因为slot传入的话（注：nvue中无法控制文字的样式）				|String &#124; Number	|-		|-		|
+|icon					|按钮图标																				|String					|-		|-		|
+|iconSize	<badge text="1.0.9"/>				|按钮图大小																				|String &#124; Number					|-		|-		|
+|iconColor				|按钮颜色																				|String					| 在`plain=true`镂空状态下，颜色与边框保持一致，否则为白色（主题为info时为黑色#000000）		|-		|
+|color					|按钮颜色，支持传入linear-gradient渐变色													|String					|-		|-		|
+| customTextStyle | 自定义按钮文字的样式，避免设置customStyle设置覆盖不了样式的情况 | Object &#124; String | - | - | 
+|customStyle			|定义需要用到的外部样式,详细见上方文档														|Object &#124; String					|-		|-		|
+
+### Button Events
+
+**说明**：目前经测试(Hbuilder X 2.6.8)，在H5，APP，可以直接对组件监听`tap`事件，等同组件内部发出的`click`事件效果，某些HX版本上，
+微信小程序对组件使用`tap`事件可能无效，故建议对按钮组件的点击事件监听统一使用组件内部发出的`click`事件。
+
+|属性名			|说明																				|类型	|默认值		|平台差异说明	|
+|:-				|:-																					|:-		|:-			|:-		|
+|@click			|按钮点击，请勿使用`@tap`点击事件，微信小程序无效，返回值为点击事件及参数					|Handler|-			|-		|
+|@getphonenumber	|获取用户手机号回调，open-type="getPhoneNumber"生效													|Handler|-		|微信、支付宝、百度、抖音、快手、京东小程序	|
+|@getuserinfo	|用户点击该按钮时，会返回获取到的用户信息，从返回参数的detail中获取到的值同uni.getUserInfo，open-type="getUserInfo"生效	|Handler|-		|微信、QQ、百度、快手、京东小程序	|
+|@error			|当使用开放能力时，发生错误的回调	，open-type="launchApp"生效													|Handler|-		|微信、QQ、快手、京东小程序	|
+|@opensetting	|从小程序打开 App 成功的回调，open-type="launchApp"生效															|Handler|-		|微信、QQ、百度、快手、京东小程序	|
+|@launchapp		|打开 APP 成功的回调，open-type="launchApp"生效																	|Handler|-		|微信、QQ、快手、京东小程序	|
+|@contact		|客服消息回调，open-type="contact"生效																	|Handler|-		|微信、QQ、百度、快手小程序	|
+|@chooseavatar		|获取用户头像回调，open-type="chooseAvatar"生效																|Handler|-		|微信小程序	|
+|@agreeprivacyauthorization		| 用户同意隐私协议事件回调，open-type="agreePrivacyAuthorization"时有效 |Handler|-		|微信小程序2.33.0	|
+|@addgroupapp		|添加群应用的回调，open-type="addGroupApp"生效																|Handler|-		|QQ小程序	|
+|@chooseaddress		|调起用户编辑并选择收货地址的回调，open-type="chooseAddress"生效																	|Handler|-		|百度小程序	|
+|@chooseinvoicetitle		|用户选择发票抬头的回调，open-type="chooseInvoiceTitle"生效																	|Handler|-		|百度小程序	|
+|@subscribe		|订阅消息授权回调，open-type="subscribe"生效																	|Handler|-		|百度小程序	|
+|@login		|登录回调，open-type="login"生效																	|Handler|-		|百度小程序|
+|@im		| 监听跳转IM的成功回调，open-type="im"生效			|Handler|-		|抖音小程序2.68.0版本+	|
+
+关于`open-type`属性的设置及回调详情，请参考`uniapp`官方提供的[button](https://uniapp.dcloud.net.cn/component/button.html#button)
+
+
+### Button Slots
+|名称 | 说明 |
+|:- |:-	|
+| default | 默认插槽，按钮文本，建议统一使用text参数，保证样式的统一性 |
+| suffix | 后置插槽，方便在按钮文字后面增加图标等 |
+
+<style scoped>
+h3[id=button-slots] + table thead tr th:nth-child(2)
+{
+	width: 80%;
+}
+</style>