lib.iframe-fullscreen

一个轻量级的 iframe 全屏库，支持 Web API 全屏和 CSS 全屏两种模式。

A lightweight iframe fullscreen library that supports both Web API fullscreen and CSS fullscreen modes.

✨ 特性 Features

• 🚀 轻量级，无依赖（Vue 示例仅用于演示）
• 🎯 支持两种全屏模式：Web API 全屏和 CSS 全屏
• 📦 TypeScript 支持
• 🔧 简单易用的 API
• 🎨 自定义全屏元素
• 🌐 支持 src 和 srcdoc 两种方式

📦 安装 Installation

npm install @kaynewang/lib.iframe-fullscreen

yarn add @kaynewang/lib.iframe-fullscreen

pnpm add @kaynewang/lib.iframe-fullscreen

🚀 快速开始 Quick Start

基础使用 Basic Usage

import { IframeFullscreen } from "@kaynewang/lib.iframe-fullscreen";

const iframeFullscreen = new IframeFullscreen({
  rootEle: document.getElementById("iframe-container")!,
  url: "https://example.com",
});

// 切换全屏
iframeFullscreen.toggleFullscreen();

Vue 3 示例 Vue 3 Example

<template>
  <div>
    <div ref="containerRef" style="width: 100%; height: 500px;">
      <button @click="handleToggleFullscreen">Toggle Fullscreen</button>
    </div>
  </div>
</template>

<script setup lang="ts">
import { onBeforeUnmount, onMounted, ref } from "vue";
import { IframeFullscreen } from "@kaynewang/lib.iframe-fullscreen";

const containerRef = ref<HTMLElement | null>(null);
const iframeFullscreen = ref<IframeFullscreen | null>(null);

const handleToggleFullscreen = () => {
  iframeFullscreen.value?.toggleFullscreen();
};

onMounted(() => {
  if (containerRef.value) {
    iframeFullscreen.value = new IframeFullscreen({
      rootEle: containerRef.value,
      url: "https://en.wikipedia.org",
      allowWebApiFullscreen: true,
    });
  }
});

onBeforeUnmount(() => {
  iframeFullscreen.value?.destroyIframeFullscreen();
});
</script>

📖 API 文档 API Documentation

IframeFullscreen

Constructor Options

interface InitIframeFullscreenOptions {
  rootEle: HTMLElement; // iframe 容器元素 (required)
  url: string; // iframe src 地址 (required)
  docUrl?: string; // iframe srcdoc 内容 (optional, 优先级高于 url)
  allowWebApiFullscreen?: boolean; // 是否使用 Web API 全屏 (optional, default: false)
  fullscreenEle?: HTMLElement; // 自定义全屏元素 (optional, default: rootEle)
}

Methods

toggleFullscreen()

切换全屏状态。

Toggle fullscreen state.

iframeFullscreen.toggleFullscreen();

destroyIframeFullscreen()

销毁 iframe 实例，清理资源。

Destroy the iframe instance and clean up resources.

iframeFullscreen.destroyIframeFullscreen();

Properties

• rootEle: HTMLElement | null - iframe 容器元素
• fullscreenEle: HTMLElement | null - 全屏元素
• iframeElement: HTMLIFrameElement | null - iframe 元素
• isFullscreen: boolean - 当前是否全屏
• allowWebApiFullscreen: boolean - 是否启用 Web API 全屏

🎯 使用场景 Use Cases

1. CSS 全屏模式 (默认)

使用 CSS 模拟全屏效果，兼容性更好，但可能受页面其他元素影响。

const iframeFullscreen = new IframeFullscreen({
  rootEle: document.getElementById("container")!,
  url: "https://example.com",
  allowWebApiFullscreen: false, // 或不设置，默认为 false
});

2. Web API 全屏模式

使用原生 Fullscreen API，真正的全屏体验，但需要浏览器支持。

const iframeFullscreen = new IframeFullscreen({
  rootEle: document.getElementById("container")!,
  url: "https://example.com",
  allowWebApiFullscreen: true,
});

3. 使用 srcdoc

通过 srcdoc 直接注入 HTML 内容。

const htmlContent = "<h1>Hello World</h1>";

const iframeFullscreen = new IframeFullscreen({
  rootEle: document.getElementById("container")!,
  url: "", // srcdoc 优先级更高
  docUrl: htmlContent,
});

4. 自定义全屏元素

指定特定元素进行全屏。

const iframeFullscreen = new IframeFullscreen({
  rootEle: document.getElementById("iframe-container")!,
  url: "https://example.com",
  fullscreenEle: document.getElementById("fullscreen-wrapper")!,
  allowWebApiFullscreen: true,
});

⚠️ 注意事项 Notes

1. 浏览器兼容性：Web API 全屏模式需要浏览器支持 Fullscreen API
2. 用户交互：某些浏览器要求全屏操作必须由用户交互触发（如点击事件）
3. HTTPS：部分浏览器要求在 HTTPS 环境下才能使用全屏功能
4. 跨域限制：iframe 内容可能受到跨域策略限制
5. 资源清理：组件卸载时务必调用 destroyIframeFullscreen() 方法清理资源

📝 License

MIT © kayne

🤝 贡献 Contributing

欢迎提交 Issue 和 Pull Request！

Issues and Pull Requests are welcome!