amp-iframe

1.0 0.1

<script async custom-element="amp-iframe" src="https://cdn.ampproject.org/v0/amp-iframe-1.0.js"></script>

<script async custom-element="amp-iframe" src="https://cdn.ampproject.org/v0/amp-iframe-1.0.js"></script>
<link rel="stylesheet" href="https://cdn.ampproject.org/v0/amp-iframe-1.0.css">

用法

顯示 AMP 有效的 iframe。amp-iframe 與原生 iframe 有幾個重要的不同之處，旨在使其更安全，並避免 AMP 檔案被單個 iframe 佔據

• amp-iframe 不得出現在文件頂部附近（除非使用 placeholder 的 iframe，如下所述）。iframe 必須距離頂部 600 像素，或者在捲動到頂部時不在視窗前 75% 的範圍內，以較小者為準。
• 預設情況下，amp-iframe 是沙箱化的（請參閱詳細資訊）。
• amp-iframe 必須僅透過 HTTPS、data-URI 或透過 srcdoc 屬性請求資源。
• amp-iframe 不得與容器位於相同的來源，除非它們不允許在 sandbox 屬性中使用 allow-same-origin。請參閱「Iframe 來源政策」文件，以了解有關 iframe 允許來源的更多詳細資訊。

<amp-iframe
  width="200"
  height="100"
  sandbox="allow-scripts allow-same-origin"
  layout="responsive"
  src="https://www.google.com/maps/embed/v1/place?key=AIzaSyAyAS599A2GGPKTmtNr9CptD61LE4gN6oQ&q=iceland"
>
</amp-iframe>

從 0.1 版本遷移

與 0.1 不同，實驗性的 1.0 版本的 amp-iframe 已棄用 frameborder 屬性。請使用 CSS border 屬性來控制 <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 可能無法取得檢視區資訊。

在有效的 AMP 文件之外獨立使用

Bento 允許您在非 AMP 頁面中使用 AMP 元件，而無需完全承諾使用有效的 AMP。您可以採用這些元件，並將它們放置在使用不支援 AMP 的框架和 CMS 的實作中。請參閱我們的指南 在非 AMP 頁面中使用 AMP 元件，以了解更多資訊。

若要尋找 amp-iframe 的獨立版本，請參閱 bento-iframe。

帶有預留位置的 Iframe

當 amp-iframe 具有 placeholder 元素時，可以讓 amp-iframe 出現在文件頂部，如下面的範例所示。

• amp-iframe 必須包含具有 placeholder 屬性的元素 (例如 amp-img 元素)，該元素將呈現為預留位置，直到 iframe 準備好顯示為止。
• 可以透過監聽 iframe 的 onload 或 embed-ready postMessage (由 iframe 文件傳送) 來得知 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 的大小。若要執行此操作

1. amp-iframe 必須使用 resizable 屬性定義。
2. amp-iframe 必須具有 overflow 子元素。此元素通常可以是 div。但是，如果 amp-iframe 是 p 元素的子元素，則建議使用 span 或 button (以消除由 p 元素的 詞組內容 引起的問題)。
3. amp-iframe 必須設定 allow-same-origin sandbox 屬性。
4. iframe 文件必須將 embed-size 請求作為視窗訊息傳送。
5. 如果請求高度小於特定閾值 (100 像素)，則會拒絕 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 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);
  });
});

當 intersectionRatio 跨閾值 [0, 0.05, 0.1, ... 0.9, 0.95, 1] 變更時，父項會將相交訊息以 IntersectionObserver 條目的格式傳送給 iframe。

屬性

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，則很可能需要將 allow-scripts allow-same-origin 新增至 sandbox 屬性，並且您可能需要允許其他功能。

另請注意，沙箱適用於從沙箱化 iframe 開啟的所有視窗。這包括由具有 target=_blank 的連結建立的新視窗 (新增 allow-popups 以允許這種情況發生)。將 allow-popups-to-escape-sandbox 新增至 sandbox 屬性，會使這些新視窗的行為類似於非沙箱化的新視窗。這很可能是您大多數時候想要和期望的。遺憾的是，截至撰寫本文時，Chrome、Firefox、Safari 和 Opera 支援 allow-popups-to-escape-sandbox，但 Edge 不支援。

請參閱 MDN 上的文件，以取得有關 sandbox 屬性的更多詳細資訊。

通用屬性

amp-iframe 包含擴展到 AMP 元件的通用屬性。

分析

我們強烈建議將 amp-analytics 用於分析目的，因為它是一個明顯更穩健、完整且高效的解決方案，可以針對各種分析供應商進行設定。

AMP 每個頁面僅允許一個用於分析和追蹤目的的 iframe。為了節省資源，這些 iframe 將在載入後 5 秒從 DOM 中移除，這應該足以完成任何需要完成的工作。

如果 iframe 看起來沒有直接的用戶目的 (例如不可見或很小)，則會將其識別為追蹤/分析 iframe。

驗證

請參閱 AMP 驗證器規格中的 amp-iframe 規則。