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 具有固定位置按钮，而第二个 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 Cache 之类的 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 缓存上托管的文档以获取更新；如果用户正在查看从 Web 发布商的原始域（例如“example.com”）提供的文档，则客户端将轮询该原始域上托管的文档以获取更新。

这意味着内容发布商无需设置 JSON 端点或推送机制即可使此组件正常工作。只需将新内容发布到同一 URL，并使用有效的 amp-live-list 标记，用户将在下一次轮询期间将其内容拉入其客户端实例（轮询间隔在组件中可配置，并且在 15 秒的最小值之上有效）。

当页面上有多个 amp-live-list 组件时，我们选择 amp-live-list 组件中最小的轮询间隔，并将其用作轮询间隔。

参考点

更新

当从服务器收到新项目时，将显示 update 参考点，以便为用户提供在有新项目可用时刷新页面的能力。它默认是隐藏的（通过一个 .amp-hidden 类，其样式可以被覆盖）。如果要像社交媒体网站上那样在页面上显示一个浮动按钮，以吸引读者的注意力进行操作，则可以将此参考点设置为 fixed 位置项。目前，在没有插入（新发现的 ID）操作的情况下，不会为更新（使用 data-update-time）或 tombstone（使用 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

不会进行轮询。当不在第一页（查看存档数据）并且文章不再新鲜且不应再更新时，建议使用此设置。

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 和样式可能比 body 取消隐藏时到达得更晚（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 类，并且一旦在后续更新中插入下一组新项目，该类将被删除。您可以添加如下的突出显示效果。

.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 规则。