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 參考點，以便使用者在有新項目可用時重新整理頁面。預設為隱藏 (透過 .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 參考點的子項必須具有 id 和 data-sort-time 屬性。

分頁

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 中完全移除。

已停用

不會發生輪詢。建議在不在第 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 觸發。

更新

使用新探索到的更新項目更新 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 參考點的子項，您可以透過執行以下操作來覆寫此 CSS

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

.amp-hidden 和 .amp-active 類別會新增至 update 參考點，您可以掛鉤到此類別以新增轉場效果。

驗證

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