# Fullscreen Dialog Portal

> Use when Cook Web payment dialogs, settings dialogs, or other overlays appear during browser fullscreen. Check whether their portal container is outside the fullscreen element.

- Skill: `ai-shifu/fullscreen-dialog-portal` (Agent Skill)
- Install (CLI): `npx get-skill add ai-shifu/fullscreen-dialog-portal`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ai-shifu/fullscreen-dialog-portal/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: ai-shifu (https://skillmd.com/u/ai-shifu)
- Updated: 2026-11-16
- Page: https://skillmd.com/skills/ai-shifu/fullscreen-dialog-portal

---


# 浏览器全屏 Dialog Portal

## 核心规则

- 浏览器 fullscreen 模式下，只有全屏节点及其后代会继续可见；基于 `Dialog` 的弹层若仍 portal 到 `document.body`，就会出现“状态已打开但界面看不到”的现象。
- 优先在通用弹层封装层处理 fullscreen portal 容器，不要在每个业务弹窗里各自复制一套 `document.fullscreenElement` 监听逻辑。
- 若通用封装允许外部传入 `container`，fullscreen 自动兜底必须保留显式覆盖能力，避免影响已有定制挂载点。
- 监听 fullscreen 状态变化时，要兼容进入和退出全屏两个方向，确保弹层在切换后仍能落到当前正确的容器上。
- 若首帧就可能在 fullscreen 内打开弹窗，容器解析不能只依赖异步 effect；需要提供首屏同步兜底，避免弹窗先挂到 `body` 导致闪烁或不可见。
- 若 fullscreen 的宿主节点承载了播放器或阅读器主容器，切换 lesson / chapter 时不要用 loading skeleton 把该宿主整棵卸载掉；应保留原节点并在内部叠加 loading，否则浏览器会因 fullscreen owner 被移除而自动退出全屏。
- 不止 `Dialog`，像追问浮层、评分卡片、引导卡片这类普通业务浮层若定位依赖 `absolute/fixed`，在 fullscreen 下也要确认它们是否仍渲染在 fullscreen 视口树内；若不是，同样需要 portal 到 `slide__viewport` 之类的宿主节点。
- 移动端基于 `src/components/ui/Dialog.tsx` 的基础弹窗默认要保留稳定的视口边距，优先在通用 `DialogContent` 上统一约束宽度，而不是在每个业务弹窗里分别补 `w-[calc(100vw-32px)]`。
- 基础 `Dialog` 的遮罩层级要高于听课 slide 内部 loading / ask / interaction 这类局部浮层；若 slide 局部浮层使用 `z-[91]` 一类层级，通用 Dialog 遮罩和内容应在封装层统一使用更高层级，避免业务弹窗被 slide 区域盖住或糊住。

## 工作流

1. 先确认异常弹层是否基于 `src/components/ui/Dialog.tsx` 这类通用封装，而不是业务侧自己 `createPortal`。
2. 复现时重点观察触发弹层时页面是否已经进入浏览器 fullscreen，而不是仅仅组件内部切换了“全屏样式”。
3. 若是浏览器 fullscreen，优先检查 `DialogPortal` 的 `container` 是否仍为空，导致默认挂到 `body`。
4. 在通用封装层补齐 fullscreen 容器解析与 `fullscreenchange` 监听，并保留外部 `container` 的覆盖入口。
5. 若问题发生在章节切换、重新加载或数据刷新后，再检查 fullscreen owner 在 loading 阶段是否被条件渲染卸载；优先改成保留宿主节点、仅在内部显示 loading overlay。
6. 修改后至少验证一次“进入 slide fullscreen 后直接触发支付弹窗/业务弹窗”或“fullscreen 中切换章节仍保持屏幕状态”的路径，并补一次定向类型检查。

