pit-docs-mcp 1.0.2

package/docs/pitElementUi/message-box.md

@@ -0,0 +1,326 @@
+## MessageBox 弹框
+模拟系统的消息提示框而实现的一套模态对话框组件，用于消息提示、确认消息和提交内容。
+
+:::tip
+从场景上说，MessageBox 的作用是美化系统自带的 `alert`、`confirm` 和 `prompt`，因此适合展示较为简单的内容。如果需要弹出较为复杂的内容，请使用 Dialog。
+:::
+
+### 消息提示
+
+当用户进行操作时会被触发，该对话框中断用户操作，直到用户确认知晓后才可关闭。
+
+:::demo 调用`$alert`方法即可打开消息提示，它模拟了系统的 `alert`，无法通过按下 ESC 或点击框外关闭。此例中接收了两个参数，`message`和`title`。值得一提的是，窗口被关闭后，它默认会返回一个`Promise`对象便于进行后续操作的处理。若不确定浏览器是否支持`Promise`，可自行引入第三方 polyfill 或像本例一样使用回调进行后续处理。
+```html
+<template>
+  <el-button type="text" @click="open">点击打开 Message Box</el-button>
+</template>
+
+<script>
+  export default {
+    methods: {
+      open() {
+        this.$alert('这是一段内容', '标题名称', {
+          confirmButtonText: '确定',
+          callback: action => {
+            this.$message({
+              type: 'info',
+              message: `action: ${ action }`
+            });
+          }
+        });
+      }
+    }
+  }
+</script>
+```
+:::
+
+### 确认消息
+
+提示用户确认其已经触发的动作，并询问是否进行此操作时会用到此对话框。
+
+:::demo 调用`$confirm`方法即可打开消息提示，它模拟了系统的 `confirm`。Message Box 组件也拥有极高的定制性，我们可以传入`options`作为第三个参数，它是一个字面量对象。`type`字段表明消息类型，可以为`success`，`error`，`info`和`warning`，无效的设置将会被忽略。注意，第二个参数`title`必须定义为`String`类型，如果是`Object`，会被理解为`options`。在这里我们用了 Promise 来处理后续响应。
+
+```html
+<template>
+  <el-button type="text" @click="open">点击打开 Message Box</el-button>
+</template>
+
+<script>
+  export default {
+    methods: {
+      open() {
+        this.$confirm('此操作将永久删除该文件, 是否继续?', '提示', {
+          confirmButtonText: '确定',
+          cancelButtonText: '取消',
+          type: 'warning'
+        }).then(() => {
+          this.$message({
+            type: 'success',
+            message: '删除成功!'
+          });
+        }).catch(() => {
+          this.$message({
+            type: 'info',
+            message: '已取消删除'
+          });          
+        });
+      }
+    }
+  }
+</script>
+```
+:::
+
+### 提交内容
+
+当用户进行操作时会被触发，中断用户操作，提示用户进行输入的对话框。
+
+:::demo 调用`$prompt`方法即可打开消息提示，它模拟了系统的 `prompt`。可以用`inputPattern`字段自己规定匹配模式，或者用`inputValidator`规定校验函数，可以返回`Boolean`或`String`，返回`false`或字符串时均表示校验未通过，同时返回的字符串相当于定义了`inputErrorMessage`字段。此外，可以用`inputPlaceholder`字段来定义输入框的占位符。
+
+```html
+<template>
+  <el-button type="text" @click="open">点击打开 Message Box</el-button>
+</template>
+
+<script>
+  export default {
+    methods: {
+      open() {
+        this.$prompt('请输入邮箱', '提示', {
+          confirmButtonText: '确定',
+          cancelButtonText: '取消',
+          inputPattern: /[\w!#$%&'*+/=?^_`{|}~-]+(?:\.[\w!#$%&'*+/=?^_`{|}~-]+)*@(?:[\w](?:[\w-]*[\w])?\.)+[\w](?:[\w-]*[\w])?/,
+          inputErrorMessage: '邮箱格式不正确'
+        }).then(({ value }) => {
+          this.$message({
+            type: 'success',
+            message: '你的邮箱是: ' + value
+          });
+        }).catch(() => {
+          this.$message({
+            type: 'info',
+            message: '取消输入'
+          });       
+        });
+      }
+    }
+  }
+</script>
+```
+:::
+
+### 自定义
+
+可自定义配置不同内容。
+
+:::demo 以上三个方法都是对`$msgbox`方法的再包装。本例直接调用`$msgbox`方法，使用了`showCancelButton`字段，用于显示取消按钮。另外可使用`cancelButtonClass`为其添加自定义样式，使用`cancelButtonText`来自定义按钮文本（Confirm 按钮也具有相同的字段，在文末的字段说明中有完整的字段列表）。此例还使用了`beforeClose`属性，它的值是一个方法，会在 MessageBox 的实例关闭前被调用，同时暂停实例的关闭。它有三个参数：`action`、实例本身和`done`方法。使用它能够在关闭前对实例进行一些操作，比如为确定按钮添加`loading`状态等；此时若需要关闭实例，可以调用`done`方法（若在`beforeClose`中没有调用`done`，则实例不会关闭）。
+
+```html
+<template>
+  <el-button type="text" @click="open">点击打开 Message Box</el-button>
+</template>
+
+<script>
+  export default {
+    methods: {
+      open() {
+        const h = this.$createElement;
+        this.$msgbox({
+          title: '消息',
+          message: h('p', null, [
+            h('span', null, '内容可以是 '),
+            h('i', { style: 'color: teal' }, 'VNode')
+          ]),
+          showCancelButton: true,
+          confirmButtonText: '确定',
+          cancelButtonText: '取消',
+          beforeClose: (action, instance, done) => {
+            if (action === 'confirm') {
+              instance.confirmButtonLoading = true;
+              instance.confirmButtonText = '执行中...';
+              setTimeout(() => {
+                done();
+                setTimeout(() => {
+                  instance.confirmButtonLoading = false;
+                }, 300);
+              }, 3000);
+            } else {
+              done();
+            }
+          }
+        }).then(action => {
+          this.$message({
+            type: 'info',
+            message: 'action: ' + action
+          });
+        });
+      }
+    }
+  }
+</script>
+```
+:::
+
+:::tip
+弹出层的内容可以是 `VNode`，所以我们能把一些自定义组件传入其中。每次弹出层打开后，Vue 会对新老 `VNode` 节点进行比对，然后将根据比较结果进行最小单位地修改视图。这也许会造成弹出层内容区域的组件没有重新渲染，例如 [#8931](https://github.com/ElemeFE/element/issues/8931)。当这类问题出现时，解决方案是给 `VNode` 加上一个不相同的 key，参考[这里](https://jsfiddle.net/zhiyang/ezmhq2ef/)。
+:::
+
+### 使用 HTML 片段
+
+`message` 属性支持传入 HTML 片段。
+
+:::demo 将`dangerouslyUseHTMLString`属性设置为 true，`message` 就会被当作 HTML 片段处理。
+
+```html
+<template>
+  <el-button type="text" @click="open">点击打开 Message Box</el-button>
+</template>
+
+<script>
+  export default {
+    methods: {
+      open() {
+        this.$alert('<strong>这是 <i>HTML</i> 片段</strong>', 'HTML 片段', {
+          dangerouslyUseHTMLString: true
+        });
+      }
+    }
+  }
+</script>
+```
+:::
+
+:::warning
+`message` 属性虽然支持传入 HTML 片段，但是在网站上动态渲染任意 HTML 是非常危险的，因为容易导致 [XSS 攻击](https://en.wikipedia.org/wiki/Cross-site_scripting)。因此在 `dangerouslyUseHTMLString` 打开的情况下，请确保 `message` 的内容是可信的，**永远不要**将用户提交的内容赋值给 `message` 属性。
+:::
+
+### 区分取消与关闭
+
+有些场景下，点击取消按钮与点击关闭按钮有着不同的含义。
+
+:::demo 默认情况下，当用户触发取消（点击取消按钮）和触发关闭（点击关闭按钮或遮罩层、按下 ESC 键）时，Promise 的 reject 回调和`callback`回调的参数均为 'cancel'。如果将`distinguishCancelAndClose`属性设置为 true，则上述两种行为的参数分别为 'cancel' 和 'close'。
+
+```html
+<template>
+  <el-button type="text" @click="open">点击打开 Message Box</el-button>
+</template>
+
+<script>
+  export default {
+    methods: {
+      open() {
+        this.$confirm('检测到未保存的内容，是否在离开页面前保存修改？', '确认信息', {
+          distinguishCancelAndClose: true,
+          confirmButtonText: '保存',
+          cancelButtonText: '放弃修改'
+        })
+          .then(() => {
+            this.$message({
+              type: 'info',
+              message: '保存修改'
+            });
+          })
+          .catch(action => {
+            this.$message({
+              type: 'info',
+              message: action === 'cancel'
+                ? '放弃保存并离开页面'
+                : '停留在当前页面'
+            })
+          });
+      }
+    }
+  }
+</script>
+```
+:::
+
+### 居中布局
+内容支持居中布局
+
+:::demo 将 `center` 设置为 `true` 即可开启居中布局
+
+```html
+<template>
+  <el-button type="text" @click="open">点击打开 Message Box</el-button>
+</template>
+
+<script>
+  export default {
+    methods: {
+      open() {
+        this.$confirm('此操作将永久删除该文件, 是否继续?', '提示', {
+          confirmButtonText: '确定',
+          cancelButtonText: '取消',
+          type: 'warning',
+          center: true
+        }).then(() => {
+          this.$message({
+            type: 'success',
+            message: '删除成功!'
+          });
+        }).catch(() => {
+          this.$message({
+            type: 'info',
+            message: '已取消删除'
+          });
+        });
+      }
+    }
+  }
+</script>
+```
+:::
+
+### 全局方法
+
+如果你完整引入了 Element，它会为 Vue.prototype 添加如下全局方法：$msgbox, $alert, $confirm 和 $prompt。因此在 Vue instance 中可以采用本页面中的方式调用 `MessageBox`。调用参数为：
+- `$msgbox(options)`
+- `$alert(message, title, options)` 或 `$alert(message, options)`
+- `$confirm(message, title, options)` 或 `$confirm(message, options)`
+- `$prompt(message, title, options)` 或 `$prompt(message, options)`
+
+### 单独引用
+
+如果单独引入 `MessageBox`：
+
+```javascript
+import { MessageBox } from 'element-ui';
+```
+
+那么对应于上述四个全局方法的调用方法依次为：MessageBox, MessageBox.alert, MessageBox.confirm 和 MessageBox.prompt，调用参数与全局方法相同。
+
+### Options
+
+| 参数      | 说明          | 类型      | 可选值                           | 默认值  |
+|---------- |-------------- |---------- |--------------------------------  |-------- |
+| title | MessageBox 标题 | string | — | — |
+| message | MessageBox 消息正文内容 | string / VNode | — | — |
+| dangerouslyUseHTMLString | 是否将 message 属性作为 HTML 片段处理 | boolean | — | false |
+| type | 消息类型，用于显示图标 | string | success / info / warning / error | — |
+| iconClass | 自定义图标的类名，会覆盖 `type` | string | — | — |
+| customClass | MessageBox 的自定义类名 | string | — | — |
+| callback | 若不使用 Promise，可以使用此参数指定 MessageBox 关闭后的回调 | function(action, instance)，action 的值为'confirm', 'cancel'或'close', instance 为 MessageBox 实例，可以通过它访问实例上的属性和方法 | — | — |
+| showClose | MessageBox 是否显示右上角关闭按钮 | boolean | — | true |
+| beforeClose | MessageBox 关闭前的回调，会暂停实例的关闭 | function(action, instance, done)，action 的值为'confirm', 'cancel'或'close'；instance 为 MessageBox 实例，可以通过它访问实例上的属性和方法；done 用于关闭 MessageBox 实例 | — | — |
+| distinguishCancelAndClose | 是否将取消（点击取消按钮）与关闭（点击关闭按钮或遮罩层、按下 ESC 键）进行区分 | boolean | — | false |
+| lockScroll | 是否在 MessageBox 出现时将 body 滚动锁定 | boolean | — | true |
+| showCancelButton | 是否显示取消按钮 | boolean | — | false（以 confirm 和 prompt 方式调用时为 true） |
+| showConfirmButton | 是否显示确定按钮 | boolean | — | true |
+| cancelButtonText | 取消按钮的文本内容 | string | — | 取消 |
+| confirmButtonText | 确定按钮的文本内容 | string | — | 确定 |
+| cancelButtonClass | 取消按钮的自定义类名 | string | — | — |
+| confirmButtonClass | 确定按钮的自定义类名 | string | — | — |
+| closeOnClickModal | 是否可通过点击遮罩关闭 MessageBox | boolean | — | true（以 alert 方式调用时为 false） |
+| closeOnPressEscape | 是否可通过按下 ESC 键关闭 MessageBox | boolean | — | true（以 alert 方式调用时为 false） |
+| closeOnHashChange | 是否在 hashchange 时关闭 MessageBox | boolean | — | true |
+| showInput | 是否显示输入框 | boolean | — | false（以 prompt 方式调用时为 true）|
+| inputPlaceholder | 输入框的占位符 | string | — | — |
+| inputType | 输入框的类型 | string | — | text |
+| inputValue | 输入框的初始文本 | string | — | — |
+| inputPattern | 输入框的校验表达式 | regexp | — | — |
+| inputValidator | 输入框的校验函数。可以返回布尔值或字符串，若返回一个字符串, 则返回结果会被赋值给 inputErrorMessage | function | — | — |
+| inputErrorMessage | 校验未通过时的提示文本 | string | — | 输入的数据不合法! |
+| center | 是否居中布局 | boolean | — | false |
+| roundButton | 是否使用圆角按钮 | boolean | — | false |

package/docs/pitElementUi/message.md

@@ -0,0 +1,219 @@
+## Message 消息提示
+
+常用于主动操作后的反馈提示。与 Notification 的区别是后者更多用于系统级通知的被动提醒。
+
+### 基础用法
+
+从顶部出现，3 秒后自动消失。
+
+:::demo Message 在配置上与 Notification 非常类似，所以部分 options 在此不做详尽解释，文末有 options 列表，可以结合 Notification 的文档理解它们。Element 注册了一个`$message`方法用于调用，Message 可以接收一个字符串或一个 VNode 作为参数，它会被显示为正文内容。
+
+```html
+<template>
+  <el-button :plain="true" @click="open">打开消息提示</el-button>
+  <el-button :plain="true" @click="openVn">VNode</el-button>
+</template>
+
+<script>
+  export default {
+    methods: {
+      open() {
+        this.$message('这是一条消息提示');
+      },
+
+      openVn() {
+        const h = this.$createElement;
+        this.$message({
+          message: h('p', null, [
+            h('span', null, '内容可以是 '),
+            h('i', { style: 'color: teal' }, 'VNode')
+          ])
+        });
+      }
+    }
+  }
+</script>
+```
+:::
+
+### 不同状态
+
+用来显示「成功、警告、消息、错误」类的操作反馈。
+
+:::demo 当需要自定义更多属性时，Message 也可以接收一个对象为参数。比如，设置`type`字段可以定义不同的状态，默认为`info`。此时正文内容以`message`的值传入。同时，我们也为 Message 的各种 type 注册了方法，可以在不传入`type`字段的情况下像`open4`那样直接调用。
+```html
+<template>
+  <el-button :plain="true" @click="open2">成功</el-button>
+  <el-button :plain="true" @click="open3">警告</el-button>
+  <el-button :plain="true" @click="open1">消息</el-button>
+  <el-button :plain="true" @click="open4">错误</el-button>
+</template>
+
+<script>
+  export default {
+    methods: {
+      open1() {
+        this.$message('这是一条消息提示');
+      },
+      open2() {
+        this.$message({
+          message: '恭喜你，这是一条成功消息',
+          type: 'success'
+        });
+      },
+
+      open3() {
+        this.$message({
+          message: '警告哦，这是一条警告消息',
+          type: 'warning'
+        });
+      },
+
+      open4() {
+        this.$message.error('错了哦，这是一条错误消息');
+      }
+    }
+  }
+</script>
+```
+:::
+
+### 可关闭
+
+可以添加关闭按钮。
+
+:::demo 默认的 Message 是不可以被人工关闭的，如果需要可手动关闭的 Message，可以使用`showClose`字段。此外，和 Notification 一样，Message 拥有可控的`duration`，设置`0`为不会被自动关闭，默认为 3000 毫秒。
+```html
+<template>
+  <el-button :plain="true" @click="open1">消息</el-button>
+  <el-button :plain="true" @click="open2">成功</el-button>
+  <el-button :plain="true" @click="open3">警告</el-button>
+  <el-button :plain="true" @click="open4">错误</el-button>
+</template>
+
+<script>
+  export default {
+    methods: {
+      open1() {
+        this.$message({
+          showClose: true,
+          message: '这是一条消息提示'
+        });
+      },
+
+      open2() {
+        this.$message({
+          showClose: true,
+          message: '恭喜你，这是一条成功消息',
+          type: 'success'
+        });
+      },
+
+      open3() {
+        this.$message({
+          showClose: true,
+          message: '警告哦，这是一条警告消息',
+          type: 'warning'
+        });
+      },
+
+      open4() {
+        this.$message({
+          showClose: true,
+          message: '错了哦，这是一条错误消息',
+          type: 'error'
+        });
+      }
+    }
+  }
+</script>
+```
+:::
+
+### 文字居中
+使用 `center` 属性让文字水平居中。
+
+:::demo
+
+```html
+<template>
+  <el-button :plain="true" @click="openCenter">文字居中</el-button>
+</template>
+
+<script>
+  export default {
+    methods: {
+      openCenter() {
+        this.$message({
+          message: '居中的文字',
+          center: true
+        });
+      }
+    }
+  }
+</script>
+```
+:::
+
+### 使用 HTML 片段
+`message` 属性支持传入 HTML 片段
+
+:::demo 将`dangerouslyUseHTMLString`属性设置为 true，`message` 就会被当作 HTML 片段处理。
+
+```html
+<template>
+  <el-button :plain="true" @click="openHTML">使用 HTML 片段</el-button>
+</template>
+
+<script>
+  export default {
+    methods: {
+      openHTML() {
+        this.$message({
+          dangerouslyUseHTMLString: true,
+          message: '<strong>这是 <i>HTML</i> 片段</strong>'
+        });
+      }
+    }
+  }
+</script>
+```
+:::
+
+:::warning
+`message` 属性虽然支持传入 HTML 片段，但是在网站上动态渲染任意 HTML 是非常危险的，因为容易导致 [XSS 攻击](https://en.wikipedia.org/wiki/Cross-site_scripting)。因此在 `dangerouslyUseHTMLString` 打开的情况下，请确保 `message` 的内容是可信的，**永远不要**将用户提交的内容赋值给 `message` 属性。
+:::
+
+### 全局方法
+
+Element 为 Vue.prototype 添加了全局方法 $message。因此在 vue instance 中可以采用本页面中的方式调用 `Message`。
+
+### 单独引用
+
+单独引入 `Message`：
+
+```javascript
+import { Message } from 'element-ui';
+```
+
+此时调用方法为 `Message(options)`。我们也为每个 type 定义了各自的方法，如 `Message.success(options)`。并且可以调用 `Message.closeAll()` 手动关闭所有实例。
+
+### Options
+| 参数      | 说明          | 类型      | 可选值                           | 默认值  |
+|---------- |-------------- |---------- |--------------------------------  |-------- |
+| message | 消息文字 | string / VNode | — | — |
+| type | 主题 | string | success/warning/info/error | info |
+| iconClass | 自定义图标的类名，会覆盖 `type` | string | — | — |
+| dangerouslyUseHTMLString | 是否将 message 属性作为 HTML 片段处理 | boolean | — | false |
+| customClass | 自定义类名 | string | — | — |
+| duration | 显示时间, 毫秒。设为 0 则不会自动关闭 | number | — | 3000 |
+| showClose | 是否显示关闭按钮 | boolean | — | false |
+| center | 文字是否居中 | boolean | — | false |
+| onClose | 关闭时的回调函数, 参数为被关闭的 message 实例 | function | — | — |
+| offset | Message 距离窗口顶部的偏移量 | number | — | 20 |
+
+### 方法
+调用 `Message` 或 `this.$message` 会返回当前 Message 的实例。如果需要手动关闭实例，可以调用它的 `close` 方法。
+| 方法名 | 说明 |
+| ---- | ---- |
+| close | 关闭当前的 Message |