Skip to main content

基于 iframe 的自定义组件 FullscreenIframe

· 3 min read
Kyle
Kyle
CTO of the Ph.D. Creative Station

FullscreenIframe 是一个功能强大且高度自定义的 React 组件，旨在无缝地将外部内容通过 iframe 嵌入到您的 Docusaurus 站点中。它不仅提供了优雅的全屏查看功能，还解决了 iframe 中常见的热键冲突问题（如 ESC 键），并能自动与网站的浅色/深色主题保持视觉同步，提供一致、沉浸式的用户体验。无论您是想嵌入一个在线白板、一个 CodePen 演示、一个 Figma 设计稿，还是任何需要专注模式的 web 应用，FullscreenIframe 都是您的理想选择。

跳转该页面以查看 FullscreenIframe 组件的使用效果。

核心特性​

  • 一键全屏：提供一个悬浮的图标按钮，用户只需单击即可将 iframe 内容扩展至整个屏幕，创造无干扰的浏览环境。
  • ESC 键禁用开关：在全屏模式下，提供一个紧凑的开关控件，允许用户临时禁用 ESC 键退出全屏的功能。这对于需要使用 ESC 键进行操作的内嵌应用（如 Miro、Excalidraw 等白板工具）至关重要。
  • 动态主题同步：组件能够自动侦测 Docusaurus 站点的 light/dark 主题切换，并实时调整自身配色方案，确保其外观与 CustomTOC 等其他自定义组件始终保持视觉统一。
  • 优雅简约的设计：所有控件均采用图标化和毛玻璃（Frosted Glass）效果设计，风格现代、简约且不干扰内容。控件的文字说明通过 tooltip 提供，最大限度地减少了视觉占用。
  • 无缝集成：作为 Docusaurus 的 MDX 组件，集成过程非常简单，只需一行代码即可使用。

使用方法​

在您的 MDX 文件中，首先导入组件，然后在需要的位置使用它。您需要提供两个基本参数：src 和 title。

import FullscreenIframe from '@site/src/components/FullscreenIframe';

<FullscreenIframe 
  src="https://www.example.com" 
  title="示例网站"
/>

实时演示​

下面是一个嵌入了 Excalidraw 在线白板的实时示例。您可以尝试：

  1. 点击右下角的全屏按钮进入全屏。
  2. 在全屏模式下，勾选左下角的开关以禁用 ESC 键，然后您可以在白板中使用 ESC 键取消选择工具，而不会退出全屏。
  3. 再次点击退出全屏图标返回页面。
  4. 切换网站的浅色/深色主题，观察控件配色的变化。

参数配置​

参数类型是否必需描述
srcstring是要在 iframe 中加载的网页内容的 URL。
titlestring是为 iframe 提供一个无障碍的标题，对 SEO 和屏幕阅读器友好。

通过 FullscreenIframe，您可以更自信、更优雅地将第三方内容集成到您的技术文档和博客中，同时为用户提供最佳的交互体验。