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 位置项。目前，update 参考点不会显示任何更新（使用 data-update-time）或 tombstone（使用 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 参考点的子项必须具有 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）。

如果在轮询请求中发现替换或 tombstone 操作，但没有发现插入（没有新项目），则将执行替换和 tombstone 操作，而无需读者操作。组件和 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 类，并且一旦在后续更新中插入下一组新项目后，该类将被删除。您可以添加如下所示的突出显示效果。

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