mirror of
https://github.com/ArthurDanjou/ui.git
synced 2026-01-14 12:14:41 +01:00
docs(use-overlay): add caveats section regarding provide/inject limit (#4287)
Co-authored-by: Benjamin Canac <canacb1@gmail.com>
This commit is contained in:
Eugen Istoc
GitHub
@@ -1,6 +1,6 @@
|
||||
---
|
||||
title: useOverlay
|
||||
description: "A composable to programmatically control overlays."
|
||||
description: 'A composable to programmatically control overlays.'
|
||||
---
|
||||
|
||||
## Usage
|
||||
@@ -9,9 +9,11 @@ Use the auto-imported `useOverlay` composable to programmatically control [Modal
|
||||
|
||||
```vue
|
||||
<script setup lang="ts">
|
||||
import { LazyModalExample } from '#components'
|
||||
|
||||
const overlay = useOverlay()
|
||||
|
||||
const modal = overlay.create(MyModal)
|
||||
const modal = overlay.create(LazyModalExample)
|
||||
|
||||
async function openModal() {
|
||||
modal.open()
|
||||
@@ -29,71 +31,73 @@ In order to return a value from the overlay, the `overlay.open().instance.result
|
||||
|
||||
### `create(component: T, options: OverlayOptions): OverlayInstance`
|
||||
|
||||
Creates an overlay, and returns a factory instance
|
||||
Create an overlay, and return a factory instance.
|
||||
|
||||
- Parameters:
|
||||
- `component`: The overlay component
|
||||
- `options` The overlay options
|
||||
- `defaultOpen?: boolean` Opens the overlay immediately after being created `default: false`
|
||||
- `component`: The overlay component.
|
||||
- `options`:
|
||||
- `defaultOpen?: boolean` Open the overlay immediately after being created. Defaults to `false`.
|
||||
- `props?: ComponentProps`: An optional object of props to pass to the rendered component.
|
||||
- `destroyOnClose?: boolean` Removes the overlay from memory when closed `default: false`
|
||||
- `destroyOnClose?: boolean` Removes the overlay from memory when closed. Defaults to `false`.
|
||||
|
||||
### `open(id: symbol, props?: ComponentProps<T>): OpenedOverlay<T>`
|
||||
|
||||
Opens the overlay using its `id`
|
||||
Open an overlay by its `id`.
|
||||
|
||||
- Parameters:
|
||||
- `id`: The identifier of the overlay
|
||||
- `id`: The identifier of the overlay.
|
||||
- `props`: An optional object of props to pass to the rendered component.
|
||||
|
||||
### `close(id: symbol, value?: any): void`
|
||||
|
||||
Close an overlay using its `id`
|
||||
Close an overlay by its `id`.
|
||||
|
||||
- Parameters:
|
||||
- `id`: The identifier of the overlay
|
||||
- `value`: A value to resolve the overlay promise with
|
||||
- `id`: The identifier of the overlay.
|
||||
- `value`: A value to resolve the overlay promise with.
|
||||
|
||||
### `patch(id: symbol, props: ComponentProps<T>): void`
|
||||
|
||||
Update an overlay using its `id`
|
||||
Update an overlay by its `id`.
|
||||
|
||||
- Parameters:
|
||||
- `id`: The identifier of the overlay
|
||||
- `id`: The identifier of the overlay.
|
||||
- `props`: An object of props to update on the rendered component.
|
||||
|
||||
### `unmount(id: symbol): void`
|
||||
|
||||
Removes the overlay from the DOM using its `id`
|
||||
Remove an overlay from the DOM by its `id`.
|
||||
|
||||
- Parameters:
|
||||
- `id`: The identifier of the overlay
|
||||
- `id`: The identifier of the overlay.
|
||||
|
||||
### `isOpen(id: symbol): boolean`
|
||||
|
||||
Checks if an overlay its open using its `id`
|
||||
Check if an overlay is open using its `id`.
|
||||
|
||||
- Parameters:
|
||||
- `id`: The identifier of the overlay
|
||||
- `id`: The identifier of the overlay.
|
||||
|
||||
### `overlays: Overlay[]`
|
||||
|
||||
In-memory list of overlays that were created
|
||||
In-memory list of all overlays that were created.
|
||||
|
||||
## Overlay Instance API
|
||||
## Instance API
|
||||
|
||||
### `open(props?: ComponentProps<T>): Promise<OpenedOverlay<T>>`
|
||||
|
||||
Opens the overlay
|
||||
Open the overlay.
|
||||
|
||||
- Parameters:
|
||||
- `props`: An optional object of props to pass to the rendered component.
|
||||
|
||||
```vue
|
||||
<script setup lang="ts">
|
||||
import { LazyModalExample } from '#components'
|
||||
|
||||
const overlay = useOverlay()
|
||||
|
||||
const modal = overlay.create(MyModalContent)
|
||||
const modal = overlay.create(LazyModalExample)
|
||||
|
||||
function openModal() {
|
||||
modal.open({
|
||||
@@ -105,23 +109,25 @@ function openModal() {
|
||||
|
||||
### `close(value?: any): void`
|
||||
|
||||
Close the overlay
|
||||
Close the overlay.
|
||||
|
||||
- Parameters:
|
||||
- `value`: A value to resolve the overlay promise with
|
||||
- `value`: A value to resolve the overlay promise with.
|
||||
|
||||
### `patch(props: ComponentProps<T>)`
|
||||
|
||||
Updates the props of the overlay.
|
||||
Update the props of the overlay.
|
||||
|
||||
- Parameters:
|
||||
- `props`: An object of props to update on the rendered component.
|
||||
|
||||
```vue
|
||||
<script setup lang="ts">
|
||||
import { LazyModalExample } from '#components'
|
||||
|
||||
const overlay = useOverlay()
|
||||
|
||||
const modal = overlay.create(MyModal, {
|
||||
const modal = overlay.create(LazyModalExample, {
|
||||
title: 'Welcome'
|
||||
})
|
||||
|
||||
@@ -141,6 +147,8 @@ Here's a complete example of how to use the `useOverlay` composable:
|
||||
|
||||
```vue
|
||||
<script setup lang="ts">
|
||||
import { ModalA, ModalB, SlideoverA } from '#components'
|
||||
|
||||
const overlay = useOverlay()
|
||||
|
||||
// Create with default props
|
||||
@@ -150,7 +158,7 @@ const modalB = overlay.create(ModalB)
|
||||
const slideoverA = overlay.create(SlideoverA)
|
||||
|
||||
const openModalA = () => {
|
||||
// Open Modal A, but override the title prop
|
||||
// Open modalA, but override the title prop
|
||||
modalA.open({ title: 'Hello' })
|
||||
}
|
||||
|
||||
@@ -160,16 +168,37 @@ const openModalB = async () => {
|
||||
|
||||
const input = await modalBInstance.result
|
||||
|
||||
// Pass the result from modalB to the slideover, and open it.
|
||||
// Pass the result from modalB to the slideover, and open it
|
||||
slideoverA.open({ input })
|
||||
}
|
||||
</script>
|
||||
|
||||
<template>
|
||||
<div>
|
||||
<button @click="openModal">Open Modal</button>
|
||||
</div>
|
||||
<button @click="openModalA">Open Modal</button>
|
||||
</template>
|
||||
```
|
||||
|
||||
In this example, we're using the `useOverlay` composable to control multiple modals and slideovers.
|
||||
|
||||
## Caveats
|
||||
|
||||
### Provide / Inject
|
||||
|
||||
When opening overlays programmatically (e.g. modals, slideovers, etc), the overlay component can only access injected values from the component containing `UApp` (typically `app.vue` or layout components). This is because overlays are mounted outside of the page context by the `UApp` component.
|
||||
|
||||
As such, using `provide()` in pages or parent components isn't supported directly. To pass provided values to overlays, the recommended approach is to use props instead:
|
||||
|
||||
```vue
|
||||
<script setup lang="ts">
|
||||
import { LazyModalExample } from '#components'
|
||||
|
||||
const providedValue = inject('valueProvidedInPage')
|
||||
|
||||
const modal = overlay.create(LazyModalExample, {
|
||||
props: {
|
||||
providedValue,
|
||||
otherData: someValue
|
||||
}
|
||||
})
|
||||
</script>
|
||||
```
|
||||
Reference in New Issue
Block a user