59. 嵌入第三方网页 · 玄武屏使用手册

通过 iframe 把玄武屏演示嵌入到你的网站、博客、文档系统、SaaS 平台。本节讲嵌入方式、参数、跨域行为。

基础嵌入

<iframe src="https://x.bahuangqi.com/embed/abcd1234"
        width="100%" height="600"
        frameborder="0" allowfullscreen></iframe>

abcd1234 是演示文稿的分享 ID。

URL 参数

参数	默认	说明
`?p=5`	1	起始页
`&autoplay=1`	0	自动播放（需配合 muted）
`&loop=1`	0	循环播放
`&controls=0`	1	隐藏控制条
`&theme=dark`	auto	主题（light/dark/auto）
`&lang=en`	zh	语言
`&watermark=0`	1	隐藏水印（需商业授权）

例：https://x.bahuangqi.com/embed/abc?p=3&autoplay=1&loop=1&controls=0

嵌入模式

1. 完整嵌入

整份演示嵌入：

<iframe src="https://x.bahuangqi.com/embed/abc"
        width="800" height="450"></iframe>

观众可以正常翻页交互。

2. 单页嵌入

只嵌入某一页：

<iframe src="https://x.bahuangqi.com/embed/abc?p=5&single=1"></iframe>

观众只能在这一页交互，不能翻页。

3. 单元素嵌入

只嵌入某一个 GGB / HTML 元素：

<iframe src="https://x.bahuangqi.com/embed/abc?p=5&element=ggb-001"></iframe>

适合：博客文章嵌入互动动画。

响应式嵌入

iframe 默认不响应式。常见做法：

<div style="position:relative; padding-bottom:56.25%; height:0;">
  <iframe src="https://x.bahuangqi.com/embed/abc"
          style="position:absolute; top:0; left:0; width:100%; height:100%;"
          frameborder="0" allowfullscreen></iframe>
</div>

56.25% 是 16:9 比例（9÷16 = 0.5625）。其他比例：

4:3 → 75%
21:9 → 42.86%
32:9 → 28.13%

跨域行为

默认允许

玄武屏服务器允许嵌入到任何 HTTPS 站点
图片 / GGB / HTML 资源跨域读取已配置 CORS

禁止嵌入

可在分享设置里禁止某些场景：

仅允许特定域名嵌入（白名单）
禁止国外站点嵌入
完全禁止 iframe 嵌入

父子页面通信

通过 postMessage 双向通信：

// 父页面给玄武屏发指令
const xwpFrame = document.querySelector('iframe').contentWindow
xwpFrame.postMessage({ type: 'goToPage', page: 5 }, '*')

// 玄武屏给父页面发事件
window.addEventListener('message', (e) => {
  if (e.data.type === 'xwp:page-changed') {
    console.log('观众翻到第', e.data.page, '页')
  }
})

嵌入到具体平台

Notion

/embed
粘贴玄武屏分享链接

飞书文档

插入 → 内嵌网页
粘贴链接

知乎专栏 / 微信公众号

不支持 iframe。可用：

截图嵌入
二维码引导跳转

Confluence

HTML 宏 → 粘贴 iframe 代码

WordPress / 博客系统

<!-- 在 HTML 模式粘贴 iframe -->

嵌入分析

后台可看到：

哪些站点嵌入了你的演示
总观看次数
平均观看时长
翻页深度

适合：

验证内容传播效果
找到合作站点
分析观众兴趣

安全考虑

CSP 配置

如果你的站点用了 CSP（Content Security Policy）：

Content-Security-Policy:
  frame-src 'self' https://x.bahuangqi.com;

需将玄武屏域名加入白名单。

防点击劫持

玄武屏自动设置 X-Frame-Options: ALLOWFROM 限制：

默认允许任意站点嵌入
可在分享设置里限制为白名单

防爬虫嵌入

不希望演示被爬虫嵌入到聚合站点：

设置"禁止匿名访问"，需登录玄武屏账号才能看
或加密分享，访问需密码

收费嵌入

商业授权场景：

嵌入次数计费（按月）
嵌入站点数量计费
私有化嵌入版本

详见「77. 定制服务流程」。

跨场景应用

场景	嵌入用法
个人博客	嵌入互动动画展示作品
企业官网	产品演示嵌入到产品页
教育平台	课件嵌入到 LMS
SaaS 文档	操作演示嵌入到帮助页
新闻媒体	数据可视化嵌入到报道
政府门户	政策解读演示嵌入到通知

下一节讲协作邀请与权限。