useOverlay
一个用于编程式控制叠加层的可组合函数。
用法
使用自动导入的 useOverlay
可组合函数来编程式控制 Modal 和 Slideover 组件。
<script setup lang="ts">
import { LazyModalExample } from '#components'
const overlay = useOverlay()
const modal = overlay.create(LazyModalExample)
async function openModal() {
modal.open()
}
</script>
useOverlay
可组合函数是使用createSharedComposable
创建的,确保相同的叠加层状态在整个应用程序中共享。
为了从叠加层返回一个值,可以等待
overlay.open().instance.result
。但是,为了使其正常工作,叠加层组件必须发出一个 close
事件。详情请参阅下面的示例。API
create(component: T, options: OverlayOptions): OverlayInstance
创建一个叠加层,并返回一个工厂实例。
- 参数
component
:叠加层组件。选项
:defaultOpen?: boolean
:创建后立即打开叠加层。默认为false
。props?: ComponentProps
:一个可选的 prop 对象,用于传递给渲染的组件。destroyOnClose?: boolean
:关闭时从内存中移除叠加层。默认为false
。
open(id: symbol, props?: ComponentProps<T>): OpenedOverlay<T>
通过 id
打开一个叠加层。
- 参数
id
:叠加层的标识符。props
:一个可选的 prop 对象,用于传递给渲染的组件。
close(id: symbol, value?: any): void
通过 id
关闭一个叠加层。
- 参数
id
:叠加层的标识符。value
:用于解决叠加层 Promise 的值。
patch(id: symbol, props: ComponentProps<T>): void
通过 id
更新一个叠加层。
- 参数
id
:叠加层的标识符。props
:一个 prop 对象,用于更新渲染的组件。
unmount(id: symbol): void
通过 id
从 DOM 中移除一个叠加层。
- 参数
id
:叠加层的标识符。
isOpen(id: symbol): boolean
使用 id
检查叠加层是否打开。
- 参数
id
:叠加层的标识符。
overlays: Overlay[]
所有已创建叠加层的内存列表。
实例 API
open(props?: ComponentProps<T>): Promise<OpenedOverlay<T>>
打开叠加层。
- 参数
props
:一个可选的 prop 对象,用于传递给渲染的组件。
<script setup lang="ts">
import { LazyModalExample } from '#components'
const overlay = useOverlay()
const modal = overlay.create(LazyModalExample)
function openModal() {
modal.open({
title: 'Welcome'
})
}
</script>
close(value?: any): void
关闭叠加层。
- 参数
value
:用于解决叠加层 Promise 的值。
patch(props: ComponentProps<T>)
更新叠加层的 props。
- 参数
props
:一个 prop 对象,用于更新渲染的组件。
<script setup lang="ts">
import { LazyModalExample } from '#components'
const overlay = useOverlay()
const modal = overlay.create(LazyModalExample, {
title: 'Welcome'
})
function openModal() {
modal.open()
}
function updateModalTitle() {
modal.patch({ title: 'Updated Title' })
}
</script>
示例
这是一个使用 useOverlay
可组合函数的完整示例
<script setup lang="ts">
import { ModalA, ModalB, SlideoverA } from '#components'
const overlay = useOverlay()
// Create with default props
const modalA = overlay.create(ModalA, { title: 'Welcome' })
const modalB = overlay.create(ModalB)
const slideoverA = overlay.create(SlideoverA)
const openModalA = () => {
// Open modalA, but override the title prop
modalA.open({ title: 'Hello' })
}
const openModalB = async () => {
// Open modalB, and wait for its result
const modalBInstance = modalB.open()
const input = await modalBInstance.result
// Pass the result from modalB to the slideover, and open it
slideoverA.open({ input })
}
</script>
<template>
<button @click="openModalA">Open Modal</button>
</template>
在此示例中,我们使用 useOverlay
可组合函数来控制多个模态框和侧滑框。
注意事项
Provide / Inject
当编程式打开叠加层(例如模态框、侧滑框等)时,叠加层组件只能访问包含 UApp
的组件(通常是 app.vue
或布局组件)中注入的值。这是因为叠加层是由 UApp
组件挂载在页面上下文之外的。
因此,在页面或父组件中直接使用 provide()
不受支持。要将提供的值传递给叠加层,推荐的方法是改用 props。
<script setup lang="ts">
import { LazyModalExample } from '#components'
const providedValue = inject('valueProvidedInPage')
const modal = overlay.create(LazyModalExample, {
props: {
providedValue,
otherData: someValue
}
})
</script>