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 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）操作，则不会显示 update 参考点来更新（使用 data-update-time）或墓碑（使用 data-tombstone）操作。

实际的操作处理程序可能位于后代，而不必位于 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 语法 来触发。

更新

使用新发现的更新来更新 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 类，并且一旦在后续更新中插入下一组新项目，该类将被删除。您可以添加如下面的 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 规则。