amp-live-list

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

用法

用於包裝和呈現最簡使用者介面，以顯示在來源文件中提供新內容時，用戶端執行個體中即時更新的內容。

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 參考點，以便讓使用者能夠重新整理頁面以取得可用的新項目。預設為隱藏 (透過可覆寫樣式的 .amp-hidden 類別)。如果您想要在頁面上使用固定位置項目作為浮動按鈕 (就像社群媒體網站一樣)，以吸引讀者注意並採取行動，您可以將此參考點設定為 fixed 位置項目。目前，對於沒有插入 (新發現的 ID) 作業的更新 (使用 data-update-time) 或墓碑 (使用 data-tombstone) 作業，不會顯示 update 參考點。

實際的動作處理常式可能位於子系，而不一定要位於 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 中完全移除。

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 語法來觸發。

更新

使用新發現的更新來更新 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 規則。