From 1cae35d26d8ef85a70f05ff22d43f9f899a9e88b Mon Sep 17 00:00:00 2001
From: Yunfei Shen <shenyf0608@163.com>
Date: Wed, 3 Apr 2024 00:29:29 +0800
Subject: [PATCH] docs(dialog): mention destroy DOM elements in dialog.md
 (#3125)

* docs(dialog): mention destroy DOM elements in dialog.md

* docs(dialog): add more specific description in dialog.md

* docs(dialog): update translations in dialog.en-US.md

* docs(dialog): update colons in dialog.en-US.md
---
 src/dialog/dialog.en-US.md | 94 ++++++++++++++++++++++++++------------
 src/dialog/dialog.md       | 31 +++++++------
 2 files changed, 82 insertions(+), 43 deletions(-)

diff --git a/src/dialog/dialog.en-US.md b/src/dialog/dialog.en-US.md
index bd3b37d56..8707ab8c4 100644
--- a/src/dialog/dialog.en-US.md
+++ b/src/dialog/dialog.en-US.md
@@ -1,30 +1,64 @@
 :: BASE_DOC ::
 
+### Plugin or function invocations
+
+#### Plugin invocations
+
+- `this.$dialog(options)`, or
+
+- `this.$dialog.confirm(options)`, or
+
+- `this.$dialog.alert(options)`
+
+#### Function invocations
+
+- `DialogPlugin(options)`, or
+
+- `DialogPlugin.confirm(options)`, or
+
+- `DialogPlugin.alert(options)`
+
+#### Component instance methods
+
+A component instance refers to `DialogInstance = this.$dialog(options)` or `DialogInstance = DialogPlugin(options)`.
+
+- Destroying a dialog: `DialogInstance.destroy()`
+
+- Hiding a dialog: `DialogInstance.hide()`
+
+- Showing a dialog: `DialogInstance.show()`
+
+- Updating a dialog: `DialogInstance.update()`
+
+Note that in the following demo, there are multiple instances where DOM elements are not being destroyed. In real-world applications, it is important to consider destroying DOM elements. Otherwise, when users repeatedly click and create instances from plugin or function invocations, a large number of DOM elements can accumulate, leading to potential memory leaks.
+
+{{ plugin }}
+
 ## API
 ### DialogCard Props
 
 name | type | default | description | required
 -- | -- | -- | -- | --
-`Pick<DialogProps, 'body' \| 'cancelBtn' \| 'closeBtn' \| 'confirmBtn' \| 'footer' \| 'header' \| 'theme' \| 'onCancel' \| 'onCloseBtnClick' \| 'onConfirm'>` | String / Slot / Function | - | extends `Pick<DialogProps, 'body' \| 'cancelBtn' \| 'closeBtn' \| 'confirmBtn' \| 'footer' \| 'header' \| 'theme' \| 'onCancel' \| 'onCloseBtnClick' \| 'onConfirm'>`。Typescript：`string \| TNode`。[see more ts definition](https://github.com/Tencent/tdesign-vue/blob/develop/src/common.ts) | N
+`Pick<DialogProps, 'body' \| 'cancelBtn' \| 'closeBtn' \| 'confirmBtn' \| 'footer' \| 'header' \| 'theme' \| 'onCancel' \| 'onCloseBtnClick' \| 'onConfirm'>` | String / Slot / Function | - | extends `Pick<DialogProps, 'body' \| 'cancelBtn' \| 'closeBtn' \| 'confirmBtn' \| 'footer' \| 'header' \| 'theme' \| 'onCancel' \| 'onCloseBtnClick' \| 'onConfirm'>`. Typescript: `string \| TNode`. [see more ts definition](https://github.com/Tencent/tdesign-vue/blob/develop/src/common.ts) | N
 
 ### Dialog Props
 
 name | type | default | description | required
 -- | -- | -- | -- | --
-attach | String / Function | - | Typescript：`AttachNode`。[see more ts definition](https://github.com/Tencent/tdesign-vue/blob/develop/src/common.ts) | N
-body | String / Slot / Function | - | Typescript：`string \| TNode`。[see more ts definition](https://github.com/Tencent/tdesign-vue/blob/develop/src/common.ts) | N
-cancelBtn | String / Object / Slot / Function | - | Typescript：`string \| ButtonProps \| TNode \| null`，[Button API Documents](./button?tab=api)。[see more ts definition](https://github.com/Tencent/tdesign-vue/blob/develop/src/common.ts)。[see more ts definition](https://github.com/Tencent/tdesign-vue/tree/develop/src/dialog/type.ts) | N
-closeBtn | String / Boolean / Slot / Function | true | Typescript：`string \| boolean \| TNode`。[see more ts definition](https://github.com/Tencent/tdesign-vue/blob/develop/src/common.ts) | N
+attach | String / Function | - | Typescript: `AttachNode`. [see more ts definition](https://github.com/Tencent/tdesign-vue/blob/develop/src/common.ts) | N
+body | String / Slot / Function | - | Typescript: `string \| TNode`. [see more ts definition](https://github.com/Tencent/tdesign-vue/blob/develop/src/common.ts) | N
+cancelBtn | String / Object / Slot / Function | - | Typescript: `string \| ButtonProps \| TNode \| null`，[Button API Documents](./button?tab=api). [see more ts definition](https://github.com/Tencent/tdesign-vue/blob/develop/src/common.ts). [see more ts definition](https://github.com/Tencent/tdesign-vue/tree/develop/src/dialog/type.ts) | N
+closeBtn | String / Boolean / Slot / Function | true | Typescript: `string \| boolean \| TNode`. [see more ts definition](https://github.com/Tencent/tdesign-vue/blob/develop/src/common.ts) | N
 closeOnEscKeydown | Boolean | true | \- | N
 closeOnOverlayClick | Boolean | true | \- | N
-confirmBtn | String / Object / Slot / Function | - | Typescript：`string \| ButtonProps \| TNode \| null`。[see more ts definition](https://github.com/Tencent/tdesign-vue/blob/develop/src/common.ts) | N
+confirmBtn | String / Object / Slot / Function | - | Typescript: `string \| ButtonProps \| TNode \| null`. [see more ts definition](https://github.com/Tencent/tdesign-vue/blob/develop/src/common.ts) | N
 confirmLoading | Boolean | undefined | confirm button loading status | N
 confirmOnEnter | Boolean | - | confirm on enter | N
-default | String / Slot / Function | - | Typescript：`string \| TNode`。[see more ts definition](https://github.com/Tencent/tdesign-vue/blob/develop/src/common.ts) | N
+default | String / Slot / Function | - | Typescript: `string \| TNode`. [see more ts definition](https://github.com/Tencent/tdesign-vue/blob/develop/src/common.ts) | N
 destroyOnClose | Boolean | false | \- | N
 draggable | Boolean | false | \- | N
-footer | Boolean / Slot / Function | true | Typescript：`boolean \| TNode`。[see more ts definition](https://github.com/Tencent/tdesign-vue/blob/develop/src/common.ts) | N
-header | String / Boolean / Slot / Function | true | Typescript：`string \| boolean \| TNode`。[see more ts definition](https://github.com/Tencent/tdesign-vue/blob/develop/src/common.ts) | N
+footer | Boolean / Slot / Function | true | Typescript: `boolean \| TNode`. [see more ts definition](https://github.com/Tencent/tdesign-vue/blob/develop/src/common.ts) | N
+header | String / Boolean / Slot / Function | true | Typescript: `string \| boolean \| TNode`. [see more ts definition](https://github.com/Tencent/tdesign-vue/blob/develop/src/common.ts) | N
 mode | String | modal | options: modal/modeless/full-screen | N
 placement | String | top | options: top/center | N
 preventScrollThrough | Boolean | true | \- | N
@@ -35,21 +69,21 @@ top | String / Number | - | \- | N
 visible | Boolean | - | \- | N
 width | String / Number | - | \- | N
 zIndex | Number | - | \- | N
-onCancel | Function |  | Typescript：`(context: { e: MouseEvent }) => void`<br/> | N
-onClose | Function |  | Typescript：`(context: DialogCloseContext) => void`<br/>[see more ts definition](https://github.com/Tencent/tdesign-vue/tree/develop/src/dialog/type.ts)。<br/>`type DialogEventSource = 'esc' \| 'close-btn' \| 'cancel' \| 'overlay'`<br/><br/>`interface DialogCloseContext { trigger: DialogEventSource; e: MouseEvent \| KeyboardEvent }`<br/> | N
-onCloseBtnClick | Function |  | Typescript：`(context: { e: MouseEvent }) => void`<br/> | N
-onClosed | Function |  | Typescript：`() => void`<br/> | N
-onConfirm | Function |  | Typescript：`(context: { e: MouseEvent \| KeyboardEvent }) => void`<br/> | N
-onEscKeydown | Function |  | Typescript：`(context: { e: KeyboardEvent }) => void`<br/> | N
-onOpened | Function |  | Typescript：`() => void`<br/> | N
-onOverlayClick | Function |  | Typescript：`(context: { e: MouseEvent }) => void`<br/> | N
+onCancel | Function |  | Typescript: `(context: { e: MouseEvent }) => void`<br/> | N
+onClose | Function |  | Typescript: `(context: DialogCloseContext) => void`<br/>[see more ts definition](https://github.com/Tencent/tdesign-vue/tree/develop/src/dialog/type.ts). <br/>`type DialogEventSource = 'esc' \| 'close-btn' \| 'cancel' \| 'overlay'`<br/><br/>`interface DialogCloseContext { trigger: DialogEventSource; e: MouseEvent \| KeyboardEvent }`<br/> | N
+onCloseBtnClick | Function |  | Typescript: `(context: { e: MouseEvent }) => void`<br/> | N
+onClosed | Function |  | Typescript: `() => void`<br/> | N
+onConfirm | Function |  | Typescript: `(context: { e: MouseEvent \| KeyboardEvent }) => void`<br/> | N
+onEscKeydown | Function |  | Typescript: `(context: { e: KeyboardEvent }) => void`<br/> | N
+onOpened | Function |  | Typescript: `() => void`<br/> | N
+onOverlayClick | Function |  | Typescript: `(context: { e: MouseEvent }) => void`<br/> | N
 
 ### Dialog Events
 
 name | params | description
 -- | -- | --
 cancel | `(context: { e: MouseEvent })` | \-
-close | `(context: DialogCloseContext)` | [see more ts definition](https://github.com/Tencent/tdesign-vue/tree/develop/src/dialog/type.ts)。<br/>`type DialogEventSource = 'esc' \| 'close-btn' \| 'cancel' \| 'overlay'`<br/><br/>`interface DialogCloseContext { trigger: DialogEventSource; e: MouseEvent \| KeyboardEvent }`<br/>
+close | `(context: DialogCloseContext)` | [see more ts definition](https://github.com/Tencent/tdesign-vue/tree/develop/src/dialog/type.ts). <br/>`type DialogEventSource = 'esc' \| 'close-btn' \| 'cancel' \| 'overlay'`<br/><br/>`interface DialogCloseContext { trigger: DialogEventSource; e: MouseEvent \| KeyboardEvent }`<br/>
 close-btn-click | `(context: { e: MouseEvent })` | \-
 closed | \- | \-
 confirm | `(context: { e: MouseEvent \| KeyboardEvent })` | \-
@@ -61,9 +95,9 @@ overlay-click | `(context: { e: MouseEvent })` | \-
 
 name | type | default | description | required
 -- | -- | -- | -- | --
-attach | String / Function | 'body' | Typescript：`AttachNode`。[see more ts definition](https://github.com/Tencent/tdesign-vue/blob/develop/src/common.ts) | N
+attach | String / Function | 'body' | Typescript: `AttachNode`. [see more ts definition](https://github.com/Tencent/tdesign-vue/blob/develop/src/common.ts) | N
 className | String | - | \- | N
-style | String / Object | - | Typescript：`string \| Styles`。[see more ts definition](https://github.com/Tencent/tdesign-vue/blob/develop/src/common.ts) | N
+style | String / Object | - | Typescript: `string \| Styles`. [see more ts definition](https://github.com/Tencent/tdesign-vue/blob/develop/src/common.ts) | N
 `Omit<DialogProps, 'attach'>` | \- | - | extends `Omit<DialogProps, 'attach'>` | N
 
 ### DialogInstance
@@ -72,36 +106,36 @@ name | params | return | description
 -- | -- | -- | --
 destroy | \- | \- | required
 hide | \- | \- | required
-setConfirmLoading | `(loading: boolean)` | \- | required。set confirm button loading status
+setConfirmLoading | `(loading: boolean)` | \- | required. set confirm button loading status
 show | \- | \- | required
 update | `(props: DialogOptions)` | \- | required
 
 ### DialogPlugin
 
-同时也支持 `this.$dialog`。
+Also supports `this.$dialog`.
 
 name | params | default | description
 -- | -- | -- | --
-options | \- | - | Typescript：`DialogOptions`
+options | \- | - | Typescript: `DialogOptions`
 
-插件返回值：`DialogInstance`
+The plugin returns `DialogInstance`.
 
 ### DialogPlugin.confirm
 
-同时也支持 `this.$dialog.confirm`。
+Also supports `this.$dialog.confirm`.
 
 name | params | default | description
 -- | -- | -- | --
-options | \- | - | Typescript：`DialogOptions`
+options | \- | - | Typescript: `DialogOptions`
 
-插件返回值：`DialogInstance`
+The plugin returns `DialogInstance`.
 
 ### DialogPlugin.alert
 
-同时也支持 `this.$dialog.alert`。
+Also supports `this.$dialog.alert`.
 
 name | params | default | description
 -- | -- | -- | --
-options | Object | - | Typescript：`Omit<DialogOptions, 'cancelBtn'>`
+options | Object | - | Typescript: `Omit<DialogOptions, 'cancelBtn'>`
 
-插件返回值：`DialogInstance`
+The plugin returns `DialogInstance`.
diff --git a/src/dialog/dialog.md b/src/dialog/dialog.md
index 1984be61a..88d3eac51 100644
--- a/src/dialog/dialog.md
+++ b/src/dialog/dialog.md
@@ -1,31 +1,36 @@
 :: BASE_DOC ::
 
 ### 插件函数式调用
-插件调用方式一：`this.$dialog(options)`
 
-插件调用方式二：`this.$dialog.confirm(options)`
+#### 插件调用
 
-插件调用方式三：`this.$dialog.alert(options)`
+- 方式一：`this.$dialog(options)`
 
-<br />
+- 方式二：`this.$dialog.confirm(options)`
 
-函数调用方式一：`DialogPlugin(options)`
+- 方式三：`this.$dialog.alert(options)`
 
-函数调用方式二：`DialogPlugin.confirm(options)`
+#### 函数调用
 
-函数调用方式三：`DialogPlugin.alert(options)`
+- 方式一：`DialogPlugin(options)`
 
-<br />
+- 方式二：`DialogPlugin.confirm(options)`
 
-组件实例：`DialogInstance = this.$dialog(options)` 或者 组件实例：`DialogInstance = DialogPlugin(options)`
+- 方式三：`DialogPlugin.alert(options)`
 
-组件实例方法-销毁弹框：`DialogInstance.destroy()`
+#### 组件实例方法
 
-组件实例方法-隐藏弹框：`DialogInstance.hide()`
+组件实例指的是 `DialogInstance = this.$dialog(options)` 或者 `DialogInstance = DialogPlugin(options)`。
 
-组件实例方法-显示弹窗：`DialogInstance.show()`
+- 销毁弹框：`DialogInstance.destroy()`
 
-组件实例方法-更新弹框：`DialogInstance.update()`
+- 隐藏弹框：`DialogInstance.hide()`
+
+- 显示弹窗：`DialogInstance.show()`
+
+- 更新弹框：`DialogInstance.update()`
+
+注意在以下使用示例中，有多处并未销毁 DOM 元素。在实际应用中，需要考虑销毁 DOM 元素，否则当用户重复点击、创建插件或函数调用的实例后，会产生大量 DOM 元素、容易造成内存泄漏。
 
 {{ plugin }}