npm package: @kaynewang/lib.iframe-fullscreen
Description: 一个轻量级的 iframe 全屏库，支持 Web API 全屏和 CSS 全屏两种模式。
Author: kayne
Latest version: 0.0.4

# 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

```bash
npm install @kaynewang/lib.iframe-fullscreen
```

```bash
yarn add @kaynewang/lib.iframe-fullscreen
```

```bash
pnpm add @kaynewang/lib.iframe-fullscreen
```

## 🚀 快速开始 Quick Start

### 基础使用 Basic Usage

```typescript
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

```vue
<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

```typescript
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.

```typescript
iframeFullscreen.toggleFullscreen();
```

##### `destroyIframeFullscreen()`

销毁 iframe 实例，清理资源。

Destroy the iframe instance and clean up resources.

```typescript
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 模拟全屏效果，兼容性更好，但可能受页面其他元素影响。

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

### 2. Web API 全屏模式

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

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

### 3. 使用 srcdoc

通过 srcdoc 直接注入 HTML 内容。

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

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

### 4. 自定义全屏元素

指定特定元素进行全屏。

```typescript
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](mailto:w.zengkai@gmail.com)

## 🤝 贡献 Contributing

欢迎提交 Issue 和 Pull Request！

Issues and Pull Requests are welcome!