Update 公共组件开发.md

开发文档/公共组件开发.md

@@ -1 +1,193 @@
+## 摘要
+项目中一些可以复用的组件称为公共组件，放在`src/components/common`目录下，本项目用到的公共组件有对话框，弹窗，Toast等，和小程序的Toast也差不多。
+这里也写了个<a href="https://github.com/ChenMingK/demos/tree/master/common-components">demo</a>，如果公共组件是渲染在最外层的(和App同级)，
+可以使用vue-create-api来快速创建而不是一个个导入。具体的使用方法见开发文档的**Tips**部分
 
+<img src="https://github.com/ChenMingK/ImagesStore/blob/master/imgs/common-components.gif" width=300px>
+
+## Toast
+这是用于消息显示的组件，用于显示消息，比如显示下载进度或者支付成功之类的。我们让其绝对定位水平垂直居中且总是置于顶层<br>
+- 接收的参数
+  - text: 消息框显示的文本内容
+  - timeout: 消息框显示的时间，默认为1.5s
+- 提供的方法
+  - show(): 显示对话框, 在timeout时间后消失
+  - hide(): 隐藏对话框
+``` html
+<template>
+  <transition name="fade">
+    <div class="toast-bg-wrapper" @click.prevent v-show="visible"><!--不处理任何的点击事件-->
+      <div class="toast-bg">
+        <div class="toast-wrapper">
+          <div class="toast" v-html="showText"></div><!--内容按普通html插入-->
+        </div>
+      </div>
+    </div>
+  </transition>
+</template>
+```
+``` javaScript
+<script>
+  export default {
+    // 要使用vue-create-api则需要加上name
+    name: 'toast',
+    props: {
+      text: [String, Number], // 要传入消息框的内容
+      timeout: {              // 可控的对话框显示时间
+        type: Number,
+        default: 1500
+      }
+    },
+    data() {
+      return {
+        visible: false,
+        showText: ''
+      }
+    },
+    methods: {
+      hide() {
+        this.visible = false
+      },
+      // 提供显示对话框的方法
+      show() {
+        this.visible = true
+        this.showText = this.text
+        clearTimeout(this.task)
+        this.task = null
+        this.task = setTimeout(() => {
+          this.visible = false
+        }, this.timeout)
+      },
+      // 提供持续显示对话框的方法，比如显示下载进度，外部最后可通过调用hide()方法隐藏
+      continueShow() {
+        this.showText = this.text
+        clearTimeout(this.task)
+        this.task = null
+        this.visible = true
+      }
+    }
+  }
+</script>
+```
+
+## Dialog
+对话框组件，显示一段文本，并让用户点击确认或取消，因为点击确认需要执行的事件由父组件来决定，所有要允许父组件传入按钮的点击事件<br>
+- 接收的参数
+  - title: 需要显示的文本内容
+- 提供的方法
+  - show(): 显示对话框
+  - hide(): 隐藏对话框
+这里使用了插槽`slot`，即父组件可以往此处填充自己的内容，这样组件的可扩展性就更好了，比如我不想要两个按钮我想要三个那就自己加
+
+``` html
+<template>
+  <transition name="fade">
+    <div class="dialog" v-show="visible">
+      <div class="dialog-wrapper">
+        <div class="dialog-title-wrapper">
+          <span class="dialog-title-text">{{title}}</span>
+        </div>
+        <slot>
+        </slot><!--插槽-->
+        <div class="dialog-btn-wrapper">
+          <slot name="btn"><!--带默认样式的插槽，不填写按钮的话默认两个按钮-->
+            <div class="dialog-btn" @click="hide">取消</div>
+            <div class="dialog-btn">确认</div>
+          </slot>
+        </div>
+      </div>
+    </div>
+  </transition>
+</template>
+```
+
+``` javaScript
+<script>
+  export default {
+    name: 'my-dialog',
+    props: {
+      title: String
+    },
+    data() {
+      return {
+        visible: false
+      }
+    },
+    methods: {
+      show() {
+        this.visible = true
+      },
+      hide() {
+        this.visible = false
+      }
+    }
+  }
+</script>
+```
+
+## Popup
+这是一个底层弹窗组件<br>
+- 接收的参数
+  - title: 需要显示的文本内容
+  - btn: 可动态配置的按钮，以数组形式传入，一个按钮作为一个数组元素
+- 提供的方法
+  - show(): 显示
+  - hide(): 隐藏
+
+``` html
+<template>
+  <div class="popup" v-if="popupVisible">
+    <transition name="fade">
+      <div class="popup-bg" @click.stop.prevent="hide()" v-if="popupVisible"></div>
+      <!--灰色的背景图层, 点击后弹窗隐藏. 禁止事件冒泡和预设行为-->
+    </transition>
+    <transition name="popup-slide-up">[]
+      <div class="popup-wrapper" v-show="visible"> <!--两个visible来控制隐藏, 完善过渡动画-->
+        <div class="popup-title" v-if="title && title.length > 0">{{title}}</div>
+        <div class="popup-btn"
+            :class="{'danger': item.type === 'danger'}"
+            v-for="(item, index) in btn"
+            :key="index"
+            @click="item.click">
+            {{item.text}}
+        </div><!--danger属性作为警告按钮-->
+      </div>
+    </transition>
+  </div>
+</template>
+```
+
+``` javaScript
+<script>
+  export default {
+    name: 'popup',
+    props: {
+      title: String, // 上方提示内容
+      btn: Array // 可动态配置的按钮数 btn = [ {type: xx, text: xx} ]
+    },
+    data() {
+      return {
+        popupVisible: false,
+        visible: false    
+      }
+    },
+    methods: {
+      show() {
+        // 这里反过来, 先显示整个Popup, 再显示下方按钮
+        this.popupVisible = true
+        // setTimeout保证执行顺序, 先让整个Popup显示出来, 再显示按钮部分
+        setTimeout(() => {
+          this.visible = true
+        })     
+      },
+      hide() {
+        // 先将下方按钮部分隐藏，再隐藏整体的, 即先保留灰色背景层, 让按钮部分显示过渡动画
+        this.visible = false
+        setTimeout(() => {
+          this.popupVisible = false
+        }, 200) 
+      }
+    }
+}
+</script>
+```