---
title: 概览
description: 使用统一 API 编排应用中的临时浮层。
order: 1
toc:
  - id: package-role
    title: 包的职责
  - id: supported-overlays
    title: 支持的浮层
  - id: design-boundary
    title: 设计边界
---

## 包的职责 {#package-role}

`@workspace/overlays` 是基于 Base UI handle 和 `@workspace/ui` 的异步浮层编排层。业务代码通过 `openAlert()`、`openModal()` 等原子函数发起交互，不需要分别维护 `open` 状态。

每种能力都使用独立子路径和 Host，例如 `@workspace/overlays/modal` 只包含 Modal 所需实现。`OverlayScope` 按需创建已经使用的 feature channel，不会预先构造所有 Base UI handle。同类请求按顺序显示，不会覆盖仍在等待的 Promise。

## 支持的浮层 {#supported-overlays}

- `alert`：等待用户确认消息。
- `confirm`：返回 `true` 或 `false`。
- `prompt`：返回输入字符串，取消时返回 `null`。
- `modal`：居中的自定义内容浮层。
- `sheet`：从页面边缘进入的面板。
- `drawer`：支持拖动、方向和吸附点的面板。
- `toast`：复用 Base UI toast manager 的通知、更新和 Promise 状态。

## 设计边界 {#design-boundary}

这个包负责 Scope、请求队列、Promise 结算和标准结构，不复制底层 UI primitives。根入口只导出 Scope 能力；具体 UI 从 `/alert`、`/modal`、`/sheet` 等子路径导入，以保留明确的 tree-shaking 边界。