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 创建的，确保相同的叠加层状态在整个应用程序中共享。
为了从叠加层返回一个值，可以 await overlay.open()。要使此功能生效，叠加层组件必须发出 close 事件。有关详细信息，请参阅下面的示例。

API

useOverlay()

useOverlay 组合函数提供了全局管理叠加层的方法。每个创建的叠加层都会返回一个具有自身方法的实例。

create()

create(component: T, options: OverlayOptions): OverlayInstance

创建一个叠加层，并返回一个工厂实例。

参数

component
T required
要渲染的叠加层组件。
options
OverlayOptions
叠加层的配置选项。

open()

open(id: symbol, props?: ComponentProps<T>): OpenedOverlay<T>

通过其 id 打开叠加层。

参数

id
symbol required
叠加层的标识符。
props
ComponentProps<T>
要传递给渲染组件的可选 props 对象。

close()

close(id: symbol, value?: any): void

通过其 id 关闭叠加层。

参数

id
symbol required
叠加层的标识符。
value
any
用于解析叠加层 Promise 的值。

patch()

patch(id: symbol, props: ComponentProps<T>): void

通过其 id 更新叠加层。

参数

id
symbol required
叠加层的标识符。
props
ComponentProps<T> required
用于更新渲染组件 props 的对象。

unmount()

unmount(id: symbol): void

通过其 id 从 DOM 中移除叠加层。

参数

id
symbol required
叠加层的标识符。

isOpen()

isOpen(id: symbol): boolean

使用其 id 检查叠加层是否打开。

参数

id
symbol required
叠加层的标识符。

overlays

overlays: Overlay[]

内存中所有已创建叠加层的列表。

Instance API

open()

open(props?: ComponentProps<T>): Promise<OpenedOverlay<T>>

打开叠加层。

参数

props
ComponentProps<T>
要传递给渲染组件的可选 props 对象。
<script setup lang="ts">
import { LazyModalExample } from '#components'

const overlay = useOverlay()

const modal = overlay.create(LazyModalExample)

function openModal() {
  modal.open({
    title: 'Welcome'
  })
}
</script>

close()

close(value?: any): void

关闭叠加层。

参数

value
any
用于解析叠加层 Promise 的值。

patch()

patch(props: ComponentProps<T>): void

更新叠加层的 props。

参数

props
ComponentProps<T> required
用于更新渲染组件 props 的对象。
<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

  // 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>

defineShortcuts

一个在应用中定义键盘快捷键的组合函数。

useToast

一个在应用中显示 toast 通知（消息提示）的组合函数。