amp-render

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

用法

amp-render 元件會擷取 JSON 資料，然後使用範本呈現該資料。amp-render 可以使用來自 CORS JSON 端點、來自 amp-state 狀態變數或來自 amp-script 的資料。

由於 amp-render 的資料可能來自 amp-script，因此您可以使用自己的 JavaScript 來篩選資料、限制其大小、建立清單功能，以及自訂元件的行為和外觀。如果您偏好使用 HTML 屬性，amp-list 提供了更豐富的功能集。

您可以用下列兩種方式之一指定範本

• 參考現有範本元素 ID 的 template 屬性。

<template id="my-template" type="amp-mustache">
  Your personal offer: ${{price}}</template>
<amp-render template="my-template" src="https://example.com/data.json">
</amp-render>

• 直接巢狀於 amp-render 元素內的範本元素。

<amp-render src="https://example.com/data.json">
  <template type="amp-mustache">
    Your personal offer: ${{price}}  </template>
</amp-render>

如需範本的詳細資訊，請參閱 AMP HTML 範本。

XHR 批次處理

AMP 會批次處理 XMLHttpRequests (XHR) 至 JSON 端點。這讓您可以使用單一 JSON 要求做為 AMP 頁面上多個元素的資料來源。例如，如果您的 <amp-render> 向端點發出 XHR，在 XHR 傳輸期間，所有後續向相同端點發出的 XHR 都不會觸發，而是會傳回第一個 XHR 的結果。

預留位置和後備方案

<amp-render> 支援選用的預留位置和/或後備方案。

• 預留位置是具有 placeholder 屬性的子元素。此元素會顯示直到 <amp-render> 成功載入為止。如果也提供了後備方案，則當 <amp-render> 載入失敗時，預留位置會隱藏。
• 後備方案是具有 fallback 屬性的子元素。如果 <amp-render> 載入失敗，則會顯示此元素。

如需更多資訊，請參閱預留位置與後備方案。請注意，子元素不能同時是預留位置和後備方案。

<amp-render src="https://example.com/data.json">
  <div placeholder>Loading ...</div>
  <div fallback>Failed to load data.</div>
</amp-render>

重新整理資料

<amp-render> 元素公開了 refresh 動作，其他元素可以在 on="tap:..." 屬性中參考該動作。

<button on="tap:my-component.refresh">Refresh</button>
<amp-render id="my-component" src="https://example.com/data.json">
  <template type="amp-mustache">
    <div>{{title}}</div>
  </template>
</amp-render>

動態調整大小

在某些情況下，我們可能需要 <amp-render> 元素在使用者互動時調整大小。例如，當內容不符合具有 layout="fixed-height" 的指定 height 屬性，或指定的 height 過大而產生空白時。<amp-render 元素公開了 resizeToContents 動作，可調整高度以符合內容。請參閱以下範例

<button on="tap:my-component.resizeToContents()">Expand</button>
<amp-render
  id="my-component"
  src="https://example.com/data.json"
  layout="fixed-height"
  height="30">
    <template type="amp-mustache">
{{#cars}}        <p>{{make}} {{model}}</p>
{{/cars}}    </template>
</amp-render>

替換

<amp-render> 允許所有標準 URL 變數替換。如需更多資訊，請參閱 替換指南。

例如

<amp-render src="https://example.com/data.json?RANDOM"></amp-render>

可能會向類似 https://example.com/data.json?0.8390278471201 的網址發出要求，其中 RANDOM 值是在每次曝光時隨機產生。

屬性

src (必要)

遠端端點的 URL，該端點會傳回將在此 <amp-render> 內呈現的 JSON。src 屬性有三個有效的通訊協定。

1. https：這必須參照 CORS HTTP 服務。不安全的 HTTP 不受支援。
2. amp-state：用於從 <amp-state> 資料初始化。如需更多詳細資訊，請參閱 amp-list 中的 從 <amp-state> 初始化 章節。
3. amp-script：用於將 <amp-script> 函式做為資料來源。如需更多詳細資訊，請參閱 amp-list 中的 將 <amp-script> 做為資料來源 章節。

如果存在 [src] 屬性，則可以省略 src 屬性。[src] 支援 URL 和非 URL 運算式值。

template (範本)

參考已定義範本元素的 ID。如果範本是 amp-render 元素的子元素，則此屬性不是必要的。

credentials (憑證)

定義 Fetch API 指定的 credentials 選項。

• 支援的值：omit、include
• 預設值：omit

若要傳送憑證，請傳遞 include 的值。如果設定此值，則回應必須遵循 AMP CORS 安全性指南。

以下範例在 credentials 中使用 "include" 值來顯示個人化內容

<amp-render
  credentials="include"
  src="<%host%>/json/product.json?clientId=CLIENT_ID(myCookieId)"
>
  <template type="amp-mustache">
    Your personal offer: ${{price}}  </template>
</amp-render>

xssi-prefix

導致 <amp-render> 在剖析之前，從擷取的 JSON 中移除前置字串。這對於包含 安全性前置字串 (例如 )]}) 的 API 很有用，以協助防止跨網站指令碼攻擊。

例如，假設我們有一個 API 傳回此回應

)]}{ "items": ["value"] }

我們可以指示 amp-render 移除安全性前置字串，如下所示

<amp-render xssi-prefix=")]}" src="https://example.com/data.json"></amp-render>

key (索引鍵)

定義運算式以尋找要呈現的回應中的子物件。例如，假設我們有一個 API 傳回此回應

{
  "automobiles": {
    "cars": {
      "german": {
        "make": "BMW",
        "model": "M3"
      },
      "american": {
        "make": "Tesla",
        "model": "Model X"
      }
    }
  }
}

如果我們只想顯示回應中的德國汽車，可以使用 key 屬性。

<amp-render src="https://example.com/data.json" key="automobiles.cars.german">
  <template type="amp-mustache">
{{make}} {{model}}  </template>
</amp-render>

binding (繫結)

控制是否在同時使用 amp-render 和 amp-bind 的頁面上，封鎖呈現以評估子項中的繫結 (例如 [text])。

• binding="never" 或 binding="no"：永遠不要封鎖呈現 (最快)。
• binding="refresh" (預設)：在初始載入時不封鎖呈現 (較快)。
• binding="always"：永遠封鎖呈現 (慢速)。

基本上，binding="always" 是 binding="refresh"，也會封鎖以評估 amp-render 初始載入時的繫結。

通用屬性

此元素包含擴充至 AMP 元件的通用屬性。

無障礙功能

對於沒有 aria-live 屬性的 amp-render 執行個體，將會新增 aria-live="polite"，以便螢幕閱讀器宣告內容的任何變更。若要覆寫 aria-live="polite" 的新增，請新增 aria-live="off"。

驗證

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