add docs of messagebox/tooltip/tag...

examples/docs/alert.md

@@ -15,7 +15,7 @@
 
 ## 基本用法
 
-alert组件提供四种主题，由`type`属性指定，默认值为`info`，下面的示例展示了四种不同的主题。
+Alert 组件提供四种主题，由`type`属性指定，默认值为`info`，下面的示例展示了四种不同的主题。
 
 <div class="demo-box demo-alert">
   <el-alert title="成功提示的文案" type="success"></el-alert>
@@ -91,7 +91,7 @@ alert组件提供四种主题，由`type`属性指定，默认值为`info`，下
 
 ## 带有 icon 和辅助性文字介绍
 
-最后，这是一个同时具有icon和辅助性文字的样例。
+最后，这是一个同时具有 icon 和辅助性文字的样例。
 
 <div class="demo-box demo-alert">
   <el-alert title="成功提示的文案" type="success" description="文字说明文字说明文字说明文字说明文字说明文字说明" show-icon></el-alert>
@@ -137,11 +137,11 @@ alert组件提供四种主题，由`type`属性指定，默认值为`info`，下
 | type | 主题 | string | 'success', 'warning', 'info', 'error' | 'info' |
 | description | 辅助性文字 | string | | |
 | closable | 是否可关闭 | boolean | | true |
-| closeText | 关闭按钮自定义文本 | string | | |
+| close-text | 关闭按钮自定义文本 | string | | |
 | showIcon | 是否显示图标 | boolean | | false |
 
 
 ## Events
-| 参数      | 说明          | 类型      | 可选值                           | 默认值  |
+| 事件名称 | 说明 | 回调参数 |
-|---------- |-------------- |---------- |--------------------------------  |-------- |
+|---------- |-------- |---------- |
-| close | 关闭时的回调函数 | function | | |
+| close | 关闭alert时触发的事件 |  |

examples/docs/badge.md

@@ -1,5 +1,7 @@
 ## 基础用法
-展示新消息数量
+Badge 组件可以在右上角展示标记，最常见的用法是用于展示消息数，定义`value`属性，它接受`Number`或者`String`。
+
+下面是一个样例，我们在 Badge 组件内嵌入 Button 组件：
 
 <el-row>
   <el-col :span="12">
@@ -45,7 +47,9 @@
 ```
 
 ## 最大值
-可自定义最大值
+为了方便使用，Badge 组件可以自定义显示的最大值，由`max`属性定义，它接受一个`Number`，需要注意的是，只有当`value`为`Number`时，它才会生效。
+
+下面是一个样例：
 
 <el-row>
   <el-col :span="12">
@@ -69,7 +73,9 @@
 
 
 ## 自定义内容
-可以显示数字外的文本内容
+
+定义`value`为`String`类型是时可以用于显示自定义文本，下面是两个样例，它们可以启发你在适时的情况使用 Badge：
+
 
 <el-row>
   <el-col :span="12">
@@ -92,7 +98,7 @@
 ```
 
 ## 小红点
-以红点的形式标注需要关注的内容
+除了数字外，设置`is-dot`属性，它接受一个`Boolean`。可以使badge组件显示为一个小红点，来提醒用户需要关注的内容，此时设置其他属性均无效。
 
 <el-row>
   <el-col :span="12">
@@ -131,7 +137,7 @@
   }
 </style>
 
-## API
+## Attributes
 | 参数          | 说明            | 类型            | 可选值                 | 默认值   |
 |-------------  |---------------- |---------------- |---------------------- |-------- |
 | value          | 显示值      | string, number          |                       |         |

examples/docs/button.md

@@ -31,7 +31,7 @@
 
 ## 基础用法
 
-button组件默认提供7种主题，由`type`属性来定义，默认为`default`：
+Button 组件默认提供7种主题，由`type`属性来定义，默认为`default`：
 
 <div class="demo-box demo-button">
   <el-button>Default</el-button>
@@ -71,7 +71,7 @@ button组件默认提供7种主题，由`type`属性来定义，默认为`defaul
 
 注意，在该情况下，`type`虽然可以为`text`，但是是没有意义的，会显示为`text button`的样式。
 
-你可以Hover在样例上进行预览：
+你可以 Hover 在样例上进行预览：
 
 <div class="demo-box demo-button">
   <el-button :plain="true">Default</el-button>
@@ -91,7 +91,7 @@ button组件默认提供7种主题，由`type`属性来定义，默认为`defaul
 
 ## 尺寸
 
-button组件提供除了默认值以外的三种尺寸：`large`、`small`、`mini`来满足不同的需求，通过设置`size`属性来配置它们。
+Button 组件提供除了默认值以外的三种尺寸：`large`、`small`、`mini`来满足不同的需求，通过设置`size`属性来配置它们。
 
 <div class="demo-box demo-button">
   <el-button type="primary" size="large">large</el-button>
@@ -109,7 +109,7 @@ button组件提供除了默认值以外的三种尺寸：`large`、`small`、`mi
 
 ## Loading
 
-button组件提供的`loading`属性可以方便的让你处理 loading 状态，它接受一个`Boolean`，要设置为 loading 状态，只要设置`loading`属性为`true`即可，下面是一个样例：
+Button 组件提供的`loading`属性可以方便的让你处理 loading 状态，它接受一个`Boolean`，要设置为 loading 状态，只要设置`loading`属性为`true`即可，下面是一个样例：
 
 <div class="demo-box demo-button">
   <el-button type="primary" :loading="true">Button</el-button>
@@ -131,14 +131,14 @@ button组件提供的`loading`属性可以方便的让你处理 loading 状态
 
 ## 图标按钮
 
-理所当然的，Element也支持图标按钮，设置`icon`属性即可，icon的列表可以参考Element的icon组件，下面是简单的预览：
+理所当然的，Element 也支持图标按钮，设置`icon`属性即可，icon 的列表可以参考 Element 的 icon 组件，下面是简单的预览：
 
 <div class="demo-box demo-button">
   <el-button type="primary" icon="edit"></el-button>
   <el-button type="primary" icon="search">Search</el-button>
 </div>
 
-除此以外，你也可以设置在文字右边的icon，只要使用`i`标签即可，使用图标组件来实现它：
+除此以外，你也可以设置在文字右边的 icon ，只要使用`i`标签即可，使用图标组件来实现它：
 
 <div class="demo-box demo-button">
   <el-button type="primary">Upload<i class="el-icon-upload el-icon-right"></i></el-button>

examples/docs/card.md

@@ -44,7 +44,10 @@
 </style>
 
 ## 基础用法
-包含标题, 内容和操作
+
+Card 组件包括`header`和`body`部分，`header`部分需要有显式具名 slot 分发，同时他也是可选的。
+
+下面是一个带有标题、内容和操作（按钮）的 Card 组件示例，需要注意的是，部分样式需要你自己填入，下例中我们使用了布局来限制卡片的宽度：
 
 <el-row>
   <el-col :span="12">
@@ -73,7 +76,8 @@
 ```
 
 ## 简单卡片
-卡片可以只有内容区域
+
+如上述所言，Card 组件可以只有`body`区域，下面是一个没有定义`header`的 Card 组件。
 
 <el-row>
   <el-col :span="12">
@@ -94,8 +98,12 @@
 ```
 
 
-## 带图片
+## 进阶使用
-可配置定义更丰富的内容展示
+配置`body-style`属性来自定义`body`部分的`style`。
+
+可以让你的卡片极大程度的被个性化，为更丰富的内容展示服务。。
+
+下例是一个带图片的示例，能帮助你更好地理解`body-style`配合分发内容自定义样式的强大：
 
 <el-row>
   <el-col :span="8" v-for="(o, index) in 2" :offset="index > 0 ? 2 : 0">
@@ -125,7 +133,7 @@
 </el-card>
 ```
 
-## API
+## Attributes
 | 参数      | 说明    | 类型      | 可选值       | 默认值   |
 |---------- |-------- |---------- |-------------  |-------- |
 | header | 设置 header，也可以通过 `slot#header` 传入 DOM | string| | |

examples/docs/icon.md

@@ -50,11 +50,11 @@
 </style>
 ## icon-font 图标
 
-我们为你提供了一套常用的图标集合。
+提供了一套常用的图标集合。
 
 ## 使用方法
 
-直接通过`el-icon-iconName`的类名来使用即可。例如：
+直接通过设置类名为`el-icon-iconName`来使用即可。例如：
 
 <div><i class="el-icon-search"></i></div>
 
@@ -62,7 +62,7 @@
 <i class="el-icon-search"></i>
 ```
 
-也可以在按钮组件中使用图标:
+也可以在按钮组件中使用图标，更多地使用方式可以在按钮组件的文档中看到。
 
 <div><el-button type="primary" icon="search">搜索</el-button></div>
 
@@ -72,6 +72,8 @@
 
 ## 图标集合
 
+下面是目前 Element 所有的图标集合：
+
 <ul class="icon-list">
   <li v-for="name in icons">
     <span>

examples/docs/message-box.md

@@ -48,23 +48,20 @@
         }).then(action => {
           this.$msgbox('', 'action: ' + action);
         });
-      },
-      
-      open6() {
-        this.$msgbox({
-          title: '消息',
-          message: '这是一段内容, 这是一段内容, 这是一段内容, 这是一段内容, 这是一段内容, 这是一段内容, 这是一段内容',
-          showCancelButton: true,
-          showClose: false,
-          confirmButtonText: '知道了',
-          type: 'success'
-        });
       }
+
     }
   };
 </script>
 
 ## 基本用法
+
+MessageBox 组件提供了四种不同的样式来替代浏览器提供的`alert`等功能：`$msgbox`，`$alert`，`$confirm`以及`$prompt`。
+
+在本页文档中一一介绍它们，首先看最简单的示例，我们使用`$alert`，它接收了两个参数，`message`和`title`。
+
+值得一提的是，窗口被关闭后，它会返回一个`Promise`对象便于进行后续操作的处理。
+
 <el-button @click.native="open">打开 Alert</el-button>
 
 ```html
@@ -83,7 +80,13 @@
 </script>
 ```
 
-## 返回 Promise
+## 配置项
+
+MessageBox 组件也拥有极高的定制性，我们可以传入`options`作为第三个参数，它是一个字面量对象。
+
+下例是一个包含图标的 alert 框，需要注意的是，第二个参数`title`必须定义为`String`类型，如果是`Object`，会被理解为`options`。
+
+`type`字段表明消息类型，可以为`success`，`error`，`info`和`warning`，无效的设置将会被忽略。
 
 <el-button @click.native="open2">打开 alert</el-button>
 
@@ -105,6 +108,8 @@
 </script>
 ```
 
+下面是一个 confirm 框，在这里我们用了`Promise`来处理后续响应。
+
 <el-button @click.native="open3">打开 confirm</el-button>
 
 ```html
@@ -132,6 +137,11 @@
   }
 </script>
 ```
+
+Prompt 框功能强大，可以处理简单的输入，甚至你可以用`inputPattern`字段自己规定匹配模式，或者用`inputValidator`规定校验函数，可以返回`Boolean`或`String`，`Boolean`为`false`或字符串时均表示校验为通过，`String`相当于定义了`inputErrorMessage`字段。
+
+此外，你可以用`inputPlaceholder`字段来定义输入框的占位符。
+
 <el-button @click.native="open4">打开 prompt</el-button>
 
 ```html
@@ -157,6 +167,10 @@
 </script>
 ```
 
+Msgbox 框是最基本的弹框，与 Alert 的区别在于 Alert 无法通过 ESC 和 点击框外关闭。
+
+此例中我们使用了`showCancelButton`字段，用于显示取消按钮，同时使用`cancelButtonClass`可以自定义样式，`cancelButtonText`来自定义按钮文本，Confirm 按钮也具有相同的字段，在文末的字段说明中有完整的字段列表。
+
 <el-button @click.native="open5">打开 Message Box</el-button>
 
 ```html
@@ -181,35 +195,9 @@
 </script>
 ```
 
-## 更多配置项
-
-<el-button @click.native="open6">打开 Message Box</el-button>
-
-```html
-<template>
-  <el-button @click.native="open6">打开 Message Box</el-button>
-</template>
-
-<script>
-  export default {
-    methods: {
-      open6() {
-        this.$msgbox({
-          title: '消息',
-          message: '这是一段内容, 这是一段内容, 这是一段内容, 这是一段内容, 这是一段内容, 这是一段内容, 这是一段内容',
-          showCancelButton: true,
-          confirmButtonText: '知道了',
-          type: 'success'
-        });
-      }
-    }
-  }
-</script>
-```
-
 ## 全局方法
 
-element 为 Vue.prototype 添加了如下全局方法：$msgbox, $alert, $confirm 和 $prompt。因此在 vue instance 中可以采用本页面中的方式调用 `MessageBox`。
+Element 为 Vue.prototype 添加了如下全局方法：$msgbox, $alert, $confirm 和 $prompt。因此在 vue instance 中可以采用本页面中的方式调用 `MessageBox`。
 
 ## 单独引用
 
@@ -221,13 +209,13 @@ import { MessageBox } from 'element-ui';
 
 对应于上述四个全局方法的调用方法依次为：MessageBox, MessageBox.alert, MessageBox.confirm 和 MessageBox.prompt。
 
-## API
+## Options
 
 | 参数      | 说明          | 类型      | 可选值                           | 默认值  |
 |---------- |-------------- |---------- |--------------------------------  |-------- |
-| title | 标题 | string | | |
+| title | MessageBox标题 | string | | |
-| message | 消息内容 | string | | |
+| message | MessageBox消息正文内容 | string | | |
-| type | 消息类型 | string | 'success', 'info', 'warning', 'error' | |
+| type | 消息类型，用于显示图标 | string | 'success', 'info', 'warning', 'error' | |
 | showCancelButton | 是否显示取消按钮 | boolean | | false（以 confirm 和 prompt 方式调用时为 true） |
 | showConfirmButton | 是否显示确定按钮 | boolean | | true |
 | cancelButtonText | 取消按钮的文本内容 | string | | '取消' |
@@ -235,8 +223,7 @@ import { MessageBox } from 'element-ui';
 | cancelButtonClass | 取消按钮的自定义类名 | string | | |
 | confirmButtonClass | 确定按钮的自定义类名 | string | | |
 | showInput | 是否显示输入框 | boolean | | false（以 prompt 方式调用时为 true）|
-| inputValue | 输入框的值 | string | | |
 | inputPlaceholder | 输入框的占位符 | string | | |
 | inputPattern | 输入框的校验表达式 | regexp | | |
-| inputValidator | 输入框的校验函数。若返回一个字符串, 则返回结果会被赋值给 inputErrorMessage | function | | |
+| inputValidator | 输入框的校验函数。可以返回布尔值或字符串，若返回一个字符串, 则返回结果会被赋值给 inputErrorMessage | function | | |
 | inputErrorMessage | 校验未通过时的提示文本 | string | | '输入的数据不合法!' |

examples/docs/tag.md

@@ -30,6 +30,8 @@
 
 ## 基础使用
 
+Tag 组件提供了六种主题，由`type`属性来定义，该属性可选填：
+
 <div class="demo-box demo-tag">
   <el-tag>标签一</el-tag>
   <el-tag type="gray">标签二</el-tag>
@@ -48,14 +50,37 @@
 <el-tag type="danger">标签六</el-tag>
 ```
 
+## 描边
+
+`hit`属性可以设置描边，接受一个`Boolean`，默认为`false`。
+
+借此可以定义 hover 时的效果，下面是一个`hit`为`true`时的效果：
+
+<div class="demo-box demo-tag">
+  <el-tag type="primary" :hit="true">标签</el-tag>
+</div>
+
+```html
+<el-tag type="primary" :hit="true">标签</el-tag>
+```
+
 ## 可移除的标签
 
+设置`closable`属性来定义一个可移除的标签，接受一个`Boolean`，设置为`true`即可。
+
+此外，默认的标签移除时会附带渐变动画，如果不想使用，可以设置`close-transition`属性，它接受一个`Boolean`，true 为关闭。
+
+设置`close`事件可以处理关闭后的回调函数。
+
+下面是一个综合应用他们的样例：
+
 <div class="demo-box demo-tag">
   <el-tag
     v-for="tag in tags"
     :closable="true"
     :type="tag.type"
     :key="tag"
+    :close-transition="false"
     @close="handleClose(tag)"
   >
   {{tag.name}}
@@ -67,6 +92,8 @@
   v-for="tag in tags"
   :closable="true"
   :type="tag.type"
+  :key="tag"
+  :close-transition="false"
   @close="handleClose(tag)"
 >
 {{tag.name}}
@@ -94,3 +121,17 @@
   }
 </script>
 ```
+
+## Attributes
+| 参数      | 说明          | 类型      | 可选值                           | 默认值  |
+|---------- |-------------- |---------- |--------------------------------  |-------- |
+| type | 主题 | string | 'primary', 'gray', 'success', 'warning', 'error' |  |
+| closable | 是否可关闭 | boolean | | false |
+| close-transition | 是否禁用关闭时的渐变动画 | boolean | | false |
+| hit | 是否有边框描边 | boolean | | false |
+
+
+## Events
+| 事件名称 | 说明 | 回调参数 |
+|---------- |-------- |---------- |
+| close | 关闭tag时触发的事件 |  |

examples/docs/tooltip.md

@@ -1,5 +1,29 @@
+<script>
+  export default {
+    data() {
+      return {
+        disabled: false
+      };
+    }
+  };
+</script>
 ## 基础用法
-鼠标 hover 的时候显示,可选择提示出现的位置。
+
+Tooltip 组件常用于展示鼠标 hover 时的提示信息，在这里我们提供9种不同的展示方式。
+
+使用`content`属性来决定`hover`时的提示信息。
+
+由`placement`属性决定展示效果：
+
+`placement`属性值为：`方向-箭头方位`
+
+四个方向：`top`、`left`、`right`、`bottom`
+
+三种箭头方位：`start`, `end`，默认为空
+
+如`top center`即`placement="top"`，`left top`即`placement="left-start"`。
+
+下面是完整的九个示例，可以通过该示例来理解上面的说明，选择你要的效果：
 
 <style>
   .box {
@@ -78,7 +102,9 @@
   </div>
 </div>
 
-## 适用于不同情景
+## 主题
+
+Tooltip 组件提供了两个不同的主题：`dark`和`light`，可以通过设置`effect`属性来改变主题，默认为`dark`。
 
 <div>
   <el-tooltip content="Top center" placement="top">
@@ -93,12 +119,91 @@
   </el-tooltip>
 </div>
 
-## API
+```html
+<el-tooltip content="Top center" placement="top">
+  <el-button>Dark</el-button>
+</el-tooltip>
+<el-tooltip content="Bottom center" placement="bottom" effect="light">
+  <el-button>Light</el-button>
+</el-tooltip>
+```
+
+## 更多Content
+
+如果需要展示多行文本或者是设置文本内容的格式，我们可以考虑用具名 slot 分发`content`，替代`tooltip`中的`content`属性：
+
+<div>
+  <el-tooltip placement="top">
+    <div slot="content">多行信息<br/>第二行信息</div>
+    <el-button>Top center</el-button>
+  </el-tooltip>
+</div>
+
+```html
+<el-tooltip placement="top">
+  <div slot="content">多行信息<br/>第二行信息</div>
+  <el-button>Top center</el-button>
+</el-tooltip>
+```
+
+## 高级扩展
+
+除了这些基本设置外，还有一些属性可以让使用者更好的定制自己的效果：
+
+`transition`属性可以定制显隐的动画效果，默认为`fade-in-linear`。
+
+如果需要关闭`tooltip`功能，`disabled`属性可以满足这个需求，它接受一个`Boolean`，设置为`true`即可。
+
+事实上，这是基于[Vue-popper](https://github.com/element-component/vue-popper)的扩展，你可以自定义任意 Vue-popper 中允许定义的字段。
+
+当然，Tooltip 组件实际上十分强大，文末的API文档会做一一说明。
+
+<style>
+  .slide-fade-enter-active {
+    transition: all .3s ease;
+  }
+  .slide-fade-leave-active {
+    transition: all .3s cubic-bezier(1.0, 0.5, 0.8, 1.0);
+  }
+  .slide-fade-enter, .expand-fade-leave-active {
+    margin-left: 20px;
+    opacity: 0;
+  }
+</style>
+
+<div>
+  <el-tooltip :disabled="disabled" content="点击关闭 tooltip 功能" transition="slide-fade" placement="bottom" effect="light">
+    <el-button @click.native="disabled=true">点击关闭 tooltip 功能</el-button>
+  </el-tooltip>
+</div>
+
+```html
+<el-tooltip :disabled="disabled" content="点击关闭 tooltip 功能" transition="slide-fade" placement="bottom" effect="light">
+  <el-button @click.native="disabled=true">点击关闭 tooltip 功能</el-button>
+</el-tooltip>
+
+<style>
+  .slide-fade-enter-active {
+    transition: all .3s ease;
+  }
+  .slide-fade-leave-active {
+    transition: all .3s cubic-bezier(1.0, 0.5, 0.8, 1.0);
+  }
+  .slide-fade-enter, .expand-fade-leave-active {
+    margin-left: 20px;
+    opacity: 0;
+  }
+</style>
+```
+
+## Attributes
 | 参数               | 说明                                                     | 类型              | 可选值      | 默认值 |
 |--------------------|----------------------------------------------------------|-------------------|-------------|--------|
-|  effect        |  默认提供的样式  | String            | `dark`, `light`  | dark  |
+|  effect        |  默认提供的主题  | String            | `dark`, `light`  | dark  |
-|  content        |  显示的内容  | String            |  |  |
+|  content        |  显示的内容，也可以通过 `slot#content` 传入 DOM  | String            |  |  |
-|  placement        |  出现位置  | String           |  `top`, `top-start`, `top-end`, `bottom`, `bottom-start`, `bottom-end`, `left`, `left-start`, `left-end`, `right`, `right-start`, `right-end` |  bottom |
+|  placement        |  Tooltip 的出现位置  | String           |  `top`, `top-start`, `top-end`, `bottom`, `bottom-start`, `bottom-end`, `left`, `left-start`, `left-end`, `right`, `right-start`, `right-end` |  bottom |
 |  visible        |  初始状态是否可见  | Boolean           |  |  false |
-|  disabled       |  控制是否不可见  | Boolean           |  |  false |
+|  disabled       |  Tooltip 是否可用  | Boolean           |  |  false |
-|  options        | [popper.js](https://popper.js.org/documentation.html) 的参数 | Object            | 参考 [popper.js](https://popper.js.org/documentation.html) 文档 | { boundariesElement: 'body' } |
+|  transition     |  定义渐变动画      | String             |  | `fade-in-linear` |
+|  visibleArrow   |  是否显示 Tooltip 箭头，更多参数可见[Vue-popper](https://github.com/element-component/vue-popper) | Boolean |  | true |
+|  options        | [popper.js](https://popper.js.org/documentation.html) 的参数 | Object            | 参考 [popper.js](https://popper.js.org/documentation.html) 文档 | `{ boundariesElement: 'body', gpuAcceleration: false }` |

packages/message-box/src/main.vue

@@ -8,10 +8,10 @@
         </div>
         <div class="el-message-box__content" v-if="message !== ''">
           <div class="el-message-box__status" :class="[ typeClass ]"></div>
-          <div class="el-message-box__message" :style="{ 'margin-left': type ? '50px' : '0' }"><p>{{ message }}</p></div>
+          <div class="el-message-box__message" :style="{ 'margin-left': typeClass ? '50px' : '0' }"><p>{{ message }}</p></div>
           <div class="el-message-box__input" v-show="showInput">
             <input type="text" v-model="inputValue" :placeholder="inputPlaceholder" ref="input" />
-            <div class="el-message-box__errormsg" :style="{ visibility: !!editorErrorMessage ? 'visible' : 'hidden' }">{{editorErrorMessage}}</div>
+            <div class="el-message-box__errormsg" :style="{ visibility: !!editorErrorMessage ? 'visible' : 'hidden' }">{{ editorErrorMessage }}</div>
           </div>
         </div>
         <div class="el-message-box__btns">
@@ -56,14 +56,14 @@
 
     computed: {
       typeClass() {
-        return this.type ? `el-icon-${ typeMap[this.type] }` : '';
+        return this.type && typeMap[this.type] ? `el-icon-${ typeMap[this.type] }` : '';
       },
 
       confirmButtonClasses() {
-        return 'el-button el-button-primary ' + this.confirmButtonClass;
+        return `el-button el-button-primary ${ this.confirmButtonClass }`;
       },
       cancelButtonClasses() {
-        return 'el-button el-button-default ' + this.cancelButtonClass;
+        return `el-button el-button-default ${ this.cancelButtonClass }`;
       }
     },