企业官网建设流程全解析

如何用 Homepage 的 iframe 组件嵌入第三方页面并控制加载行为

【免费下载链接】homepageA highly customizable homepage (or startpage / application dashboard) with Docker and service API integrations.项目地址: https://gitcode.com/GitHub_Trending/ho/homepage

Homepage 是一个可自定义的首页 / 应用仪表盘。当你希望把某个第三方 Web 页面直接嵌进首页的服务卡片里、而不是只放一个跳转链接时，可以使用type: iframe的 widget。本文基于 iframe 文档 和 Service 配置文档，给出最小可用配置、各加载控制项的默认值与行为，以及结果验证方式。

先说一个文档明确警告的边界：iframe widget 发出的请求不会经过 Homepage 代理，因为请求是由浏览器直接发起的。也就是说，能访问嵌入页面的前提是浏览器网络能到达src地址。

准备条件：确认 iframe 属于哪类 widget

根据 Widgets 文档，Homepage 有两类 widget：

• Service widgets：显示服务状态，定义在services.yaml中，挂在 service 条目下；
• Info widgets：显示头部信息（系统、环境等），定义在widgets.yaml中。

iframe widget 属于 service widget 一侧：它作为一个 widget 条目挂到services.yaml的某个 service 下。iframe 的渲染内容是标准 HTML<iframe>，其余 HTML 属性 Homepage 文档指向 MDN 的 iframe 文档作为参考。

写入最小可用配置

services.yaml的结构是：顶层数组为 Group，每个 Group 下是 service 条目数组，每个 service 通过widget:（单个）或widgets:（多个）挂接 widget。iframe 的最小 widget 块如下（src为要嵌入的页面地址，name同时作为 iframe 的name与title属性）：

- Group A: - My Embedded Page: href: http://example.com widget: type: iframe name: myIframe src: http://example.com

其中href、icon等 service 属性均可选，写法见 Service 配置文档；决定嵌入行为的是widget:块里的type: iframe、name和src。

控制加载与显示行为

iframe 文档 给出的完整示例展示了全部可选配置项：

widget: type: iframe name: myIframe src: http://example.com classes: h-60 sm:h-60 md:h-60 lg:h-60 xl:h-60 2xl:h-72 # optional, use tailwind height classes referrerPolicy: same-origin # optional, no default allowPolicy: autoplay; fullscreen; gamepad # optional, no default allowFullscreen: false # optional, default: true loadingStrategy: eager # optional, default: eager allowScrolling: no # optional, default: yes refreshInterval: 2000 # optional, no default

各选项的作用和默认值如下：

两个行为细节来自 组件实现，配置时需要知道：

• refreshInterval最小粒度为 1 秒。实现中若配置值小于 1000，会被强制按 1000 处理；刷新通过重建 iframe（key变化触发重挂载）完成，即配置后页面会周期性重新加载，而不是局部刷新。
• allowScrolling: no的具体效果是同时设置pointerEvents: none和overflow: hidden，嵌入页面既不可滚动也不可交互。

另外，iframe widget 的 服务端定义 是一个空对象，说明它不通过 Homepage 的 API 拉取数据，页面完全由浏览器按src加载——这与开头"不代理"的警告一致。

可选分支：一个 service 挂多个 widget

如果一个服务卡片内需要嵌入多个页面（或 iframe 与其他数据型 widget 混排），用复数形式widgets:列表即可，例如：

- Group A: - My Embedded Pages: href: http://example.com widgets: - type: iframe name: pageA src: http://example.com/a - type: iframe name: pageB src: http://example.com/b classes: h-40 sm:h-40 md:h-40 lg:h-40 xl:h-40 2xl:h-40

多 widget 的通用写法（如同时挂emby、uptimekuma等）见 Service 配置文档的 Multiple Widgets 一节。文档同时注明：多 widget 目前不支持通过 Kubernetes ingress annotations 定义。

验证结果

项目中的 组件测试 给出了渲染后 iframe 节点应携带的属性，可作为核对依据：

• src等于配置的src；
• title和name等于配置的name；
• scrolling等于配置的allowScrolling（如no）；
• className中包含配置的classes。

在实际页面中，保存services.yaml后打开 Homepage 首页，对应服务卡片区域应显示嵌入的第三方页面；用浏览器开发者工具检查该卡片内的<iframe>节点，确认上述属性与配置一致，即说明配置生效。

限制与注意事项

• iframe 请求由浏览器直接发出，不经过 Homepage 代理；Homepage 服务端能否访问该页面与嵌入是否成功无关。
• refreshInterval配置小于 1000 毫秒时按 1000 毫秒执行。
• 其余 iframe HTML 属性（如referrerPolicy、allow的取值范围）Homepage 文档未逐一展开，以 MDN 的 iframe 文档为准。

【免费下载链接】homepageA highly customizable homepage (or startpage / application dashboard) with Docker and service API integrations.项目地址: https://gitcode.com/GitHub_Trending/ho/homepage