MessageBox: add distinguishCancelAndClose (#11831)

examples/docs/en-US/message-box.md

@@ -100,6 +100,28 @@
       },
 
       open6() {
+        this.$confirm('You have unsaved changes, save and proceed?', 'Confirm', {
+          distinguishCancelAndClose: true,
+          confirmButtonText: 'Save',
+          cancelButtonText: 'Discard Changes'
+        })
+          .then(() => {
+            this.$message({
+              type: 'info',
+              message: 'Changes saved. Proceeding to a new route.'
+            });
+          })
+          .catch(action => {
+            this.$message({
+              type: 'info',
+              message: action === 'cancel'
+                ? 'Changes discarded. Proceeding to a new route.'
+                : 'Stay in the current route'
+            })
+          });
+      },
+
+      open7() {
         this.$confirm('This will permanently delete the file. Continue?', 'Warning', {
           confirmButtonText: 'OK',
           cancelButtonText: 'Cancel',
@@ -292,6 +314,7 @@ The content of MessageBox can be `VNode`, allowing us to pass custom components.
 :::
 
 ### Use HTML String
+
 `message` supports HTML string.
 
 :::demo Set `dangerouslyUseHTMLString` to true and `message` will be treated as an HTML string.
@@ -319,6 +342,47 @@ The content of MessageBox can be `VNode`, allowing us to pass custom components.
 Although `message` property supports HTML strings, dynamically rendering arbitrary HTML on your website can be very dangerous because it can easily lead to [XSS attacks](https://en.wikipedia.org/wiki/Cross-site_scripting). So when `dangerouslyUseHTMLString` is on, please make sure the content of `message` is trusted, and **never** assign `message` to user-provided content.
 :::
 
+### Distinguishing cancel and close
+
+In some cases, clicking the cancel button and close button may have different meanings.
+
+:::demo By default, the parameters of Promise's reject callback and `callback` are 'cancel' when the user cancels (clicking the cancel button) and closes (clicking the close button or mask layer, pressing the ESC key) the MessageBox. If `distinguishCancelAndClose` is set to true, the parameters of the above two operations are 'cancel' and 'close' respectively.
+
+```html
+<template>
+  <el-button type="text" @click="open6">Click to open Message Box</el-button>
+</template>
+
+<script>
+  export default {
+    methods: {
+      open6() {
+        this.$confirm('You have unsaved changes, save and proceed?', 'Confirm', {
+          distinguishCancelAndClose: true,
+          confirmButtonText: 'Save',
+          cancelButtonText: 'Discard Changes'
+        })
+          .then(() => {
+            this.$message({
+              type: 'info',
+              message: 'Changes saved. Proceeding to a new route.'
+            });
+          })
+          .catch(action => {
+            this.$message({
+              type: 'info',
+              message: action === 'cancel'
+                ? 'Changes discarded. Proceeding to a new route.'
+                : 'Stay in the current route'
+            })
+          });
+      }
+    }
+  }
+</script>
+```
+:::
+
 ### Centered content
 Content of MessageBox can be centered.
 
@@ -326,13 +390,13 @@ Content of MessageBox can be centered.
 
 ```html
 <template>
-  <el-button type="text" @click="open6">Click to open Message Box</el-button>
+  <el-button type="text" @click="open7">Click to open Message Box</el-button>
 </template>
 
 <script>
   export default {
     methods: {
-      open6() {
+      open7() {
         this.$confirm('This will permanently delete the file. Continue?', 'Warning', {
           confirmButtonText: 'OK',
           cancelButtonText: 'Cancel',
@@ -384,9 +448,10 @@ The corresponding methods are: `MessageBox`, `MessageBox.alert`, `MessageBox.con
 | type | message type, used for icon display | string | success / info / warning / error | — |
 | iconClass | custom icon's class, overrides `type` | string | — | — |
 | customClass | custom class name for MessageBox | string | — | — |
-| callback | MessageBox closing callback if you don't prefer Promise | function(action), where action can be 'confirm' or 'cancel', and `instance` is the MessageBox instance. You can access to that instance's attributes and methods | — | — |
+| callback | MessageBox closing callback if you don't prefer Promise | function(action), where action can be 'confirm', 'cancel' or 'close', and `instance` is the MessageBox instance. You can access to that instance's attributes and methods | — | — |
 | showClose | whether to show close icon of MessageBox | boolean | — | true |
-| beforeClose | callback before MessageBox closes, and it will prevent MessageBox from closing | function(action, instance, done), where `action` can be 'confirm' or 'cancel'; `instance` is the MessageBox instance, and you can access to that instance's attributes and methods; `done` is for closing the instance | — | — |
+| beforeClose | callback before MessageBox closes, and it will prevent MessageBox from closing | function(action, instance, done), where `action` can be 'confirm', 'cancel' or 'close'; `instance` is the MessageBox instance, and you can access to that instance's attributes and methods; `done` is for closing the instance | — | — |
+| distinguishCancelAndClose | whether to distinguish canceling and closing the MessageBox | boolean | — | false |
 | lockScroll | whether to lock body scroll when MessageBox prompts | boolean | — | true |
 | showCancelButton | whether to show a cancel button | boolean | — | false (true when called with confirm and prompt) |
 | showConfirmButton | whether to show a confirm button | boolean | — | true |

examples/docs/es/message-box.md

@@ -98,8 +98,30 @@
           dangerouslyUseHTMLString: true
         });
       },
-    
+
       open6() {
+        this.$confirm('You have unsaved changes, save and proceed?', 'Confirm', {
+          distinguishCancelAndClose: true,
+          confirmButtonText: 'Save',
+          cancelButtonText: 'Discard Changes'
+        })
+          .then(() => {
+            this.$message({
+              type: 'info',
+              message: 'Changes saved. Proceeding to a new route.'
+            });
+          })
+          .catch(action => {
+            this.$message({
+              type: 'info',
+              message: action === 'cancel'
+                ? 'Changes discarded. Proceeding to a new route.'
+                : 'Stay in the current route'
+            })
+          });
+      },
+
+      open7() {
         this.$confirm('This will permanently delete the file. Continue?', 'Warning', {
           confirmButtonText: 'OK',
           cancelButtonText: 'Cancel',
@@ -295,6 +317,7 @@ El contenido de MessageBox puede ser `VNode`, permitiéndonos pasar componentes
 :::
 
 ### Utiliza cadenas HTML
+
 `message` soporta cadenas HTML.
 
 :::demo Establezca el valor de `dangerouslyUseHTMLString` a true y `message` sera tratado como una cadena HTML.
@@ -322,6 +345,47 @@ El contenido de MessageBox puede ser `VNode`, permitiéndonos pasar componentes
 Aunque la propiedad `message` soporta cadenas HTML, realizar arbitrariamente render dinamico de HTML en nuestro sitio web puede ser muy peligroso ya que puede conducir facilmente a [XSS attacks](https://en.wikipedia.org/wiki/Cross-site_scripting). Entonces cuando `dangerouslyUseHTMLString` esta activada, asegurece que el contendio de `message` sea de confianza, y **nunca** asignar `message` a contenido generado por el usuario.
 :::
 
+### Distinguishing cancel and close
+
+In some cases, clicking the cancel button and close button may have different meanings.
+
+:::demo By default, the parameters of Promise's reject callback and `callback` are 'cancel' when the user cancels (clicking the cancel button) and closes (clicking the close button or mask layer, pressing the ESC key) the MessageBox. If `distinguishCancelAndClose` is set to true, the parameters of the above two operations are 'cancel' and 'close' respectively.
+
+```html
+<template>
+  <el-button type="text" @click="open6">Click to open Message Box</el-button>
+</template>
+
+<script>
+  export default {
+    methods: {
+      open6() {
+        this.$confirm('You have unsaved changes, save and proceed?', 'Confirm', {
+          distinguishCancelAndClose: true,
+          confirmButtonText: 'Save',
+          cancelButtonText: 'Discard Changes'
+        })
+          .then(() => {
+            this.$message({
+              type: 'info',
+              message: 'Changes saved. Proceeding to a new route.'
+            });
+          })
+          .catch(action => {
+            this.$message({
+              type: 'info',
+              message: action === 'cancel'
+                ? 'Changes discarded. Proceeding to a new route.'
+                : 'Stay in the current route'
+            })
+          });
+      }
+    }
+  }
+</script>
+```
+:::
+
 ### Centered content
 El contenido del componente MessageBox puede ser centrado.
 
@@ -329,13 +393,13 @@ El contenido del componente MessageBox puede ser centrado.
 
 ```html
 <template>
-  <el-button type="text" @click="open6">Click to open Message Box</el-button>
+  <el-button type="text" @click="open7">Click to open Message Box</el-button>
 </template>
 
 <script>
   export default {
     methods: {
-      open6() {
+      open7() {
         this.$confirm('This will permanently delete the file. Continue?', 'Warning', {
           confirmButtonText: 'OK',
           cancelButtonText: 'Cancel',
@@ -387,8 +451,9 @@ Los metodos correspondientes: `MessageBox`, `MessageBox.alert`, `MessageBox.conf
 | type                     | tipo de mensaje , utilizado para mostrar el  icono | string                                   | success / info / warning / error | —                                        |
 | iconClass                | clase personalizada para el icono, sobreescribe `type` | string         | —                          | —           |
 | customClass              | nombre de la clase personzalida para el componente MessageBox | string                                   | —                                | —                                        |
-| callback                 | MessageBox callback al cerrar si no desea utilizar Promise | function(action), donde la accion puede ser 'confirm' o 'cancel', e `instance`  es la instancia del componente MessageBox. Puedes acceder a los metodos y atributos de esa instancia | —                                | —                                        |
-| beforeClose              | callback llamado antes de cerrar el componente MessageBox, y previene que el componente MessageBox se cierre | function(action, instance, done), donde `action` pueden ser 'confirm' o 'cancel'; `instance` es la instancia del componente MessageBox, Puedes acceder a los metodos y atributos de esa instancia; `done` es para cerrar la instancia | —                                | —                                        |
+| callback                 | MessageBox callback al cerrar si no desea utilizar Promise | function(action), donde la accion puede ser 'confirm', 'cancel' o 'close', e `instance`  es la instancia del componente MessageBox. Puedes acceder a los metodos y atributos de esa instancia | —                                | —                                        |
+| beforeClose              | callback llamado antes de cerrar el componente MessageBox, y previene que el componente MessageBox se cierre | function(action, instance, done), donde `action` pueden ser 'confirm', 'cancel' o 'close'; `instance` es la instancia del componente MessageBox, Puedes acceder a los metodos y atributos de esa instancia; `done` es para cerrar la instancia | —                                | —                                        |
+| distinguishCancelAndClose | whether to distinguish canceling and closing the MessageBox | boolean | — | false |
 | lockScroll               | utilizado para bloquear el desplazamiento del contenido del MessageBox prompts | boolean                                  | —                                | true                                     |
 | showCancelButton         | utlizado para mostrar un boton cancelar  | boolean                                  | —                                | false (true cuando es llamado con confirm y prompt) |
 | showConfirmButton        | utlizado para mostrar un boton confirmar | boolean                                  | —                                | true                                     |

examples/docs/zh-CN/message-box.md

@@ -101,6 +101,28 @@
       },
 
       open6() {
+        this.$confirm('检测到未保存的内容，是否在离开页面前保存修改？', '确认信息', {
+          distinguishCancelAndClose: true,
+          confirmButtonText: '保存',
+          cancelButtonText: '放弃修改'
+        })
+          .then(() => {
+            this.$message({
+              type: 'info',
+              message: '保存修改'
+            });
+          })
+          .catch(action => {
+            this.$message({
+              type: 'info',
+              message: action === 'cancel'
+                ? '放弃保存并离开页面'
+                : '停留在当前页面'
+            })
+          });
+      },
+
+      open7() {
         this.$confirm('此操作将永久删除该文件, 是否继续?', '提示', {
           confirmButtonText: '确定',
           cancelButtonText: '取消',
@@ -290,7 +312,8 @@
 :::
 
 ### 使用 HTML 片段
-`message` 属性支持传入 HTML 片段
+
+`message` 属性支持传入 HTML 片段。
 
 :::demo 将`dangerouslyUseHTMLString`属性设置为 true，`message` 就会被当作 HTML 片段处理。
 
@@ -317,6 +340,47 @@
 `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="open6">点击打开 Message Box</el-button>
+</template>
+
+<script>
+  export default {
+    methods: {
+      open6() {
+        this.$confirm('检测到未保存的内容，是否在离开页面前保存修改？', '确认信息', {
+          distinguishCancelAndClose: true,
+          confirmButtonText: '保存',
+          cancelButtonText: '放弃修改'
+        })
+          .then(() => {
+            this.$message({
+              type: 'info',
+              message: '保存修改'
+            });
+          })
+          .catch(action => {
+            this.$message({
+              type: 'info',
+              message: action === 'cancel'
+                ? '放弃保存并离开页面'
+                : '停留在当前页面'
+            })
+          });
+      }
+    }
+  }
+</script>
+```
+:::
+
 ### 居中布局
 内容支持居中布局
 
@@ -324,13 +388,13 @@
 
 ```html
 <template>
-  <el-button type="text" @click="open6">点击打开 Message Box</el-button>
+  <el-button type="text" @click="open7">点击打开 Message Box</el-button>
 </template>
 
 <script>
   export default {
     methods: {
-      open6() {
+      open7() {
         this.$confirm('此操作将永久删除该文件, 是否继续?', '提示', {
           confirmButtonText: '确定',
           cancelButtonText: '取消',
@@ -382,9 +446,10 @@ import { MessageBox } from 'element-ui';
 | type | 消息类型，用于显示图标 | string | success / info / warning / error | — |
 | iconClass | 自定义图标的类名，会覆盖 `type` | string | — | — |
 | customClass | MessageBox 的自定义类名 | string | — | — |
-| callback | 若不使用 Promise，可以使用此参数指定 MessageBox 关闭后的回调 | function(action, instance)，action 的值为'confirm'或'cancel', instance 为 MessageBox 实例，可以通过它访问实例上的属性和方法 | — | — |
+| 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'；instance 为 MessageBox 实例，可以通过它访问实例上的属性和方法；done 用于关闭 MessageBox 实例 | — | — |
+| 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 |

packages/message-box/src/main.js

@@ -29,7 +29,8 @@ const defaults = {
   beforeClose: null,
   dangerouslyUseHTMLString: false,
   center: false,
-  roundButton: false
+  roundButton: false,
+  distinguishCancelAndClose: false
 };
 
 import Vue from 'vue';
@@ -59,7 +60,7 @@ const defaultCallback = action => {
         } else {
           currentMsg.resolve(action);
         }
-      } else if (action === 'cancel' && currentMsg.reject) {
+      } else if (currentMsg.reject && (action === 'cancel' || action === 'close')) {
         currentMsg.reject(action);
       }
     }

packages/message-box/src/main.vue

@@ -22,8 +22,8 @@
             class="el-message-box__headerbtn"
             aria-label="Close"
             v-if="showClose"
-            @click="handleAction('cancel')"
-            @keydown.enter="handleAction('cancel')">
+            @click="handleAction(distinguishCancelAndClose ? 'close' : 'cancel')"
+            @keydown.enter="handleAction(distinguishCancelAndClose ? 'close' : 'cancel')">
             <i class="el-message-box__close el-icon-close"></i>
           </button>
         </div>
@@ -173,7 +173,7 @@
 
       handleWrapperClick() {
         if (this.closeOnClickModal) {
-          this.handleAction('cancel');
+          this.handleAction(this.distinguishCancelAndClose ? 'close' : 'cancel');
         }
       },
 
@@ -319,7 +319,8 @@
         callback: null,
         dangerouslyUseHTMLString: false,
         focusAfterClosed: null,
-        isOnComposition: false
+        isOnComposition: false,
+        distinguishCancelAndClose: false
       };
     }
   };

test/unit/specs/message-box.spec.js

@@ -76,6 +76,24 @@ describe('MessageBox', () => {
     }, 300);
   });
 
+  it('distinguish cancel and close', done => {
+    let msgAction = '';
+    MessageBox({
+      title: '消息',
+      message: '这是一段内容',
+      distinguishCancelAndClose: true
+    }, action => {
+      msgAction = action;
+    });
+    setTimeout(() => {
+      document.querySelector('.el-message-box__close').click();
+      setTimeout(() => {
+        expect(msgAction).to.equal('close');
+        done();
+      }, 10);
+    }, 10);
+  });
+
   it('alert', done => {
     MessageBox.alert('这是一段内容', {
       title: '标题名称',

types/message-box.d.ts

@@ -1,7 +1,7 @@
 import Vue from 'vue'
 import { MessageType } from './message'
 
-export type MessageBoxCloseAction = 'confirm' | 'cancel'
+export type MessageBoxCloseAction = 'confirm' | 'cancel' | 'close'
 export type MessageBoxData = MessageBoxCloseAction | MessageBoxInputData
 
 export interface MessageBoxInputData {