amp-live-list

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

用法

用於即時更新內容的包裝函式和最小化 UI，可在來源文件中提供新內容時於用戶端執行個體中更新。

amp-live-list 提供來自用戶端的即時內容更新。根據實作方式而定，它可以在沒有使用者互動的情況下更新 DOM，例如重新整理或導覽至不同的頁面。此元件的核心使用案例是即時部落格：用於突發新聞或即時事件的報導，使用者可以停留在同一個頁面或持續返回同一個頁面，以查看最新更新。常見範例包括頒獎典禮、體育賽事和選舉。

以下範例是在單一頁面上使用多個 amp-live-list。請注意，只有第一個 amp-live-list 具有固定位置按鈕，而第二個則位於元件內部，並帶有滑動動畫。

輪詢間隔也會是 16000 毫秒，而不是 20000 毫秒，因為我們選擇較低的那個。

<style amp-custom>
  amp-live-list > [update] {
    display: none;
  }

  #fixed-button {
    position: fixed;
    top: 10px;
    left: 50%;
    transform: translateX(-50%);
  }

  .slide.amp-active {
    overflow-y: hidden;
    height: 100px;
    max-height: 150px;
    transition-property: height;
    transition-duration: 0.2s;
    transition-timing-function: ease-in;
    background: #3f51b5;
  }

  .slide.amp-hidden {
    max-height: 0;
  }

  // We need to override "display: none" to be able to see
  // the transition effect on the 2nd live list.
  #live-list-2 > .amp-hidden[update] {
    display: block;
  }
</style>

<amp-live-list
  id="live-list-1"
  data-poll-interval="16000"
  data-max-items-per-page="5"
>
  <button update id="fixed-button" class="button" on="tap:live-list-1.update">
    new updates on live list 1
  </button>
  <div items>
    <div id="live-list-1-item-2" data-sort-time="1462814963592">
      <div class="card">
        <div class="logo">
          <amp-img
            src="/examples/img/ampicon.png"
            layout="fixed"
            height="50"
            width="50"
          >
          </amp-img>
        </div>
      </div>
    </div>
    <div id="live-list-1-item-1" data-sort-time="1462814955597">
      <div class="card">
        <div class="logo">
          <amp-img
            src="/examples/img/ampicon.png"
            layout="fixed"
            height="50"
            width="50"
          >
          </amp-img>
        </div>
      </div>
    </div>
  </div>
</amp-live-list>

<amp-live-list
  id="live-list-2"
  data-poll-interval="20000"
  data-max-items-per-page="10"
>
  <div update class="slide" on="tap:live-list-2.update">
    new updates on live list 2
  </div>
  <div items>
    <div id="live-list-2-item-2" data-sort-time="1464281932879">world</div>
    <div id="live-list-2-item-1" data-sort-time="1464281932878">hello</div>
  </div>
</amp-live-list>

若要瞭解如何在部落格中使用 amp-live-list，請參閱建立即時部落格教學課程。

運作方式

在背景中，當用戶端顯示使用 <amp-live-list> 的 AMP 頁面時，AMP 執行階段會輪詢主機上的原始文件以取得更新。當用戶端收到回應時，它會篩選這些更新，並動態地將它們插入回用戶端頁面中。發布商可以自訂輪詢速率，以控制傳入要求的數量，而 Google AMP 快取等 AMP 快取可以執行最佳化，以減少伺服器回應酬載，進而節省用戶端頻寬和 CPU 週期。

amp-live-list 元件有 3 個區段。我們會將這些區段稱為「參考點」，並以屬性表示。這些參考點必須是 amp-live-list 元件的直接子項。3 個參考點為

• update (更新) (必要)
• items (項目) (必要)
• pagination (分頁) (選填)

如需更多詳細資訊，請參閱下方的「參考點」區段。

範例

<amp-live-list
  id="my-live-list"
  data-poll-interval="15000"
  data-max-items-per-page="20"
>
  <button update on="tap:my-live-list.update">You have updates!</button>
  <div items></div>
  <!-- pagination is optional -->
  <div pagination></div>
</amp-live-list>

輪詢

在大多數即時部落格的實作中，內容是由伺服器推送至頁面的用戶端執行個體，或是用戶端輪詢 JSON 端點以接收更新。此元件的實作方式不同，在於頁面的用戶端執行個體會輪詢伺服器端文件副本，以取得 items 參考點的更新。例如：如果使用者正在檢視從 AMP 快取提供的文件，則用戶端會輪詢託管在該 AMP 快取上的文件以取得更新；如果使用者正在檢視從網路發布商原始網域 (例如「example.com」) 提供的文件，則用戶端會輪詢託管在該原始網域上的文件以取得更新。

這表示內容發布商不需要設定 JSON 端點或推送機制，此元件即可運作。新的內容只需要發布到相同的網址，並具有有效的 amp-live-list 標記，使用者就會在下一次輪詢期間將該內容提取到其用戶端執行個體中 (輪詢間隔可在元件中設定，且有效間隔須高於最低 15 秒)。

當頁面上有多個 amp-live-list 元件時，我們會選擇所有 amp-live-list 元件中最小的輪詢間隔，並將其用作輪詢間隔。

參考點

update (更新)

當從伺服器收到新項目時，會顯示 update (更新) 參考點，以便為使用者提供重新整理頁面以取得新項目的功能 (若有)。預設為隱藏 (透過 .amp-hidden 類別，其樣式可以覆寫)。如果您想要在頁面上使用固定位置項目 (如社群媒體網站上的浮動按鈕)，以吸引讀者注意並採取行動，您可以將此參考點設定為 fixed 位置項目。目前，update (更新) 參考點不會針對更新 (使用 data-update-time) 或墓碑 (使用 data-tombstone) 作業顯示，除非有插入 (新發現的 ID) 作業。

實際的動作處理常式可能位於子系，且不一定要位於 update (更新) 參考點。amp-live-list 元件接著會有一個內部 update (更新) 方法，可以接收動作。請參閱 on="tap:my-live-list.update" 處理常式。

範例

<amp-live-list
  id="my-live-list"
  data-poll-interval="15000"
  data-max-items-per-page="20"
>
  <div update class="outer-container">
    <div class="inner-container">
      <button class="btn" on="tap:my-live-list.update">Click me!</button>
    </div>
  </div>
  <div items></div>
</amp-live-list>

items (項目)

items (項目) 參考點是用於插入、取代或移除新項目的位置。items (項目) 參考點的子項必須具有 id 和 data-sort-time 屬性。

pagination (分頁)

pagination (分頁) 參考點是任何分頁標記所在的位置。我們建議在此參考點下方建立一個小的子樹狀結構，因為當頁數增加時，amp-live-list 元件會對從伺服器收到的 DOM 執行內嵌取代。我們不會執行任何特殊差異比較，只會完全取代內容。

更新行為與使用者體驗

當用戶端從輪詢伺服器文件發現更新時，來自 items (項目) 參考點子項的任何新發現的 id 都會使 update (更新) 參考點變成可見。使用者必須執行動作，才能將這些項目插入到用戶端的即時 DOM 中。當讀者點擊更新動作時，我們會將 amp-live-list 元件的頂端捲動到視野中。

如果 data-update-time 屬性存在，且其值大於屬性上原始 data-sort-time，則項目會透過 replaceChild 作業就地更新。如果 data-tombstone 屬性存在，則會清空元素的子樹狀結構，並透過 CSS 隱藏項目 (請參閱 amp-live-list.css)。

如果在輪詢要求中找到取代或墓碑作業，但未找到插入作業 (沒有新項目)，則會執行取代和墓碑作業，而無需讀者執行動作。元件和 AMP 執行階段會嘗試維持視野的捲動位置，但由於取代作業可能在其子樹狀結構中包含在事後導致大小調整的元件 (amp-twitter、amp-iframe 等)，因此我們不建議透過 data-update-time 屬性進行大量取代作業。

分頁運作方式

由於 AMP 的重點是效能，因此我們建議發布商透過限制 items (項目) 參考點的子項數量，以及設定良好的 data-max-items-per-page 值，來保持單一頁面上的項目數量較少。用戶端和可能使用的任何快取都不知道項目的完整數量。因此，發布商有責任根據有效項目的數量正確更新 pagination (分頁) 參考點。例如，具有 data-tombstone 屬性的項目不應計算在內，因為它們是隱藏的。

一旦有效即時項目的數量超過 data-max-items-per-page 值，元件就會嘗試移除視野下方的項目，直到即時項目的數量等於或低於 data-max-items-per-page 值。如果刪除的項目不在視野下方，則項目數量可能會超過 data-max-items-per-page 值。

當讀者不在文件的第 1 頁時，應將 disabled (已停用) 屬性套用至所有 amp-live-list 元件，因為元件仍會嘗試插入新項目 (如果它識別出任何新項目)，且不知道不在第一頁。

伺服器端篩選

請參閱 伺服器端篩選的文件。

屬性

id (必要)

用於唯一識別 amp-live-list (因為單一頁面上允許多個)。

data-poll-interval (資料輪詢間隔)

檢查新內容的間隔時間 (毫秒為單位) (強制執行最低 15000 毫秒)。如果未提供 data-poll-interval，則預設為最低 15000 毫秒。

data-max-items-per-page (資料每頁最大項目數) (必要)

子項目的最大數量。其他元素會被視為在下一個「頁面」上。如果子項目數量大於屬性上提供的數量，則子項目數量將成為新的 data-max-items-per-page。一旦 amp-live-list 上的即時項目數量超過 data-max-items-per-page 限制，視野下方的項目將會從即時 DOM 中完全移除。

disabled (已停用)

不會進行輪詢。建議在不在第 1 頁時 (查看封存資料) 以及文章不再是最新且不應再更新時使用。

items (項目) 參考點子項的屬性

通常屬性要求僅在實際元件上強制執行，但由於我們需要在用戶端錨定並做出決策，因此我們也需要在 amp-live-list 的直接子項上要求 items (項目) 和 update (更新) 屬性。items (項目) 參考點的子項也會有屬性要求。

id (必要)

items (項目) 子項的 ID 絕不能變更。

data-sort-time (資料排序時間) (必要)

用於排序項目的時間戳記。較新的時間戳記將插入在較舊項目之前。我們建議使用 Unix 時間 (自 1970 年 1 月 1 日星期四以來經過的秒數)。

data-update-time (資料更新時間) (選填)

項目上次更新的時間戳記。使用此屬性觸發現有項目的更新：用戶端會將此項目中的所有現有內容取代為新的、更新的內容，而不會觸發更新參考點的顯示。我們建議使用 Unix 時間 (自 1970 年 1 月 1 日星期四以來經過的秒數)。

data-tombstone (資料墓碑) (選填)

如果存在，則假設項目已刪除。

sort (排序) (選填)

如果存在且值為「ascending」(目前任何其他值皆無效)，則較新的項目將插入在即時清單的底部，而不是頂部。

動作

amp-live-list 公開下列動作，您可以使用 AMP on-syntax 語法觸發。

update (更新)

使用新發現的更新來更新 DOM 元素。

樣式設定

在非常慢的連線速度下，元件的 JavaScript 和樣式可能會比取消隱藏主體 (amp-boilerplate 樣式 timesout) 的時間晚到達，因此我們強烈建議在您自己的 amp-custom 樣式中新增以下樣式。

amp-live-list > [update] {
  display: none;
}

當我們將 amp-active 類別套用至更新參考點時，它會設定 display: block。

amp-live-list-item 類別會新增至 items (項目) 參考點的所有子項。

所有新插入的項目也會新增 amp-live-list-item-new 類別，並在下一組新項目在後續更新中插入時移除。您可以新增醒目提示效果，如下列 CSS。

.amp-live-list-item-new {
  animation: amp-live-list-item-highlight 2s;
}

@keyframes amp-live-list-item-highlight {
  0% {
    box-shadow: 0 0 5px 2px rgba(81, 203, 238, 1);
  }
  100% {
    box-shadow: 0;
  }
}

CSS 會隱藏具有 data-tombstone 屬性的 items (項目) 參考點的子項，您可以透過執行以下操作來覆寫此行為

amp-live-list > [items] > [data-tombstone] {
  display: block;
}

.amp-hidden 和 .amp-active 類別會新增至 update (更新) 參考點，您可以連結到此類別以新增轉場效果。

驗證

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