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 缓存上托管的文档以进行更新；如果用户正在查看从 Web 发布商的原始域（例如“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 中完全删除。

禁用

不会发生轮询。当不在第 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 引用点的子元素，可以通过执行以下操作来覆盖该 CSS：

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

.amp-hidden 和 .amp-active 类被添加到 update 引用点，您可以挂钩到这个类来添加过渡效果。

验证

请参阅 AMP 验证器规范中的 amp-live-list 规则。