重要提示:此文档不适用于您当前选择的格式 ads!
amp-iframe
描述
显示 iframe。
必需的脚本
<script async custom-element="amp-iframe" src="https://cdn.ampproject.org/v0/amp-iframe-0.1.js"></script>
用法
显示 AMP 有效的 iframe。amp-iframe
与普通的 iframe 有几个重要的不同之处,旨在使其更安全,并避免 AMP 文件被单个 iframe 支配
amp-iframe
不得出现在文档的顶部附近(使用placeholder
的 iframe 除外,如下文 所述)。iframe 必须距离顶部 600 像素,或者滚动到顶部时不在视口的头 75% 内,以较小者为准。- 默认情况下,
amp-iframe
是沙盒化的(请参阅 详细信息)。 amp-iframe
只能通过 HTTPS、来自数据 URI 或通过srcdoc
属性请求资源。- 除非它们不允许在
sandbox
属性中使用allow-same-origin
,否则amp-iframe
不得与容器同源。有关 iframe 允许的来源的更多详细信息,请参阅 “Iframe 来源策略” 文档。
<amp-iframe width="200" height="100" sandbox="allow-scripts allow-same-origin" layout="responsive" frameborder="0" src="https://www.google.com/maps/embed/v1/place?key=AIzaSyAyAS599A2GGPKTmtNr9CptD61LE4gN6oQ&q=iceland" > </amp-iframe>
使用现有的 AMP 组件代替 amp-iframe
如果无法通过 AMP 中的其他方式实现所需的用户体验,即该用例还没有现有的 AMP 组件,则应将 amp-iframe
组件视为后备方案。这是因为使用针对特定用例量身定制的 AMP 组件有很多好处,例如
- 更好的资源管理和性能
- 在某些情况下,自定义组件可以提供内置的占位符图像。这意味着在视频加载之前获取正确的视频缩略图,并减少手动添加占位符的编码工作。
- 内置大小调整。这意味着具有不可预测大小的 iframe 内容可以更频繁地向用户显示,就好像它是页面原生的,而不是在可滚动框架中
- 可以内置其他附加功能(例如,视频播放器的自动播放)
amp-iframe
用于广告的用法
不得将 amp-iframe
用于显示广告的主要目的。可以将 amp-iframe
用于显示视频,其中部分视频是广告。此 AMP 政策可能会通过不渲染相应的 iframe 来强制执行。
广告用例应使用 amp-ad
代替。
此政策的原因是
amp-iframe
强制执行沙盒,沙盒也应用于子 iframe。这意味着着陆页可能会被破坏,即使广告本身看起来有效。amp-iframe
没有提供任何机制来将配置传递给 iframe。amp-iframe
没有完全由 iframe 控制的大小调整机制。amp-iframe
可能无法获得可见性信息。
带有占位符的 Iframe
当 amp-iframe
具有 placeholder
元素时,如以下示例所示,可以在文档顶部显示 amp-iframe
。
amp-iframe
必须包含带有placeholder
属性的元素(例如amp-img
元素),在 iframe 准备好显示之前,它将呈现为占位符。- 可以通过侦听 iframe 的
onload
或embed-ready
postMessage
来知道 iframe 的准备情况,postMessage
将由 iframe 文档发送,以先到者为准。
以下示例显示了带有占位符的 iframe
<amp-iframe width="300" height="300" layout="responsive" sandbox="allow-scripts allow-same-origin" src="https://foo.com/iframe" > <amp-img layout="fill" src="https://foo.com/foo.png" placeholder></amp-img> </amp-iframe>
以下示例显示了带有 embed-ready 请求的 iframe
window.parent.postMessage( { sentinel: 'amp', type: 'embed-ready', }, '*' );
Iframe 大小调整
与任何其他 AMP 元素一样,amp-iframe
必须定义静态布局。但是,可以在运行时调整 amp-iframe
的大小。为此
- 必须使用
resizable
属性定义amp-iframe
。 amp-iframe
必须具有overflow
子元素。此元素通常可以是div
。但是,如果amp-iframe
是p
元素的子元素,则建议使用span
或button
(以消除p
元素的 短语内容 导致的问题)。amp-iframe
必须设置allow-same-origin
沙盒属性。- iframe 文档必须将
embed-size
请求作为窗口消息发送。 - 如果请求的高度小于某个阈值 (100px),则
embed-size
请求将被拒绝。
请注意,resizable
会将 scrolling
的值覆盖为 no
。
以下示例显示了带有 overflow
元素的 amp-iframe
<amp-iframe width="300" height="300" layout="responsive" sandbox="allow-scripts allow-same-origin" resizable src="https://foo.com/iframe" > <div overflow tabindex="0" role="button" aria-label="Read more"> Read more! </div> </amp-iframe>
以下示例显示了 iframe 大小调整请求
window.parent.postMessage( { sentinel: 'amp', type: 'embed-size', height: document.body.scrollHeight, }, '*' );
收到此消息后,AMP 运行时会尽快尝试满足请求,但它会考虑读者当前正在阅读的位置、滚动是否正在进行以及任何其他 UX 或性能因素。如果运行时无法满足大小调整请求,则 amp-iframe
将显示一个 overflow
元素。单击 overflow
元素将立即调整 amp-iframe
的大小,因为它是由用户操作触发的。
以下是一些影响大小调整执行速度的因素
- 调整大小是否由用户操作触发。
- 是否为当前活动的 iframe 请求调整大小。
- 是否为视口下方或视口上方的 iframe 请求调整大小。
Iframe 可见性
Iframe 可以将其 send-intersections
消息发送给其父级,以开始接收 iframe 与父级视口交叉的 IntersectionObserver
样式 更改记录。
在以下示例中,我们假设该脚本位于创建的 iframe 中,其中 window.parent
是顶部窗口。如果脚本位于嵌套的 iframe 中,请将 window.parent
更改为顶部 AMP 窗口。
以下示例显示了 iframe send-intersections
请求
window.parent.postMessage( { sentinel: 'amp', type: 'send-intersections', }, '*' );
iframe 可以侦听来自父窗口的 intersection
消息,以接收交叉数据。
以下示例显示了 iframe send-intersections
请求
function isAmpMessage(event, type) { return ( event.source == window.parent && event.origin != window.location.origin && event.data && event.data.sentinel == 'amp' && event.data.type == type ); } window.addEventListener('message', function (event) { if (!isAmpMessage(event, 'intersection')) { return; } event.data.changes.forEach(function (change) { console.log(change); }); });
当交叉率在阈值 [0、0.05、0.1、... 0.9、0.95、1] 之间发生变化时,父级会将交叉消息以 IntersectionObserver 条目的格式发送给 iframe。
Iframe 和同意数据
如果父页面上存在 CMP,Iframe 可以发送 send-consent-data
消息来接收同意数据。
注意:在以下示例中,我们假设该脚本位于创建的 iframe 中,其中 window.parent
是顶部窗口。如果脚本位于嵌套的 iframe 中,请将 window.parent
更改为顶部 AMP 窗口。
示例:iframe send-consent-data
请求
window.parent.postMessage( { sentinel: 'amp', type: 'send-consent-data', }, '*' );
iframe 可以通过侦听 consent-data
消息来接收同意数据响应。
请注意
consent-data
响应只会发送一次,并且当同意状态更改时(例如,当用户决定通过使用发布提示 ui 拒绝同意时)不会更新 iframe- 当省略
data-block-on-consent
时,将使用default
策略,并且将立即加载 iframe。consent-data
响应可能会根据所选策略延迟。有关更多信息,请参阅amp-consent
。
示例:iframe send-consent-data
请求
function isAmpMessage(event, type) { return ( event.source == window.parent && event.origin != window.location.origin && event.data && event.data.sentinel == 'amp' && event.data.type == type ); } window.addEventListener('message', function (event) { if (!isAmpMessage(event, 'consent-data')) { return; } console.log(event.data.consentMetadata); console.log(event.data.consentString); });
属性
src
src
属性的行为主要类似于标准 iframe,但有一个例外:将 #amp=1
片段添加到 URL,以使源文档知道它们嵌入在 AMP 上下文中。仅当 src
指定的 URL 尚无片段时,才会添加此片段。
srcdoc
、frameborder
、allowfullscreen
、allowpaymentrequest
、allowtransparency
和 referrerpolicy
这些属性的行为应该与标准 iframe 上的行为一致。
如果未指定 frameborder
,默认情况下,它将被设置为 0
。
sandbox
由 amp-iframe
创建的 iframe 始终在其上定义了 sandbox
属性。默认情况下,该值为空,这意味着它们是“最大沙盒化”的。通过设置 sandbox
值,可以选择让 iframe 的沙盒化程度降低。浏览器支持的所有值都允许使用。例如,设置 sandbox="allow-scripts"
允许 iframe 运行 JavaScript,或者 sandbox="allow-scripts allow-same-origin"
允许 iframe 运行 JavaScript、进行非 CORS 的 XHR 以及读取/写入 cookie。
如果要使用 iframe 嵌入一个并非专门为沙盒化而创建的文档,则很可能需要在 sandbox
属性中添加 allow-scripts allow-same-origin
,并且可能需要允许其他功能。
另请注意,沙盒适用于从沙盒 iframe 打开的所有窗口。这包括通过带有 target=_blank
的链接创建的新窗口(添加 allow-popups
以允许这种情况发生)。向 sandbox
属性添加 allow-popups-to-escape-sandbox
,使这些新窗口的行为类似于非沙盒的新窗口。这很可能符合您大多数时候想要和期望的行为。不幸的是,截至撰写本文时,allow-popups-to-escape-sandbox
得到 Chrome、Firefox、Safari 和 Opera 的支持,但不被 Edge 支持。
有关 sandbox
属性的更多详细信息,请参阅 MDN 上的文档。
通用属性
amp-iframe
包含了扩展到 AMP 组件的通用属性。
分析
我们强烈建议使用 amp-analytics
用于分析目的,因为它是一个更加强大、完整且高效的解决方案,可以针对各种分析供应商进行配置。
AMP 每页只允许一个用于分析和跟踪目的的 iframe。为了节省资源,这些 iframe 将在加载后 5 秒从 DOM 中删除,这应该足够完成需要完成的任何工作。
如果 iframe 看起来没有直接的用户目的(例如,不可见或很小),则会被识别为跟踪/分析 iframe。
验证
请参阅 AMP 验证器规范中的 amp-iframe
规则。
您已经阅读本文档十几次了,但它并没有真正涵盖您所有的问题?也许其他人也有同样的感觉:请在 Stack Overflow 上联系他们。
转到 Stack Overflow 发现错误或缺少功能?AMP 项目强烈鼓励您的参与和贡献!我们希望您能成为我们开源社区的持续参与者,但我们也欢迎您为自己特别感兴趣的问题做出一次性贡献。
转到 GitHub