amp-list

1.0 0.1

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

用法

amp-list 元件從 CORS JSON 端點擷取動態內容。端點的回應包含資料，這些資料會在指定的範本中呈現。

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

• 一個 template 屬性，參考現有範本元素的 ID。
• 直接嵌套在 amp-list 元素內的範本元素。

有關範本的更多詳細資訊，請參閱 AMP HTML 範本。

顯示動態清單

在以下範例中，我們擷取包含 URL 和標題的 JSON 資料，並在嵌套的 amp-mustache 範本 中呈現內容。

<amp-list
  width="auto"
  height="100"
  layout="fixed-height"
  src="/static/inline-examples/data/amp-list-urls.json"
>
  <template type="amp-mustache">

    <div class="url-entry">
      <a href="{{url}}">{{title}}</a>
    </div>
  </template>
</amp-list>

這是我們使用的 JSON 檔案

{
  "items": [
    {
      "title": "AMP YouTube Channel",
      "url": "https://www.youtube.com/channel/UCXPBsjgKKG2HqsKBhWA4uQw"
    },
    {
      "title": "AMPproject.org",
      "url": "https://www.ampproject.org/"
    },
    {
      "title": "AMP",
      "url": "https://amp.dev.org.tw/"
    },
    {
      "title": "AMP Start",
      "url": "https://ampstart.com/"
    }
  ]
}

這是我們設定擷取內容樣式的方式

amp-list div[role='list'] {
  display: grid;
  grid-gap: 0.5em;
}

即使文件是從 AMP 快取提供的，請求也始終來自客戶端。載入是根據目前可視區域與元素的距離，使用正常的 AMP 規則觸發的。

如果 <amp-list> 在載入後需要更多空間，它會使用正常的 AMP 流程請求 AMP 執行階段更新其高度。如果 AMP 執行階段無法滿足新高度的請求，它將在可用時顯示 overflow 元素。但請注意，<amp-list> 元素通常放置在文件的底部，幾乎總是可以保證 AMP 執行階段可以調整它們的大小。

amp-list 的無障礙考量

預設情況下，<amp-list> 會將 list ARIA 角色新增到清單元素，並將 listitem 角色新增到透過範本呈現的項目元素。如果清單元素或其任何子元素不是「可透過 Tab 鍵選取」(可透過鍵盤按鍵 (例如 a 和 button 元素) 或任何具有正 tabindex 的元素存取)，則預設情況下會將 tabindex 的 0 新增到清單項目。這種行為不一定總是適當的 - 通常，只有互動式控制項/內容應該是可聚焦的。如果您想抑制此行為，請確保在範本的最外層元素中包含 tabindex="-1"。

<template type="amp-mustache">

  <div class="item">{{item}}</div>
  <div class="price">{{price}}</div>
</template>

<template type="amp-mustache">

  <div>
    <div class="item">{{item}}</div>
    <div class="price">{{price}}</div>
  </div>
</template>

XHR 批次處理

AMP 會批次處理對 JSON 端點的 XMLHttpRequests (XHR)，也就是說，您可以使用單個 JSON 資料請求作為 AMP 頁面上多個消費者 (例如，多個 <amp-list> 元素) 的資料來源。例如，如果您的 <amp-list> 向端點發出 XHR，則在 XHR 傳輸過程中，所有後續對同一端點的 XHR 都不會觸發，而是會傳回第一個 XHR 的結果。

在 <amp-list> 中，您可以使用 items 屬性來呈現 JSON 回應的子集，讓您可以擁有多個 <amp-list> 元素呈現不同的內容，但共用單個 XHR。

指定溢位

可選地，<amp-list> 元件可以包含一個具有 overflow 屬性的元素。如果滿足以下所有條件，AMP 將顯示此元素

• 呈現到 amp-list 中的內容超出其指定的大小。
• amp-list 的底部在可視區域內。
• amp-list 的底部不在頁面底部附近 (定義為文件底部 15% 或底部 1000px 的最小值)

如果 amp-list 在可視區域之外，它將自動展開。

範例：當清單需要更多空間時顯示溢位

在以下範例中，我們顯示圖片和標題的清單。由於 <amp-list> 內容需要的空間大於可用空間，因此 AMP 框架會顯示溢位元素。

<amp-list
  width="auto"
  height="140"
  layout="fixed-height"
  src="/static/inline-examples/data/amp-list-data.json"
>
  <template type="amp-mustache">

    <div class="image-entry">
      <amp-img src="{{imageUrl}}" width="100" height="75"></amp-img>
      <span class="image-title">{{title}}</span>
    </div>
  </template>
  <div overflow class="list-overflow" style="background-color:red;">
    See more
  </div>
</amp-list>

AMP 將以下 CSS 應用於具有 overflow 屬性的元素

.list-overflow[overflow] {
  position: absolute;
  bottom: 0;
  left: 0;
  right: 0;
}

佔位符和備用方案

可選地，<amp-list> 支援佔位符和/或備用方案。

• 佔位符 是具有 placeholder 屬性的子元素。此元素會一直顯示，直到 <amp-list> 成功載入。如果還提供了備用方案，則在 <amp-list> 載入失敗時，佔位符會隱藏。
• 備用方案 是具有 fallback 屬性的子元素。如果 <amp-list> 載入失敗，則會顯示此元素。

在 佔位符和備用方案 中瞭解更多資訊。請注意，子元素不能同時是佔位符和備用方案。

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

重新整理資料

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

<button on="tap:myList.refresh">Refresh List</button>
<amp-list id="myList" src="https://foo.com/list.json">
  <template type="amp-mustache">
    <div>{{title}}</div>
  </template>
</amp-list>

動態調整大小

在某些情況下，我們可能需要 <amp-list> 在使用者互動時調整大小。例如，當 <amp-list> 包含使用者可能點擊的 amp-accordion 時，當 <amp-list> 的內容由於綁定的 CSS 類別而更改大小時。changeToLayoutContainer 動作透過在觸發此動作時將 amp 清單更改為 layout="CONTAINER" 來處理此問題。請參閱以下範例

<button on="tap:list.changeToLayoutContainer()">Show Grid</button>
<amp-list
  id="list"
  width="396"
  height="80"
  layout="responsive"
  src="/test/manual/amp-list-data.json?RANDOM"
>
  <template type="amp-mustache">
{{title}}  </template>
</amp-list>

屬性

src (必要)

傳回 JSON 以供 amp-list 呈現的遠端端點的 URL。這必須參考 CORS HTTP 服務，並且不支援不安全的 HTTP。

如果擷取 src URL 上的資料失敗，則 <amp-list> 會觸發低信任度的 fetch-error 事件。

items

定義用於在回應中定位要呈現的陣列的表達式。這是一個點符號表達式，可透過 JSON 回應的欄位進行導覽。預設情況下，<amp-list> 需要一個陣列，可以使用 single-item 屬性從物件載入資料。

• 預設值為 "items"。預期的回應：{items: [...]}。
• 如果回應本身是所需的陣列，請使用 "." 值。預期的回應是：[...]。
• 允許嵌套導覽 (例如，"field1.field2")。預期的回應是：{field1: {field2: [...]}}。

當指定 items="items" (這是預設值) 時，回應必須是一個 JSON 物件，其中包含一個名為 "items" 的陣列屬性

{
  "items": [...]
}

max-items

一個整數值，指定要呈現的 items 陣列的最大長度。如果傳回的值超過 max-items，則 items 陣列將被截斷為 max-items 個項目。

single-item

使 <amp-list> 將傳回的結果視為單個元素陣列。物件回應將被包裝在陣列中，因此 {items: {...}} 的行為就像它是 {items: [{...}]} 一樣。

binding

對於使用 <amp-list> 且同時使用 amp-bind 的頁面，控制是否在呈現的子元素中對綁定 (例如 [text]) 的評估進行阻擋渲染。

我們建議使用 binding="no" 或 binding="refresh" 以獲得更快的效能。

• binding="no"：永遠不阻擋渲染 **(最快)**。
• binding="refresh"：在初始載入時不阻擋渲染 **(較快)**。
• binding="always"：始終阻擋渲染 **(慢)**。

如果未提供 binding 屬性，則預設值為 always。

通用屬性

此元素包含擴展到 AMP 元件的 通用屬性。

無效的 AMP 電子郵件屬性

AMP for Email 規範不允許在 AMP 電子郵件格式上使用以下屬性。

• [src]
• [state]
• [is-layout-container]
• auto-resize
• credentials
• data-amp-bind-src
• load-more
• load-more-bookmark
• reset-on-refresh
• xssi-prefix

驗證

請參閱 AMP 驗證器規範中的 amp-list 規則。