@gmcb/uv-ui 0.2.27 → 0.3.1

package/docs/components/numberBox.md

@@ -0,0 +1,257 @@
+## NumberBox 步进器 <to-api/>
+
+<demo-model url="/pages/componentsB/numberBox/numberBox"></demo-model>
+
+::: tip ✈
+
+**组件名：uv-number-box**
+
+[点击下载&安装](https://ext.dcloud.net.cn/plugin?name=uv-number-box)
+
+:::
+
+该组件一般用于商城购物选择物品数量的场景
+
+注意：该输入框只能输入大于或等于0的整数
+
+### 平台兼容性
+
+|App（vue）|App（nvue）|H5|小程序|VUE2|VUE3|
+|:-:|:-:|:-:|:-:|:-:|:-:|
+|√|√|√|√|√|√|
+
+### 基本使用
+
+通过`v-model`绑定`value`初始值，此值是双向绑定的，**无需**在回调中将返回的数值重新赋值给`value`。
+
+```vue
+<template>
+	<uv-number-box v-model="value" @change="valChange"></uv-number-box>
+</template>
+<script setup>
+import { ref } from 'vue';
+
+const value = ref(0);
+function valChange(e) {
+  console.log('当前值为: ' + e.value);
+}
+
+</script>
+```
+
+### 步长设置
+
+- 通过`step`属性设置每次点击增加或减少按钮时变化的值，默认为1，下面示例每次都会加2或者减2
+
+```vue
+<uv-number-box :step="2"></uv-number-box>
+```
+
+### 限制输入范围
+
+通过`min`和`max`参数限制输的入值最小值和最大值
+
+```vue
+<uv-number-box :min="1" :max="100"></uv-number-box>
+```
+
+### 限制只能输入整数
+
+通过`integer`限制输入类型
+
+```vue
+<uv-number-box integer></uv-number-box>
+```
+
+### 禁用 
+
+```vue
+<!-- 通过设置`disabled`参数来禁用输入框，禁用状态下无法点击加减按钮或修改输入框的值 -->
+<uv-number-box :disabled="true"></uv-number-box>
+
+<!-- 禁用输入框 -->
+<uv-number-box :disabledInput="true"></uv-number-box>
+
+<!-- 禁用增加按钮 -->
+<uv-number-box :disablePlus="true"></uv-number-box>
+
+<!-- 禁用减少按钮 -->
+<uv-number-box :disableMinus="true"></uv-number-box>
+
+<!-- 禁用长按 -->
+<uv-number-box :longPress="false"></uv-number-box>
+```
+
+### 固定小数位数
+
+通过`step`设置步进长度，`decimal-length`设置显示小数位数
+
+```vue
+<uv-number-box step="0.25" decimal-length="1" ></uv-number-box>
+```
+
+### 异步变更
+
+通过`asyncChange`设置异步变更，开启后需要手动控制输入值 （默认 `false` ）
+
+```vue
+<template>
+	<uv-number-box v-model="value" :asyncChange="true" @change="onChange"></uv-number-box>
+</template>
+<script setup>
+import { ref } from 'vue';
+
+const value = ref(1);
+function onChange(e) {
+  uni.showLoading({
+    title: '加载中',
+    mask: true
+  });
+  setTimeout(() => {
+    value.value = value.value + 1;
+    uni.hideLoading();
+  }, 1000);
+}
+
+</script>
+```
+
+### 自定义颜色和大小
+
+- 通过`button-size`参数设置按钮大小
+- 通过`icon-style`参数设置加减按钮图标的样式
+
+```vue
+<uv-number-box button-size="36" color="#ffffff" bgColor="#2979ff" iconStyle="color: #fff"></uv-number-box>
+```
+
+### 自定义 slot
+
+```vue
+<template>
+	<uv-number-box v-model="value">
+		<template v-slot:minus>
+			<view class="minus">
+				<uv-icon name="minus" size="12">
+				</uv-icon>
+			</view>
+		</template>
+		<template v-slot:input>
+			<text style="width: 50px;text-align: center;" class="input">
+				{{value}}
+			</text>
+		</template>
+		<template v-slot:plus>
+			<view class="plus">
+				<uv-icon name="plus" color="#FFFFFF" size="12">
+				</uv-icon>
+			</view>
+		</template>
+	</uv-number-box>
+</template>
+<script setup>
+import { ref } from 'vue';
+
+const value = ref(1);
+
+</script>
+<style lang="scss">
+	.minus {
+		width: 22px;
+		height: 22px;
+		border-width: 1px;
+		border-color: #E6E6E6;
+		border-style: solid;
+		border-top-left-radius: 100px;
+		border-top-right-radius: 100px;
+		border-bottom-left-radius: 100px;
+		border-bottom-right-radius: 100px;
+		/* #ifndef APP-NVUE */
+		display: flex;
+		/* #endif */
+		justify-content: center;
+		align-items: center;
+	}
+	.input {
+		padding: 0 10px;
+	}
+	.plus {
+		width: 22px;
+		height: 22px;
+		background-color: #FF0000;
+		border-radius: 50%;
+		/* #ifndef APP-NVUE */
+		display: flex;
+		/* #endif */
+		justify-content: center;
+		align-items: center;
+	}
+</style>
+```
+
+### 完整示例
+
+::: tip 完整示例下载地址
+
+[https://ext.dcloud.net.cn/plugin?name=uv-ui](https://ext.dcloud.net.cn/plugin?name=uv-ui)
+
+:::
+
+### API
+---
+
+### NumberBox Props
+
+| 参数			| 说明													| 类型					| 默认值						| 可选值	|
+| :-			| :-													| :-					| :-						| :-	|
+| value / v-model			| 用于双向绑定的值，初始化时设置设为默认min值(最小值)		| String &#124; Number	| 1							| -		|
+| name			| 步进器标识符，在change回调返回							| String &#124; Number	| -							| -		|
+| min			| 用户可输入的最小值										| String &#124; Number	| 1						| -		|
+| max			| 用户可输入的最大值										| String &#124; Number	| `Number.MAX_SAFE_INTEGER`	| -		|
+| step			| 步长，每次加或减的值， 支持小数值，如需小数				| String &#124; Number	| 1							| -		|
+| integer		| 是否只能输入正整数										| Boolean				| false						| true &#124; false	|
+| disabled		| 是否禁用操作，包括输入框，加减按钮						| Boolean				| false						| true &#124; false	|
+| disabledInput	| 是否禁止输入框											| Boolean				| false						| true &#124; false	|
+| asyncChange	| 是否开启异步变更，开启后需要手动控制输入值					| Boolean				| false						| true &#124; false	|
+| inputWidth	| 输入框宽度，单位px										| String &#124; Number	| 35						| -		|
+| showMinus		| 是否显示减少按钮										| Boolean				| true						| true &#124; false	|
+| showPlus		| 是否显示增加按钮										| Boolean				| true						| true &#124; false	|
+| decimalLength	| 显示的小数位数											| String &#124; Number	| -							| -		|
+| longPress		| 是否允许长按进行加减							| Boolean				| true			| true &#124; false	|
+| color			| 输入框文字和加减按钮图标的颜色							| String				| #323233					| -		|
+| buttonSize	| 按钮大小，宽高等于此值，单位px，输入框高度和此值保持一致	| String &#124; Number	| 30						| -		|
+| bgColor		| 输入框和按钮的背景颜色									| String				| #EBECEE					| -		|
+| cursorSpacing	| 指定光标于键盘的距离，避免键盘遮挡输入框，单位px			| String &#124; Number	| 100						| -		|
+| disablePlus	| 是否禁用增加按钮										| Boolean				| false						| true &#124; false	|
+| disableMinus	| 是否禁用减少按钮										| Boolean				| false						| true &#124; false	|
+| iconStyle		| 加减按钮图标的样式										| String				| -							| -		|
+
+
+### NumberBox Events
+
+| 事件名	| 说明											| 回调参数									|
+| :-	| :-											| :-										|
+| @focus	| 输入框得到焦点触发(按钮可点击情况下)，对象形式		| value：输入框当前值，name：步进器标识符		|
+| @blur	| 输入框失去焦点时触发，对象形式			    		| value：输入框当前值，name：步进器标识符		|
+| @change| 输入框内容发生变化时触发，对象形式		    		| value：输入框当前值，name：步进器标识符        |
+| @overlimit	| 超过范围阈值时触发                     		| type：（`minus`已达最小值，`plus`已达最大值）	|
+
+### NumberBox Slots
+
+| 名称	| 说明		|
+| :-	| :-		|
+| minus	| 减少按钮	|
+| input	| 输入框		|
+| plus	| 增加按钮	|
+
+<style scoped>
+h3[id=numberbox-events] + table thead tr th:nth-child(2){
+	width: 40%;
+}
+h3[id=numberbox-events] + table thead tr th:nth-child(3){
+	width: 40%;
+}
+h3[id=numberbox-slots] + table thead tr th:nth-child(2){
+	width: 70%;
+}
+</style>

package/docs/components/nvue.md

@@ -0,0 +1,170 @@
+## Nvue特性相关
+
+前言：uv-ui在1.x版本，只有部分组件支持`nvue`，不推荐在`nvue`项目中使用，目前uv-ui研发组正在研发2.0版本，将会全面兼容`nvue`，我们在这里做一个专题，列出一些`nvue`上的坑，希望能帮助到您。
+
+
+### Text组件
+
+- 我们在`vue`中，可以将文本相关的内容放到`view`或者`text`组件，这都是没问题的，但是在`nvue`中，需要动态响应(双向绑定)的内容，必须放在`text`标签，如果放在`view`可以正常显示，但是无法双向绑定。
+
+- 在`nvue`中，文本的样式无法继承父元素的颜色(color)，必须具体到给每一个`text`元素定义类名，在通过指定的类名给赋予颜色值，其他类似出现不能继承父组件的情况，也可参考此做法。
+
+- 在`nvue`中，`text`组件不能换行写内容，否则会出现无法去除的周边空白内容(类似被加上了`padding`或者`margin`的效果)，如下：
+
+```html
+<!-- nvue中错误写法 -->
+<text>
+    桃花潭水深千尺
+</text>
+
+<!-- nvue中正确写法 -->
+<text>不及汪伦送我情</text>
+```
+
+
+### 事件冒泡
+
+`weex`事件冒泡相关文档 —— [事件冒泡](https://weex.apache.org/zh/docs/events/event-bubbling.html#%E9%98%BB%E6%AD%A2%E5%86%92%E6%B3%A1)  
+
+在`weex`原文中，需要给给页面(组件)根元素设置`bubble="true"`才能产生事件冒泡机制，但是在`uni-app`的`nvue`中，已自动加上类似`bubble="true"`的操作，无需用户额外干预，自动就会获得事件冒泡的机制。另外，在nvue中，我们可以通过如下方式阻止事件冒泡：
+
+```html
+<template>
+    <view @tap="parentClick">
+        <text @tap="childClick">
+    </view>
+</template>
+
+<script setup>
+function childClick(e) {
+	console.log('内部被点击');
+	e.stopPropagation();
+}
+
+function parentClick() {
+	console.log('父元素将不会捕获冒泡事件');
+}
+</script>
+```
+
+
+### line-height
+
+在`nvue`中，`line-height`与字体大小`font-size`无关，如果赋予数值，单位默认为`px`，这意味着不可以如下使用：
+
+```css
+.box {
+    /* vue正常，nvue中会导致行高只有1px */
+    line-height: 1;
+}
+```
+
+### 样式穿透
+
+在`weex`(`nvue`)中有如此描述：[在 Weex 里， 每一个 Vue 组件的样式都是 scoped](https://weex.apache.org/zh/guide/use-vue-in-weex.html#%E5%B9%B3%E5%8F%B0%E7%9A%84%E5%B7%AE%E5%BC%82)，这说明`vue`中的的`/deep/`和`::v-deep`在`nvue`中都是无效，修改子组件样式只能通过传参进行，而不能进行样式穿透。
+
+
+### 字体引入不能加引号
+
+`nvue`下，`font-family`的字体引入，不能加引号，否则会导致字体图标无法显示，如下：
+
+```css
+/* 错误写法 */
+font-family: 'uicon-iconfont';
+
+/* 正确写法 */
+font-family:con-iconfont;
+```
+
+### Nvue不支持部分全局应用配置
+
+在 `nvue` 中，不建议依赖 `main.js` 中的全局混入或全局属性。如有需要，可以在每一个 `nvue` 文件中独立引入组合式函数：
+
+```js
+// composables/useExample.js
+export function useExample() {
+	function doSomething() {
+		// ...
+	}
+
+	return {
+		doSomething
+	};
+}
+```
+
+```vue
+<script setup>
+import { useExample } from '@/composables/useExample.js';
+
+const { doSomething } = useExample();
+</script>
+```
+
+
+### Scss中的:export无效
+
+在`vue`中，我们可以通过`*.scss`中使用[:export](https://www.jianshu.com/p/069f4f79de16)进行变量导出，供`js`和`css`共同使用变量，但是`nvue`中不支持此写法，请勿使用。
+
+
+### transition属性不能简写
+
+在`vue`中，我们可以很方便的简写`transition`属性，但是`nvue`中，必须分开写才有效，如下：
+
+- [weex文档关于transition的描述](https://weex.apache.org/zh/docs/styles/common-styles.html#transition)
+
+```css
+/* 如下写法，vue有效，nvue无效 */
+transition: opacity 0.3s ease-in;
+
+/* nvue页面需要拆分成如下写法 */
+transition-property: opacity;
+transition-duration: 0.3s;
+transition-timing-function: ease-in;
+```
+
+
+### box-shadow
+
+据关于[weex关于box-shadow文档](https://weex.apache.org/zh/docs/styles/common-styles.html#%E9%98%B4%E5%BD%B1-box-shadow)描述，`weex`不支持`android`上的`box-shadow`属性，但是经实测，在`nvue`(uni-app改良后台的`weex`)上`android`，是支持的`box-shadow`属性效果的。
+
+需要说明的是，在`IOS`上，目前(2020-10-30)不允许将`box-shadow`值设置为`none`，否则会出现锐利的高亮白色边框，由于`nvue`支持`rgba`透明度，我们可以通过如下方式实现类似`none`的效果：
+
+```css
+.box {
+    box-shadow: 0 0 0 0 rgba(0, 0, 0, 0)
+}
+```
+
+
+### border-radius
+
+[在`weex`文档中有明确的说明](https://weex.apache.org/zh/docs/styles/common-styles.html#border-radius)，`border-radius`支持简写形式，但是在`nvue`的`android`端，`border-radius`必须分开写才有效，如下：
+
+```css
+/* nvue下，安卓不支持此写法 */
+.box {
+    border-radius: 10px;
+}
+
+/* 必须如下写法才能兼容 */
+.box {
+    border-bottom-left-radius: 10px;
+    border-bottom-right-radius: 10px;
+    border-top-left-radius: 10px;
+    border-top-right-radius: 10px;
+}
+```
+
+
+### 关于<template\/> 和 <block\/>
+
+以下文字取自uni-app文档原文，[点此查看](https://uniapp.dcloud.io/frame?id=template-block)：
+
+```
+`<template/>` 和 `<block/>` 并不是一个组件，它们仅仅是一个包装元素，不会在页面中做任何渲染，只接受控制属性。  
+`<block/>` 在不同的平台表现存在一定差异，推荐统一使用 `<template/>`。
+```
+
+上面说，二者不会在页面做任何的渲染，但是在`nvue`中，`<block/>`确确实实被渲染成为一个`<block/>`元素，由于`nvue`默认`flex`布局，且为
+`column`竖向布局，这可能会导致`<block/>`标签下存在多个其他元素时，这些元素会竖向排列，您不得不额外对`<block/>`元素设置样式，所以我们建议只要是`nvue`的场景，一律使用`<template/>`而不是`<block/>` 标签

package/docs/components/overlay.md

@@ -0,0 +1,117 @@
+## Overlay 遮罩层 <to-api/>
+
+<demo-model url="/pages/componentsC/overlay/overlay"></demo-model>
+
+::: tip ✈
+
+**组件名：uv-overlay**
+
+[点击下载&安装](https://ext.dcloud.net.cn/plugin?name=uv-overlay)
+
+:::
+
+创建一个遮罩层，用于强调特定的页面元素，并阻止用户对遮罩下层的内容进行操作，一般用于弹窗场景，`uv-popup`、`uv-toast`、`uv-tooltip`等组件就是用了该组件
+
+### 平台兼容性
+
+|App（vue）|App（nvue）|H5|小程序|VUE2|VUE3|
+|:-:|:-:|:-:|:-:|:-:|:-:|
+|√|√|√|√|√|√|
+
+### 基本使用
+
+- 通过`show`参数配置是否显示遮罩  
+- 遮罩被点击时，会发送一个`click`事件，如不需要此事件，请设置`mask-click-able`参数为`false`
+
+```vue
+<template>
+	<uv-overlay :show="show" @click="show = false"></uv-overlay>
+</template>
+<script setup>
+import { ref } from 'vue';
+
+const show = ref(true);
+
+</script>
+```
+
+### 嵌入内容
+
+通过默认插槽可以在遮罩层上嵌入任意内容  
+注意：如果不想让`slot`插槽内容的点击事件冒泡到遮罩，请给指定元素添加上`@tap.stop`
+
+```vue
+<template>
+	<uv-overlay :show="show" @click="show = false">
+		<view class="warp">
+			<view class="rect" @tap.stop></view>
+		</view>
+	</uv-overlay>
+</template>
+<script setup>
+import { ref } from 'vue';
+
+const show = ref(true);
+
+</script>
+<style scoped>
+	.warp {
+		display: flex;
+		align-items: center;
+		justify-content: center;
+		height: 100%;
+	}
+
+	.rect {
+		width: 120px;
+		height: 120px;
+		background-color: #fff;
+	}
+</style>
+```
+
+### 遮罩样式
+
+- 通过`duration`设置遮罩淡入淡出的时长，单位`ms`
+
+```vue
+<uv-overlay :show="true" :duration="400" :z-index ="999" :opacity="0.3"></uv-overlay>
+```
+
+### 完整示例
+
+::: tip 完整示例下载地址
+
+[https://ext.dcloud.net.cn/plugin?name=uv-ui](https://ext.dcloud.net.cn/plugin?name=uv-ui)
+
+:::
+
+### API
+---
+
+### Overlay Props
+
+| 参数		| 说明								| 类型					| 默认值	| 可选值	|
+| :-		| :-								| :-					| :-	| :-	|
+| show		| 是否显示遮罩						| Boolean				| false	| true &#124; false	|
+| zIndex	| `z-index`层级						| String &#124; Number	| 10070	| -		|
+| duration	| 动画时长，单位毫秒`ms`					| String &#124; Number	| 300	| -		|
+| opacity	| 不透明度值，当做rgba的第四个参数		| String &#124; Number	| 0.5	| -		|
+
+### Overlay Events
+
+| 事件名	| 说明				| 回调参数	|
+| :-	| :-				| :-		|
+| @click	| 点击遮罩发送此事件	| -			|
+
+### Overlay Slots
+
+| 名称		| 说明								|
+| :-		| :-								|
+| default	| 默认插槽，用于在遮罩层上方嵌入内容	|
+
+<style scoped>
+h3[id=overlay-slots] + table thead tr th:nth-child(2){
+	width: 70%;
+}
+</style>