@gmcb/uv-ui 0.2.27 → 0.3.0

package/docs/components/transition.md

@@ -0,0 +1,404 @@
+## Transition 动画 <to-api/>
+
+<demo-model url="/pages/componentsA/transition/transition"></demo-model>
+
+::: tip ✈
+
+**组件名：uv-transition**
+
+[点击下载&安装](https://ext.dcloud.net.cn/plugin?name=uv-transition)
+
+:::
+
+该组件用于元素的动画过渡效果，丰富的内置动画，支持自定义动画。
+
+### 平台兼容性
+
+|App（vue）|App（nvue）|H5|小程序|VUE2|VUE3|
+|:-:|:-:|:-:|:-:|:-:|:-:|
+|√|√|√|√|√|√|
+
+### 基本使用
+
+通过`show`属性设置动画的打开和关闭
+
+```vue
+<template>
+	<button type="default" @click="open">fade</button>
+	<uv-transition 
+		:show="show" 
+		:custom-style="{'width':'100px','height':'100px','backgroundColor':'#3c9cff'}" 
+		@change="change">
+	</uv-transition>
+</template>
+<script setup>
+import { ref } from 'vue';
+
+const show = ref(false);
+function open() {
+  show.value = !show.value;
+}
+function change(e) {
+  console.log('动画触发：', e);
+}
+
+</script>
+
+```
+
+### 动画模式
+
+通过`mode`属性设置动画的模式，默认`fade`。 比如设置`mode="zoom-in"`能达到由小到大过渡
+效果，更多模式见下[Mode Options](/components/transition.html#mode-options)
+
+```vue
+<template>
+	<button type="default" @click="open">fade</button>
+	<uv-transition 
+		:show="show" 
+		mode="zoom-in"
+		:custom-style="{'width':'100px','height':'100px','backgroundColor':'#3c9cff'}" 
+		@change="change">
+	</uv-transition>
+</template>
+<script setup>
+import { ref } from 'vue';
+
+const show = ref(false);
+function open() {
+  show.value = !show.value;
+}
+function change(e) {
+  console.log('动画触发：', e);
+}
+
+</script>
+```
+
+### 自定义动画
+
+当内置动画类型不能满足需求的时候，可以使用 `step()` 和 `run()` 自定义动画，入参以及具体用法参考下方属性说明
+
+`init()` 方法可以覆盖默认配置。方法及属性详情[参考下方](/components/transition.html#transition-methods)。
+
+```vue
+<template>
+	<view>
+		<button type="primary" @click="run">执行动画</button>
+		<uv-transition 
+            ref="ani" 
+            :custom-style="{'width':'100px','height':'100px','backgroundColor':'#3c9cff'}" 
+            :show="show"  />
+	</view>
+</template>
+
+<script setup>
+import { ref } from 'vue';
+import { onReady } from '@dcloudio/uni-app';
+
+const ani = ref(null);
+const show = ref(true);
+onReady(() => {
+  ani.value.init({
+    duration: 1000,
+    timingFunction: 'linear',
+    transformOrigin: '50% 50%',
+    delay: 500
+  });
+});
+function run() {
+  // 同时右平移到 100px,旋转 360 读
+  ani.value.step({
+    translateX: '100px',
+    rotate: '360'
+  });
+  // 上面的动画执行完成后，等待200毫秒平移到 0px,旋转到 0 读
+  ani.value.step({
+    translateX: '0px',
+    rotate: '0'
+  }, {
+    timingFunction: 'ease-in',
+    duration: 200
+  });
+  // 开始执行动画
+  ani.value.run(() => {
+    console.log('动画支持完毕');
+  });
+}
+
+</script>
+```
+
+### 完整示例
+
+::: tip 完整示例下载地址
+
+[https://ext.dcloud.net.cn/plugin?name=uv-ui](https://ext.dcloud.net.cn/plugin?name=uv-ui)
+
+:::
+
+### API
+---
+
+### Transition Props
+
+| 参数			| 说明							| 类型					| 默认值		|  可选值	|
+|:-				|:-								|:-						|:-			|:-			|
+| show			| 控制组件显示或关闭					| Boolean				| false		| true &#124; false		|
+| mode			| 内置过渡动画类型					| String				| fade		| 见下[Mode Options](/components/transition.html#mode-options)		|
+| duration		| 动画的执行时间，单位`ms`			| String &#124; Number	| 300		| -			|
+| timingFunction| 使用的动画过渡函数，[详见](/components/transition.html#timingfunction属性说明)	| String | ease-out	| - |
+| customClass	| 自定义类名						| String				| -			| -			|
+| cellChild | 是否属于cell节点下。`nvue`模式下的该组件在cell或uv-list等组件下使用，该值最好是设置成true，避免回收后不显示的BUG。 | Boolean | false | true &#124; false|
+| customStyle	| 自定义样式						| Object				| -			| -			|
+
+### Mode Options
+
+**格式为：** `'fade'` 或者 `['fade','slide-top']`
+
+**注意：** 组合使用时，同一种类型相反的过渡动画如（slide-top、slide-bottom）同时使用时，只有最后一个生效
+
+| 属性值	| 说明	|
+| :-	| :- |
+| fade | 渐隐渐出过渡 |
+| slide-top | 由上至下过渡 |
+| slide-bottom | 由下至上过渡 |
+| slide-left | 由左至右过渡 |
+| slide-right | 由右至左过渡 |
+| zoom-in | 由小到大过渡 |
+| zoom-out | 由大到小过渡 |
+
+### Transition Events
+
+| 事件名			| 说明		| 回调参数	|
+| :-			| :-		| :-		|
+| @click	| 点击组件触发	| -			|
+| @change | 过渡动画结束时触发		|  e = {detail:true &#124; false} |
+
+### Transition Methods
+
+| 方法名 | 说明 | 回调参数 |
+| :- | :- | :- |
+| init() | 手动初始化配置 | Function(OBJECT:config) |
+| step() | 动画队列	 | Function(OBJECT:type,OBJECT:config) |
+| run() | 执行动画	 | Function(FUNCTION:callback) |
+
+### init(OBJECT:config) 初始化
+
+- 通过`ref`调用该方法
+- 手动设置动画配置，需要在页面渲染完毕后调用
+
+```js
+const ani = ref(null);
+
+ani.value?.init({
+	duration: 1000,
+	timingFunction: 'linear',
+	transformOrigin: '50% 50%',
+	delay: 500
+})
+```
+
+### step(OBJECT:type,OBJECT:config) 动画队列
+
+- 通过`ref`调用该方法
+- 调用 `step()` 来表示一组动画完成，`step` 第一个参数可以传入任意多个动画方法，一组动画中的所有动画会同时开始，一组动画完成后才会进行下一组动画。`step` 第二个参数可以传入一个跟 `uni.createAnimation()` 一样的配置参数用于指定当前组动画的配置。
+- 第一个参数支持的动画参考下面的 [支持的动画](/components/transition.html#timingfunction属性说明)
+- 第二个参数参考下面的 [动画配置](/components/transition.html#动画配置)，可省略，如果省略继承`init()`的配置
+```js
+// 上平移到 100px，同时旋转到 90 度
+const ani = ref(null);
+
+ani.value?.step({
+	translateX: '100px',
+	rotate: '90'
+},
+{
+	timingFunction: 'ease-in',
+	duration: 200
+})
+```
+
+### run(FUNCTION:callback) 执行动画
+
+- 通过`ref`调用该方法
+- 在执行 `step()` 后，需要调用 `run()` 来运行动画 ，否则动画会一直等待
+- `run()` 方法可以传入一个 `callback` 函数 ，会在所有动画执行完毕后回调
+
+```js
+// 开始执行动画，结束回调
+const ani = ref(null);
+
+ani.value?.run(() => {
+	console.log('动画支持完毕')
+})
+```
+
+### 动画配置
+
+动画配置 ， `init()` 与 `step()` 第二个参数配置相同 ，如果配置`step()`第二个参数，将会覆盖 `init()` 的配置
+
+| 属性名 | 类型  | 默认值 | 说明 | 平台差异 |
+| :- | :- | :- | :- | :- |
+| duration | Number | 400 | 动画持续时间，单位`ms` | - |
+| timingFunction | String | "linear" | - |
+| delay | Number | 0 | 动画延迟时间，单位`ms` | - |
+| needLayout | Boolean | false | 动画执行是否影响布局 | 仅 nvue 支持 |
+| transformOrigin | String | "center center" | 设置 [transform-origin](https://developer.mozilla.org/en-US/docs/Web/CSS/transform-origin) | - |
+
+### timingFunction属性说明
+
+| 属性名 | 说明  | 平台差异 |
+| :- | :- | :- |
+| linear | 动画从头到尾的速度是相同的 | - |
+| ease | 动画以低速开始，然后加快，在结束前变慢 | - |
+| ease-in	 | 动画以低速开始 | - |
+| ease-in-out | 动画以低速开始和结束 | - |
+| ease-out | 动画以低速结束 | - |
+| step-start | 动画第一帧就跳至结束状态直到结束 | nvue不支持 |
+| step-end | 动画一直保持开始状态，最后一帧跳到结束状态 | nvue不支持 |
+
+### 支持的动画
+
+- 调用 `step()` 来表示一组动画完成
+- 如果同一个动画方法有多个值，多个值使用数组分隔
+
+```js
+const ani = ref(null);
+
+ani.value?.step({
+	width:'100px',
+	scale: [1.2,0.8],
+})
+```
+
+#### **样式：**
+
+|属性名|类型|说明|平台差异|
+|:-|:-|:-|:-|
+|opacity	|Number|	透明度，参数范围 0~1|	-|
+|backgroundColor	|Number &#124; String|	颜色值|	-|
+|width	|Number &#124; String|	长度值，如果传入 Number 则默认使用 px，可传入其他自定义单位的长度值|	-|
+|height	|Number &#124; String|	长度值，如果传入 Number 则默认使用 px，可传入其他自定义单位的长度值|	-|
+|top	|Number &#124; String|	长度值，如果传入 Number 则默认使用 px，可传入其他自定义单位的长度值|	nvue 不支持|
+|left	|Number &#124; String|	长度值，如果传入 Number 则默认使用 px，可传入其他自定义单位的长度值|	nvue 不支持|
+|bottom	|Number &#124; String|	长度值，如果传入 Number 则默认使用 px，可传入其他自定义单位的长度值|	nvue 不支持|
+|right	|Number &#124; String|	长度值，如果传入 Number 则默认使用 px，可传入其他自定义单位的长度值|	nvue 不支持|
+
+```js
+const ani = ref(null);
+
+ani.value?.step({
+	opacity: 1,
+	backgroundColor: '#3c9cff',
+	widht:'100px',
+	height:'50rpx',
+})
+```
+
+#### **旋转：**
+
+旋转属性的值不需要填写单位
+
+|属性名|值|说明|平台差异|
+|:-|:-|:-|:-|
+|rotate|	deg	|deg的范围-180~180，从原点顺时针旋转一个deg角度|	-|
+|rotateX|	deg|	deg的范围-180~180，在X轴旋转一个deg角度|	-|
+|rotateY|	deg|	deg的范围-180~180，在Y轴旋转一个deg角度|	-|
+|rotateZ	deg|	deg的范围-180~180，在Z轴旋转一个deg角度|	nvue不支持|
+|rotate3d|	x,y,z,deg|	同 transform-function rotate3d|	nvue不支持|
+
+```js
+const ani = ref(null);
+
+ani.value?.step({
+	rotateX: 45,
+	rotateY: 45
+})
+```
+
+#### **缩放：**
+
+|属性名|值|说明|平台差异|
+|:-|:-|:-|:-|
+|scale|	sx,[sy]|	一个参数时，表示在X轴、Y轴同时缩放sx倍数；两个参数时表示在X轴缩放sx倍数，在Y轴缩放sy倍数|	-|
+|scaleX|	sx|	在X轴缩放sx倍数|	-|
+|scaleY|	sy|	在Y轴缩放sy倍数|	-|
+|scaleZ|	sz|	在Z轴缩放sy倍数	|nvue不支持|
+|scale3d|	sx,sy,sz|	在X轴缩放sx倍数，在Y轴缩放sy倍数，在Z轴缩放sz倍数|	nvue不支持|
+
+```js
+const ani = ref(null);
+
+ani.value?.step({
+	scale: [1.2,0.8]
+})
+```
+
+#### **偏移：**
+
+|属性名|值|说明|平台差异|
+|:-|:-|:-|:-|
+|translate|	tx,[ty]|	一个参数时，表示在X轴偏移tx，单位px；两个参数时，表示在X轴偏移tx，在Y轴偏移ty，单位px。	|-|
+|translateX|	tx|	在X轴偏移tx，单位px|	-|
+|translateY|	ty|	在Y轴偏移tx，单位px|	-|
+|translateZ|	tz|	在Z轴偏移tx，单位px|	nvue不支持|
+|translate3d|	tx,ty,tz|	在X轴偏移tx，在Y轴偏移ty，在Z轴偏移tz，单位px|	nvue不支持|
+
+```js
+const ani = ref(null);
+
+ani.value?.step({
+	translateX: '100px'
+})
+```
+<style scoped>
+h3[id=transition-events] + table thead tr th:nth-child(2){
+	width: 40%;
+}
+h3[id=mode-options] + table {
+	width: auto;
+}
+h3[id=mode-options] + p + p + table thead tr th:nth-child(2){
+	width: 60%;
+}
+h3[id=动画配置] + p + table thead tr th:nth-child(2){
+	width: 20%;
+}
+h3[id=动画配置] + p + table thead tr th:nth-child(4){
+	width: 25%;
+}
+h3[id=timingfunction属性说明] + table thead tr th:nth-child(2){
+	width: 50%;
+}
+h4[id=样式] + table thead tr th:nth-child(2){
+	width: 15%;
+}
+h4[id=样式] + table thead tr th:nth-child(3){
+	width: 50%;
+}
+h4[id=旋转] + p + table thead tr th:nth-child(2){
+	width: 15%;
+}
+h4[id=旋转] + p + table thead tr th:nth-child(3){
+	width: 50%;
+}
+h4[id=旋转] + p + table thead tr th:nth-child(2){
+	width: 15%;
+}
+h4[id=旋转] + p + table thead tr th:nth-child(3){
+	width: 50%;
+}
+h4[id=缩放]  + table thead tr th:nth-child(2){
+	width: 15%;
+}
+h4[id=缩放]  + table thead tr th:nth-child(3){
+	width: 50%;
+}
+h4[id=偏移]  + table thead tr th:nth-child(2){
+	width: 15%;
+}
+h4[id=偏移]  + table thead tr th:nth-child(3){
+	width: 50%;
+}
+</style>

package/docs/components/upload.md

@@ -0,0 +1,253 @@
+## Upload 上传 <to-api/>
+
+<demo-model url="/pages/componentsB/upload/upload"></demo-model>
+
+::: tip ✈
+
+**组件名：uv-upload**
+
+[点击下载&安装](https://ext.dcloud.net.cn/plugin?name=uv-upload)
+
+:::
+
+该组件用于上传图片、视频等文件场景。
+
+一般用于表单处的情况较多，可以配合表单使用，具体案例参考：[实战案例-配合uv-upload上传进行验证-4](https://www.uvui.cn/components/form.html#实战案例-配合uv-upload上传进行验证-4)
+
+### 平台兼容性
+
+|App（vue）|App（nvue）|H5|小程序|VUE2|VUE3|
+|:-:|:-:|:-:|:-:|:-:|:-:|
+|√|√|√|√|√|√|
+
+### 基础用法
+
+可以通过设置`fileList`参数(数组，元素为对象)，显示预置的图片。其中元素的`url`属性为图片路径
+
+```vue
+<template>
+	<uv-upload
+		:fileList="fileList1"
+		name="1"
+		multiple 
+		:maxCount="10"
+		@afterRead="afterRead" 
+		@delete="deletePic" 
+	></uv-upload>
+</template>
+<script setup>
+import { ref } from 'vue';
+
+const fileList1 = ref([]);
+function deletePic(event) {
+  this[`fileList${event.name}`].splice(event.index, 1);
+}
+async function afterRead(event) {
+  // 当设置 multiple 为 true 时, file 为数组格式，否则为对象格式
+  let lists = [].concat(event.file);
+  let fileListLen = this[`fileList${event.name}`].length;
+  lists.map(item => {
+    this[`fileList${event.name}`].push({
+      ...item,
+      status: 'uploading',
+      message: '上传中'
+    });
+  });
+  for (let i = 0; i < lists.length; i++) {
+    const result = await uploadFilePromise(lists[i].url);
+    let item = this[`fileList${event.name}`][fileListLen];
+    this[`fileList${event.name}`].splice(fileListLen, 1, Object.assign(item, {
+      status: 'success',
+      message: '',
+      url: result
+    }));
+    fileListLen++;
+  }
+}
+function uploadFilePromise(url) {
+  return new Promise((resolve, reject) => {
+    let a = uni.uploadFile({
+      url: 'http://192.168.2.21:7001/upload',
+      // 仅为示例，非真实的接口地址
+      filePath: url,
+      name: 'file',
+      formData: {
+        user: 'test'
+      },
+      success: res => {
+        setTimeout(() => {
+          resolve(res.data.data);
+        }, 1000);
+      }
+    });
+  });
+}
+
+</script>
+```
+
+### 上传视频
+
+通过设置`accept='video'`属性，将上传改为视频上传。
+
+```vue
+<template>
+	<uv-upload :fileList="[]" name="2" multiple :maxCount="10" accept="video"></uv-upload>
+</template>
+```
+
+### 文件预览
+
+通过设置`:previewFullImage="true"'`属性，达到文件预览的目的。
+
+```vue
+<template>
+	<uv-upload :fileList="fileList" name="3" multiple :maxCount="10" :previewFullImage="true"></uv-upload>
+</template>
+<script setup>
+import { ref } from 'vue';
+
+const fileList = ref([{
+  url: 'https://cdn.uviewui.com/uview/swiper/1.jpg'
+}]);
+
+</script>
+```
+
+### 隐藏上传按钮 / 限制上传数量
+
+上传数量等于`maxCount`所规定的数据时，隐藏上传按钮。
+
+```vue
+<template>
+	<uv-upload :fileList="fileList" name="3" :maxCount="1" multiple :previewFullImage="true"></uv-upload>
+</template>
+<script setup>
+import { ref } from 'vue';
+
+const fileList = ref([{
+  url: 'https://cdn.uviewui.com/uview/swiper/1.jpg'
+}, {
+  url: 'https://cdn.uviewui.com/uview/swiper/2.jpg'
+}]);
+
+</script>
+```
+
+### 自定义上传样式
+
+添加`image`以自定义上传样式，达到身份证，银行卡等不同场景需求。
+
+```vue
+<template>
+	<uv-upload 
+		:fileList="[]" 
+		name="6" 
+		multiple 
+		:maxCount="1" 
+		width="250" 
+		height="150">
+		<image 
+			src="https://cdn.uviewui.com/uview/demo/upload/positive.png" 
+			mode="widthFix" 
+			style="width: 250px;height: 150px;"
+		></image>
+	</uv-upload>
+</template>
+```
+
+### 完整示例
+
+::: tip 完整示例下载地址
+
+[https://ext.dcloud.net.cn/plugin?name=uv-ui](https://ext.dcloud.net.cn/plugin?name=uv-ui)
+
+:::
+
+### API
+---
+
+### Upload Props
+
+| 参数				| 说明																				| 类型					| 默认值						|  可选值					|
+|:-					|:-																					|:-						|:-							|:-							|
+| fileList			| 显示已上传的文件列表，列表中具体参数参考[FileList Options](/components/upload.html#filelist-options) | Array	 | - | - 	|
+| accept			| 接受的文件类型，`file`只支持`H5`（只有微信小程序才支持把accept配置为all、media）			| String				| image						| all &#124; media &#124; image &#124; file &#124; video|
+| capture			| 图片或视频拾取模式，当accept为image类型时设置capture可选额外camera可以直接调起摄像头		| String &#124; Array	| ['album', 'camera']		| -							|
+| compressed		| 当accept为video时生效，是否压缩视频，默认为true										| Boolean				| true						| true &#124; false						|
+| camera			| 当accept为video时生效，可选值为back或front											| String				| back						| -							|
+| maxDuration		| 当accept为video时生效，拍摄视频最长拍摄时间，单位秒						    			| Number				| 60						| true	&#124; false					|
+| uploadIcon		| 上传区域的图标，只能内置图标															| String				| camera-fill				| -							|
+| uploadIconColor	| 上传区域的图标的颜色            														| String				| #D3D4D6   				| -							|
+| useBeforeRead		| 是否开启读取前的处理函数功能，使用@beforeRead必须设置为true			| Boolean				| false						| true	&#124; false					|
+| previewFullImage	| 是否开启图片预览功能																	| Boolean				| true						| true	&#124; false					|
+| previewFullVideo	| 是否开启视频预览功能																	| Boolean				| true						| true	&#124; false					|
+| maxCount			| 最大选择图片的数量																	| String &#124; Number	| 52						| -							|
+| disabled			| 是否启用(显示/隐藏)组件																| Boolean				| false						| true &#124; false						|
+| imageMode			|  预览上传的图片时的裁剪模式，和image组件mode属性一致									| String				| aspectFill				| -							|
+| name				| 标识符，可以在回调函数的第二项参数中获取												| String				| file						| -							|
+| sizeType			| original 原图，compressed 压缩图，默认二者都有，H5无效								| Array\<String\>		| ['original', 'compressed']| -							|
+| multiple			| 是否开启图片多选，部分安卓机型不支持													| Boolean				| false						| true &#124; false						|
+| deletable			| 是否显示删除按钮																| Boolean				| true						| true	&#124; false					|
+| maxSize			| 选择单个文件的最大大小，单位B(byte)，默认不限制										| String &#124; Number	| Number.MAX_VALUE			| -							|
+| uploadText		| 上传区域的提示文字																	| String				| -							| -							|
+| width				| 内部预览图片区域和选择图片按钮的区域宽度，单位rpx，不能是百分比，或者`auto`				| String &#124; Number	| 80						| -							|
+| height			| 内部预览图片区域和选择图片按钮的区域高度，单位rpx，不能是百分比，或者`auto`				| String &#124; Number	| 80						| -							|
+| previewImage		| 是否在上传完成后展示预览图													    | Boolean				| true						| true &#124; false						|
+| customStyle | 自定义外部样式 | Object | - | - |
+
+### FileList Options 
+
+|属性名|说明|
+|:-|:-|
+| status | 上传状态，uploading - 上传中 &nbsp; success - 上传成功 &nbsp; failed - 上传失败 |
+| message | 提示文本 |
+| url | 图片地址 |
+
+
+### Upload Methods
+
+此方法如要通过ref手动调用
+
+| 名称          | 说明            |
+|-------------  |---------------- |
+| beforeRead | 读取前的处理函数|
+| afterRead | 读取后的处理函数  |
+
+### Upload Events
+
+回调参数中的`event`参数，为当前删除元素的所有信息，`index`为当前操作的图片的索引，`name`为删除名称，`file`包含删除的url信息
+
+|事件名|说明|回调参数|
+|:-|:-|:-|:-|
+| @beforeRead  | 读取前的处理函数，使用之前必须设置 `useBeforeRead` 为 `true`   | (file, lists, name)，错误信息 | 
+| @afterRead  | 读取后的处理函数 | (file, lists, name)，错误信息 | 
+| @oversize | 图片大小超出最大允许大小 | (file, lists, name), name为通过`props`传递的`index`参数 |
+| @clickPreview | 全屏预览图片时触发 | e={deletable,index,isImage,isVideo,name,url} 是否展示删除按钮，索引，是否是图片，是否是视频，通过 props 传递的name，文件地址|
+| @delete | 删除图片 | e={file,index,name}，文件，索引，通过 props 传递的name |
+
+### Upload Slots
+
+slot中您可以内置任何您所需要的样式。
+
+|名称|说明|
+|:-|:-|
+| -(default) | 自定义上传样式 |
+
+<style scoped>
+h3[id=upload-slots] + p + table thead tr th:nth-child(2){
+	width: 70%;
+}
+h3[id=upload-methods] + p + table thead tr th:nth-child(2){
+	width: 70%;
+}
+h3[id=upload-events] + p + table thead tr th:nth-child(2){
+	width: 40%;
+}
+h3[id=upload-events] + p + table thead tr th:nth-child(3){
+	width: 40%;
+}
+h3[id=filelist-options]  + table thead tr th:nth-child(2){
+	width: 70%;
+}
+</style>