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 端點或推送機制，此元件即可運作。新內容只需發布到相同的 URL，並具有有效的 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 語法觸發。

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