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 缓存上的文档以获取更新；如果用户正在查看从网络发布商的原始域（例如“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 语法来触发。

更新

使用新发现的更新更新 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 规则。