Skip to content

Commit

Permalink
docs(dialog): mention destroy DOM elements in dialog.md (#3125)
Browse files Browse the repository at this point in the history 
* 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
  • Loading branch information
@Summer-Shen
Summer-Shen authored Apr 2, 2024
1 parent 78201c1 commit 1cae35d
Show file tree
Hide file tree
Showing 2 changed files with 82 additions and 43 deletions.
94 changes: 64 additions & 30 deletions src/dialog/dialog.en-US.md
View file
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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 })` | \-
Expand All @@ -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
Expand All @@ -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`.
31 changes: 18 additions & 13 deletions src/dialog/dialog.md
View file
Original file line number Diff line number Diff line change
@@ -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 }}

Expand Down

0 comments on commit 1cae35d

Please sign in to comment.