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 會批次處理傳送至 JSON 端點的 XMLHttpRequests (XHR)。這可讓您使用單一 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> 允許所有標準網址變數替換。如要瞭解詳情，請參閱替換指南。

例如

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

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

屬性

src (必填)

遠端端點的網址，該端點會傳回將在此 <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] 支援網址和非網址運算式值。

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 規則。