mirror/element-plus
2
0
Fork 0
mirror of https://github.com/element-plus/element-plus.git synced 2024-11-21 01:02:59 +08:00
Code Issues Packages Projects Releases Wiki Activity

feat(components): [message-box] allow pass function to message option (#9405)

Browse Source 
* feat(components): [message-box] allow pass function to `message` option

* chore: update docs

* chore: update docs
This commit is contained in:
zz 2022-09-04 20:38:18 +08:00 committed by GitHub
parent acc7092901
commit 6eded0bae8
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
4 changed files with 63 additions and 29 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

26
docs/en-US/component/message-box.md
View File

@ -17,7 +17,7 @@ By design MessageBox provides simulations of system's `alert`, `confirm` and `pr
Alert interrupts user operation until the user confirms.
:::demo Open an alert by calling the `$alert` method. It simulates the system's `alert`, and cannot be closed by pressing ESC or clicking outside the box. In this example, two parameters `message` and `title` are received. It is worth mentioning that when the box is closed, it returns a `Promise` object for further processing. If you are not sure if your target browsers support `Promise`, you should import a third party polyfill or use callbacks instead like this example.
:::demo Open an alert by calling the `ElMessageBox.alert` method. It simulates the system's `alert`, and cannot be closed by pressing ESC or clicking outside the box. In this example, two parameters `message` and `title` are received. It is worth mentioning that when the box is closed, it returns a `Promise` object for further processing. If you are not sure if your target browsers support `Promise`, you should import a third party polyfill or use callbacks instead like this example.
message-box/alert
@ -27,7 +27,7 @@ message-box/alert
Confirm is used to ask users' confirmation.
:::demo Call `$confirm` method to open a confirm, and it simulates the system's `confirm`. We can also highly customize Message Box by passing a third attribute `options` which is a literal object. The attribute `type` indicates the message type, and it's value can be `success`, `error`, `info` and `warning`. Note that the second attribute `title` must be a `string`, and if it is an `object`, it will be handled as the attribute `options`. Here we use `Promise` to handle further processing.
:::demo Call `ElMessageBox.confirm` method to open a confirm, and it simulates the system's `confirm`. We can also highly customize Message Box by passing a third attribute `options` which is a literal object. The attribute `type` indicates the message type, and it's value can be `success`, `error`, `info` and `warning`. Note that the second attribute `title` must be a `string`, and if it is an `object`, it will be handled as the attribute `options`. Here we use `Promise` to handle further processing.
message-box/confirm
@ -37,28 +37,32 @@ message-box/confirm
Prompt is used when user input is required.
:::demo Call `$prompt` method to open a prompt, and it simulates the system's `prompt`. You can use `inputPattern` parameter to specify your own RegExp pattern. Use `inputValidator` to specify validation method, and it should return `Boolean` or `String`. Returning `false` or `String` means the validation has failed, and the string returned will be used as the `inputErrorMessage`. In addition, you can customize the placeholder of the input box with `inputPlaceholder` parameter.
:::demo Call `ElMessageBox.prompt` method to open a prompt, and it simulates the system's `prompt`. You can use `inputPattern` parameter to specify your own RegExp pattern. Use `inputValidator` to specify validation method, and it should return `Boolean` or `String`. Returning `false` or `String` means the validation has failed, and the string returned will be used as the `inputErrorMessage`. In addition, you can customize the placeholder of the input box with `inputPlaceholder` parameter.
message-box/prompt
:::
## Use VNode
`message` can be VNode.
:::demo
message-box/use-vnode
:::
## Customization
Can be customized to show various content.
:::demo The three methods mentioned above are repackagings of the `$msgbox` method. This example calls `$msgbox` method directly using the `showCancelButton` attribute, which is used to indicate if a cancel button is displayed. Besides we can use `cancelButtonClass` to add a custom style and `cancelButtonText` to customize the button text (the confirm button also has these fields, and a complete list of fields can be found at the end of this documentation). This example also uses the `beforeClose` attribute. It is a method and will be triggered when the MessageBox instance will be closed, and its execution will stop the instance from closing. It has three parameters: `action`, `instance` and `done`. Using it enables you to manipulate the instance before it closes, e.g. activating `loading` for confirm button; you can invoke the `done` method to close the MessageBox instance (if `done` is not called inside `beforeClose`, the instance will not be closed).
:::demo The three methods mentioned above are repackagings of the `ElMessageBox` method. This example calls `ElMessageBox` method directly using the `showCancelButton` attribute, which is used to indicate if a cancel button is displayed. Besides we can use `cancelButtonClass` to add a custom style and `cancelButtonText` to customize the button text (the confirm button also has these fields, and a complete list of fields can be found at the end of this documentation). This example also uses the `beforeClose` attribute. It is a method and will be triggered when the MessageBox instance will be closed, and its execution will stop the instance from closing. It has three parameters: `action`, `instance` and `done`. Using it enables you to manipulate the instance before it closes, e.g. activating `loading` for confirm button; you can invoke the `done` method to close the MessageBox instance (if `done` is not called inside `beforeClose`, the instance will not be closed).
message-box/customization
:::
:::tip
The content of MessageBox can be `VNode`, allowing us to pass custom components. When opening the MessageBox, Vue compares new `VNode` with old `VNode`, then figures out how to efficiently update the UI, so the components may not be completely re-rendered ([#8931](https://github.com/ElemeFE/element/issues/8931)). In this case, you can add a unique key to `VNode` each time MessageBox opens: [example](https://jsfiddle.net/zhiyang/ezmhq2ef).
:::
## Use HTML String
`message` supports HTML string.
@ -156,7 +160,7 @@ The corresponding methods are: `ElMessageBox`, `ElMessageBox.alert`, `ElMessageB
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- | ------------------------------------------------ |
| autofocus | auto focus when open MessageBox | boolean | — | true |
| title | title of the MessageBox | string | — | — |
| message | content of the MessageBox | string | — | — |
| message | content of the MessageBox | `string \| VNode \| (() => VNode)` | — | — |
| dangerouslyUseHTMLString | whether `message` is treated as HTML string | boolean | — | false |
| type | message type, used for icon display | string | success / info / warning / error | — |
| icon | custom icon component, overrides `type` | `string \| Component` | — | — |

34
docs/examples/message-box/use-vnode.vue Normal file
View File

@ -0,0 +1,34 @@
<template>
<el-button plain @click="open">Common VNode</el-button>
<el-button plain @click="open1">Dynamic props</el-button>
</template>
<script lang="ts" setup>
import { h, ref } from 'vue'
import { ElMessageBox, ElSwitch } from 'element-plus'
const open = () => {
ElMessageBox({
title: 'Message',
message: h('p', null, [
h('span', null, 'Message can be '),
h('i', { style: 'color: teal' }, 'VNode'),
]),
})
}
const open1 = () => {
const checked = ref<boolean | string | number>(false)
ElMessageBox({
title: 'Message',
// Should pass a function if VNode contains dynamic props
message: () =>
h(ElSwitch, {
modelValue: checked.value,
'onUpdate:modelValue': (val: boolean | string | number) => {
checked.value = val
},
}),
})
}
</script>

2
packages/components/message-box/src/message-box.type.ts
View File

@ -103,7 +103,7 @@ export interface ElMessageBoxOptions {
draggable?: boolean
/** Content of the MessageBox */
message?: string | VNode
message?: string | VNode | (() => VNode)
/** Title of the MessageBox */
title?: string | ElMessageBoxOptions

30
packages/components/message-box/src/messageBox.ts
View File

@ -1,7 +1,8 @@
import { h, render, watch } from 'vue'
import { createVNode, render } from 'vue'
import { isClient } from '@vueuse/core'
import {
hasOwn,
isFunction,
isObject,
isString,
isUndefined,
@ -37,7 +38,17 @@ const initInstance = (
container: HTMLElement,
appContext: AppContext | null = null
) => {
const vnode = h(MessageBoxConstructor, props)
const vnode = createVNode(
MessageBoxConstructor,
props,
isFunction(props.message) || isVNode(props.message)
? {
default: isFunction(props.message)
? props.message
: () => props.message,
}
: null
)
vnode.appContext = appContext
render(vnode, container)
document.body.appendChild(container.firstElementChild!)
@ -102,21 +113,6 @@ const showMessage = (options: any, appContext?: AppContext | null) => {
}
}
watch(
() => vm.message,
(newVal, oldVal) => {
if (isVNode(newVal)) {
// Override slots since message is vnode type.
instance.slots.default = () => [newVal]
} else if (isVNode(oldVal) && !isVNode(newVal)) {
delete instance.slots.default
}
},
{
immediate: true,
}
)
// change visibility after everything is settled
vm.visible = true
return vm