Vue 全屏模式下弹窗显示解决方案

Vue 全屏模式下弹窗显示解决方案

问题背景

在 Web 应用中，当某个元素进入全屏模式时，普通的弹窗、遮罩层或对话框组件会因为层叠上下文（Stacking Context）的限制而无法正常显示。这是因为：

1. 全屏元素创建新的层叠上下文：全屏元素会成为一个独立的渲染层
2. z-index 失效：非全屏元素的 z-index 无法穿透到全屏层
3. Teleport 目标错误：Vue 的 Teleport 组件默认挂载到 body，但全屏时需要挂载到全屏元素内部

核心解决方案

1. 技术原理

通过动态切换 Teleport 目标和强制样式覆盖来确保弹窗在任何状态下都能正常显示。

2. 实现步骤

步骤一：全屏状态检测与管理

import { ref, watch, onMounted, onUnmounted, nextTick } from 'vue';

// 全屏状态管理
const isFullscreen = ref(false);
const fullscreenElement = ref(null);
const teleportTarget = ref('body');

// 全屏状态变化处理
const handleFullscreenChange = () => {
    isFullscreen.value = !!document.fullscreenElement;
    fullscreenElement.value = document.fullscreenElement;
    updateTeleportTarget();
    
    console.log('全屏状态变化:', {
        isFullscreen: isFullscreen.value,
        fullscreenElement: fullscreenElement.value?.tagName,
        teleportTarget: teleportTarget.value
    });
};

// 生命周期事件监听
onMounted(() => {
    // 初始检测
    isFullscreen.value = !!document.fullscreenElement;
    fullscreenElement.value = document.fullscreenElement;
    updateTeleportTarget();

    // 监听各种浏览器的全屏事件
    document.addEventListener('fullscreenchange', handleFullscreenChange);
    document.addEventListener('webkitfullscreenchange', handleFullscreenChange);
    document.addEventListener('mozfullscreenchange', handleFullscreenChange);
    document.addEventListener('MSFullscreenChange', handleFullscreenChange);
});

onUnmounted(() => {
    // 清理事件监听器
    document.removeEventListener('fullscreenchange', handleFullscreenChange);
    document.removeEventListener('webkitfullscreenchange', handleFullscreenChange);
    document.removeEventListener('mozfullscreenchange', handleFullscreenChange);
    document.removeEventListener('MSFullscreenChange', handleFullscreenChange);
});

步骤二：动态 Teleport 目标切换

// 更新 Teleport 目标
const updateTeleportTarget = () => {
    if (isFullscreen.value && fullscreenElement.value) {
        // 全屏状态：Teleport 到全屏元素内部
        if (!fullscreenElement.value.id) {
            fullscreenElement.value.id = `fullscreen-container-${Date.now()}`;
        }
        teleportTarget.value = `#${fullscreenElement.value.id}`;
    } else {
        // 非全屏状态：Teleport 到 body
        teleportTarget.value = 'body';
    }
};

// 监听弹窗显示状态变化
watch(() => props.visible, (newVisible) => {
    if (newVisible) {
        nextTick(() => {
            updateTeleportTarget();
            if (isFullscreen.value) {
                forceRerender();
            }
        });
    }
}, { immediate: true });

步骤三：模板结构

<template>
    <Teleport :to="teleportTarget">
        <Transition
            enter-active-class="transition-all duration-300 ease-out"
            enter-from-class="opacity-0"
            enter-to-class="opacity-100"
            leave-active-class="transition-all duration-200 ease-in"
            leave-from-class="opacity-100"
            leave-to-class="opacity-0"
        >
            <div
                v-if="visible"
                class="modal-container"
                :class="{ 'modal-fullscreen': isFullscreen }"
                role="dialog"
                aria-modal="true"
                ref="modalRef"
            >
                <div class="modal-content" @click.stop>
                    <!-- 弹窗内容 -->
                </div>
            </div>
        </Transition>
    </Teleport>
</template>

步骤四：关键样式

/* 基础容器样式 */
.modal-container {
    position: fixed;
    top: 0;
    left: 0;
    right: 0;
    bottom: 0;
    width: 100vw;
    height: 100vh;
    background: rgba(0, 0, 0, 0.5);
    backdrop-filter: blur(8px);
    display: flex;
    align-items: center;
    justify-content: center;
    padding: 1rem;
    z-index: 9999;
}

/* 全屏状态特殊样式 - 关键！ */
.modal-fullscreen {
    position: fixed !important;
    top: 0 !important;
    left: 0 !important;
    right: 0 !important;
    bottom: 0 !important;
    width: 100% !important;
    height: 100% !important;
    z-index: 2147483647 !important; /* 使用最高层级 */
    background: rgba(0, 0, 0, 0.5) !important;
    backdrop-filter: blur(8px) !important;
}

/* 强制显示 - 防止被隐藏 */
.modal-container {
    visibility: visible !important;
    opacity: 1 !important;
    pointer-events: auto !important;
    display: flex !important;
}

/* 针对全屏容器的样式重写 */
*:fullscreen .modal-container,
*:-webkit-full-screen .modal-container,
*:-moz-full-screen .modal-container {
    position: absolute !important;
    z-index: 999999 !important;
    background: rgba(0, 0, 0, 0.5) !important;
    backdrop-filter: blur(8px) !important;
}

/* 弹窗内容 */
.modal-content {
    background: white;
    border-radius: 1rem;
    box-shadow: 0 25px 50px -12px rgba(0, 0, 0, 0.25);
    width: 100%;
    max-width: 80rem;
    height: auto;
    min-height: 500px;
    position: relative;
    z-index: 10;
    overflow: hidden;
}

/* 全屏模式下的内容调整 */
.modal-fullscreen .modal-content {
    max-width: 90vw;
    max-height: 90vh;
}

/* 响应式处理 */
@media (max-width: 768px) {
    .modal-content {
        max-width: 95%;
        margin: 0.5rem;
    }
    
    .modal-fullscreen .modal-content {
        max-width: 95vw;
        max-height: 85vh;
    }
}

/* 确保在任何情况下都不会被隐藏 */
.modal-container[style*="display: none"] {
    display: flex !important;
}

.modal-container[style*="visibility: hidden"] {
    visibility: visible !important;
}

.modal-container[style*="opacity: 0"] {
    opacity: 1 !important;
}

步骤五：备用强制渲染方案

// 强制重新渲染弹窗（备用方案）
const forceRerender = () => {
    if (!props.visible || !isFullscreen.value) return;

    nextTick(() => {
        const modal = modalRef.value;
        if (modal && fullscreenElement.value) {
            // 确保弹窗在全屏元素中可见
            modal.style.position = 'fixed';
            modal.style.top = '0';
            modal.style.left = '0';
            modal.style.width = '100%';
            modal.style.height = '100%';
            modal.style.zIndex = '2147483647';
        }
    });
};

完整代码模板

<template>
    <Teleport :to="teleportTarget">
        <Transition
            enter-active-class="transition-all duration-300 ease-out"
            enter-from-class="opacity-0"
            enter-to-class="opacity-100"
            leave-active-class="transition-all duration-200 ease-in"
            leave-from-class="opacity-100"
            leave-to-class="opacity-0"
        >
            <div
                v-if="visible"
                class="fullscreen-modal-container"
                :class="{ 'fullscreen-modal-fullscreen': isFullscreen }"
                role="dialog"
                aria-modal="true"
                ref="modalRef"
            >
                <div class="fullscreen-modal-content" @click.stop>
                    <!-- 你的弹窗内容 -->
                    <slot />
                </div>
            </div>
        </Transition>
    </Teleport>
</template>

<script setup>
import { ref, watch, onMounted, onUnmounted, nextTick } from 'vue';

const props = defineProps({
    visible: {
        type: Boolean,
        default: false
    }
});

const emit = defineEmits(['update:visible']);

// 组件引用
const modalRef = ref(null);

// 全屏状态管理
const isFullscreen = ref(false);
const fullscreenElement = ref(null);
const teleportTarget = ref('body');

// 更新Teleport目标
const updateTeleportTarget = () => {
    if (isFullscreen.value && fullscreenElement.value) {
        if (!fullscreenElement.value.id) {
            fullscreenElement.value.id = `fullscreen-container-${Date.now()}`;
        }
        teleportTarget.value = `#${fullscreenElement.value.id}`;
    } else {
        teleportTarget.value = 'body';
    }
};

// 全屏状态变化处理
const handleFullscreenChange = () => {
    isFullscreen.value = !!document.fullscreenElement;
    fullscreenElement.value = document.fullscreenElement;
    updateTeleportTarget();
};

// 强制重新渲染
const forceRerender = () => {
    if (!props.visible || !isFullscreen.value) return;
    nextTick(() => {
        const modal = modalRef.value;
        if (modal && fullscreenElement.value) {
            modal.style.position = 'fixed';
            modal.style.top = '0';
            modal.style.left = '0';
            modal.style.width = '100%';
            modal.style.height = '100%';
            modal.style.zIndex = '2147483647';
        }
    });
};

// 监听弹窗显示状态变化
watch(() => props.visible, (newVisible) => {
    if (newVisible) {
        nextTick(() => {
            updateTeleportTarget();
            if (isFullscreen.value) {
                forceRerender();
            }
        });
    }
}, { immediate: true });

// 监听全屏状态变化
watch(isFullscreen, () => {
    if (props.visible) {
        nextTick(() => {
            forceRerender();
        });
    }
});

// 生命周期钩子
onMounted(() => {
    isFullscreen.value = !!document.fullscreenElement;
    fullscreenElement.value = document.fullscreenElement;
    updateTeleportTarget();

    document.addEventListener('fullscreenchange', handleFullscreenChange);
    document.addEventListener('webkitfullscreenchange', handleFullscreenChange);
    document.addEventListener('mozfullscreenchange', handleFullscreenChange);
    document.addEventListener('MSFullscreenChange', handleFullscreenChange);
});

onUnmounted(() => {
    document.removeEventListener('fullscreenchange', handleFullscreenChange);
    document.removeEventListener('webkitfullscreenchange', handleFullscreenChange);
    document.removeEventListener('mozfullscreenchange', handleFullscreenChange);
    document.removeEventListener('MSFullscreenChange', handleFullscreenChange);
});
</script>

<style scoped>
.fullscreen-modal-container {
    position: fixed;
    top: 0;
    left: 0;
    right: 0;
    bottom: 0;
    width: 100vw;
    height: 100vh;
    background: rgba(0, 0, 0, 0.5);
    backdrop-filter: blur(8px);
    display: flex;
    align-items: center;
    justify-content: center;
    padding: 1rem;
    z-index: 9999;
}

.fullscreen-modal-fullscreen {
    position: fixed !important;
    top: 0 !important;
    left: 0 !important;
    right: 0 !important;
    bottom: 0 !important;
    width: 100% !important;
    height: 100% !important;
    z-index: 2147483647 !important;
    background: rgba(0, 0, 0, 0.5) !important;
    backdrop-filter: blur(8px) !important;
}

.fullscreen-modal-content {
    background: white;
    border-radius: 1rem;
    box-shadow: 0 25px 50px -12px rgba(0, 0, 0, 0.25);
    width: 100%;
    max-width: 80rem;
    height: auto;
    min-height: 500px;
    position: relative;
    z-index: 10;
    overflow: hidden;
}

.fullscreen-modal-fullscreen .fullscreen-modal-content {
    max-width: 90vw;
    max-height: 90vh;
}

.fullscreen-modal-container {
    visibility: visible !important;
    opacity: 1 !important;
    pointer-events: auto !important;
    display: flex !important;
}

*:fullscreen .fullscreen-modal-container,
*:-webkit-full-screen .fullscreen-modal-container,
*:-moz-full-screen .fullscreen-modal-container {
    position: absolute !important;
    z-index: 999999 !important;
    background: rgba(0, 0, 0, 0.5) !important;
    backdrop-filter: blur(8px) !important;
}

@media (max-width: 768px) {
    .fullscreen-modal-content {
        max-width: 95%;
        margin: 0.5rem;
    }
    
    .fullscreen-modal-fullscreen .fullscreen-modal-content {
        max-width: 95vw;
        max-height: 85vh;
    }
}
</style>

关键要点总结

✅ 必须要做的

1. 监听多种全屏事件：兼容不同浏览器
2. 动态切换 Teleport 目标：全屏时挂载到全屏元素
3. 使用最高 z-index：2147483647
4. 强制样式覆盖：使用 !important
5. 添加备用渲染方案：确保万无一失

❌ 常见错误

1. 只监听标准全屏事件：忽略浏览器兼容性
2. 固定 Teleport 到 body：全屏时无法显示
3. z-index 不够高：被全屏元素覆盖
4. 忘记强制样式：可能被其他样式干扰
5. 没有响应式处理：移动设备显示异常

🔧 调试技巧

1. 添加调试信息：

<!-- 开发时启用 -->
<div class="debug-info">
    <div>全屏状态: {{ isFullscreen ? '是' : '否' }}</div>
    <div>Teleport目标: {{ teleportTarget }}</div>
    <div>全屏元素: {{ fullscreenElement?.tagName || '无' }}</div>
</div>

1. 控制台日志：监控状态变化
2. 检查元素位置：开发者工具查看层级
3. 测试多种场景：不同设备、浏览器

适用场景

• ✅ 弹窗对话框
• ✅ 遮罩层
• ✅ 通知组件
• ✅ 加载状态
• ✅ 确认框
• ✅ 侧边栏
• ✅ 任何需要在全屏模式下显示的浮层组件

浏览器兼容性

浏览器	支持程度	注意事项
Chrome	✅ 完全支持	推荐
Firefox	✅ 完全支持	推荐
Safari	✅ 完全支持	需要 webkit 前缀
Edge	✅ 完全支持	现代版本
IE11	⚠️ 部分支持	需要 MS 前缀

记住：这个解决方案的核心是动态适应全屏状态，通过 Teleport 和强制样式确保弹窗始终可见！