Portal 传送容器

在保持首次渲染安全的前提下,把内容移动到显式 DOM 容器。

Beta

示例

直接操作示例,查看组件在具体任务中的状态与反馈。

首次渲染保持内联,挂载后只移动到本地显式容器;真实 Chromium hydration 证据仍待补齐。
声明位置

Portal 内容在这里声明,容器通过函数延迟解析,避免读取尚未挂载的 ref。

已传送到显式本地目标
显式 Portal 容器
本地目标区域
未指定容器时,挂载后的内容由组件传送到默认文档目标。
声明区域

下面的状态内容在这里声明。

已渲染到默认 Portal 目标
inline 和 disabled 都保留当前 DOM 位置,便于需要局部层叠上下文的场景。
显式内联
内容保持内联
禁用传送
Portal 暂时禁用

使用建议

优先使用显式容器

通过 container 或 Provider portal 配置指定目标,便于控制层叠上下文、测试边界和多 document 环境。

接受首次渲染保持内联

Portal 在服务端和首次 hydration 前保留原位置,挂载后才解析目标,避免服务端直接访问 document。

焦点合同由上层组件负责

Portal 只移动 DOM,不管理焦点捕获、恢复、Escape、背景屏蔽或 aria-modal;浮层需要组合专用交互组件。

引入方式

从已验证的公开子路径导入组件;全局样式接入方式见安装指南。

import { BasePortal } from '@inf-monkeys-tech/monkeys-design/components/base';

当前限制

  • Portal 目标必须是可用 Element;目标缺失时内容保持内联,组件不创建容器、不管理 z-index,也不提供浮层交互语义。
  • T17 尚缺真实 Chromium hydration、focus、axe、visual 与 packed React 18/19 证据;挂载后的 DOM 移动、焦点连续性和目标容器视觉尚未完成浏览器闭环。
  • Actual browser mount/hydration movement and deterministic portal visual evidence are pending T17/T23.
export interface BasePortalProps {
  children?: ReactNode;
  container?: BasePortalContainer;
  disabled?: boolean;
  inline?: boolean;
}
属性说明类型默认值
children在 BasePortal 内渲染的子内容;支持渲染函数时以对应的 Props 类型为准。ReactNode
containerPortal 内容挂载到的目标容器。BasePortalContainer
disabled是否禁用该组件及其可交互行为。boolean
inlinePortal 内容是否在当前位置直接渲染而不挂载到外部容器。boolean