弹层实例

每次调用 openLayer() 后会返回一个 LayerInstance 对象，可用于手动控制弹层。

LayerInstance

interface LayerInstance {
  /** 弹层唯一标识 */
  id: string

  /** 唯一分组标识；未配置 uniqueGroup 时为空 */
  uniqueGroup?: string

  /**
   * Teleport 目标的 CSS 选择器或 `'body'`；
   * 当 teleport 是 HTMLElement / RendererNode 时为空字符串，请改用 teleportKey。
   */
  teleportTarget: string

  /**
   * 归一化 Teleport key，对所有 teleport 类型（CSS 选择器、HTMLElement 等）
   * 都是稳定的字符串，用于内部分组和清理。
   */
  teleportKey: string

  /** 关闭弹层（仅发起关闭请求，能否关闭取决于 beforeClose） */
  close: () => void

  /** 将弹层置顶 */
  bringToTop: () => void

  /** 最大化弹层 */
  maximize: () => void

  /** 最小化弹层到停靠栏 */
  minimize: () => void

  /** 还原弹层尺寸 */
  restore: () => void

  /** 更新打开后的可变配置 */
  update: (options: Partial<Omit<LayerConfig, 'id' | 'uniqueGroup' | 'teleport'>>) => void

  /** 离场完成后 resolve 关闭结果 */
  closed: Promise<LayerCloseResult>
}

Teleport 元数据

teleportTarget 是面向用户的字段：当 teleport 是 CSS 选择器或 body 时它是有意义的字符串；当 teleport 是 HTMLElement / RendererNode 时它为空字符串，因为 DOM 元素无法表示为稳定的字符串。区分 Teleport 分组、追踪实例归属时，请读取稳定的 teleportKey——它对所有 teleport 类型都是稳定字符串。未传入 uniqueGroup 时，uniqueGroup 为 undefined。

方法说明

close()

关闭弹层。触发弹层的离场动画，动画完成后自动销毁弹层实例并清理 DOM。

const instance = openLayer({ title: '弹层' })

// 3 秒后自动关闭
setTimeout(() => {
  instance?.close()
}, 3000)

返回值： void — 该方法不返回任何值。等待关闭完成请使用 instance.closed Promise。

bringToTop()

将弹层置顶。在同一个 Teleport 父容器下的所有弹层中，将当前弹层的 z-index 提升到最高。

instance?.bringToTop()

TIP

点击弹层窗体时会自动触发置顶，通常不需要手动调用此方法。

maximize()

最大化弹层。弹层将充满其所在的容器（body 或自定义 teleport 目标）。

instance?.maximize()

restore()

将弹层从最大化状态还原到默认尺寸和位置；若窗口已最小化，则恢复到最小化前的状态。

instance?.restore()

minimize()

将允许最小化（min: true）的弹层收起到同一 Teleport 容器底部的停靠栏。窗口仍然保持挂载，因此可通过 restore() 或点击停靠项继续操作。

const instance = openLayer({ title: '编辑订单', min: true })

instance?.minimize()

update()

通过标准 Vue 父子 props 更新链路修改已打开 Layer 的可变配置。id、uniqueGroup 和 teleport 用于实例管理，打开后不会被修改。

instance?.update({
  title: '编辑用户（未保存）',
  props: { userId: '42', readonly: false },
  size: { width: '720px', height: '520px' }
})

closed

等待离场动画结束后获得关闭结果，可用于 Promise 风格的确认流程：

const instance = openLayer({ title: '确认操作', closeOnOk: true })
const result = await instance?.closed

if (result?.action === 'ok') {
  // 用户确认
}

action 为 close、ok 或 cancel；reason 会标记 header、shade、escape、ok、cancel 或 programmatic。

使用示例

<script setup lang="ts">
import { ref } from 'vue'
import { useLiteLayer } from 'vue-lite-layer'
import MyContent from './MyContent.vue'

const { openLayer } = useLiteLayer()

// 保存弹层实例引用
const layerInstance = ref<ReturnType<typeof openLayer>>(null)

const handleOpen = () => {
  layerInstance.value = openLayer({
    title: '可控弹层',
    content: MyContent,
    size: { width: '600px', height: '400px' },
  })
}

const handleMaximize = () => {
  layerInstance.value?.maximize()
}

const handleRestore = () => {
  layerInstance.value?.restore()
}

const handleClose = () => {
  layerInstance.value?.close()
  layerInstance.value = null
}
</script>

<template>
  <button @click="handleOpen">打开弹层</button>
  <button @click="handleMaximize">最大化</button>
  <button @click="handleRestore">还原</button>
  <button @click="handleClose">关闭</button>
</template>

唯一分组

通过 uniqueGroup 可以确保同一组只能打开一个弹层：

// 第一次调用：正常打开
const instance1 = openLayer({
  title: '设置',
  content: SettingsPanel,
  uniqueGroup: 'settings',
})

// 第二次调用：返回 null，不会重复打开
const instance2 = openLayer({
  title: '设置',
  content: SettingsPanel,
  uniqueGroup: 'settings',
})

console.log(instance2) // null