amp-list

1.0 0.1

<script async custom-element="amp-list" src="https://cdn.ampproject.org/v0/amp-list-0.1.js"></script>

用法

amp-list 组件从 CORS JSON 端点获取动态内容。来自端点的响应包含数据，这些数据在指定的模板中呈现。

您可以通过两种方式之一指定模板

• 一个 template 属性，该属性引用现有模板元素的 ID。
• 一个直接嵌套在 amp-list 元素内的模板元素。

有关模板的更多详细信息，请参阅 AMP HTML 模板。

显示动态列表

在以下示例中，我们检索包含 URL 和标题的 JSON 数据，并在嵌套的 amp-mustache 模板中呈现内容。

<amp-list
  width="auto"
  height="100"
  layout="fixed-height"
  src="/static/inline-examples/data/amp-list-urls.json"
>
  <template type="amp-mustache">

    <div class="url-entry">
      <a href="{{url}}">{{title}}</a>
    </div>
  </template>
</amp-list>

这是我们使用的 JSON 文件

{
  "items": [
    {
      "title": "AMP YouTube Channel",
      "url": "https://www.youtube.com/channel/UCXPBsjgKKG2HqsKBhWA4uQw"
    },
    {
      "title": "AMPproject.org",
      "url": "https://www.ampproject.org/"
    },
    {
      "title": "AMP",
      "url": "https://amp.org.cn/"
    },
    {
      "title": "AMP Start",
      "url": "https://ampstart.com/"
    }
  ]
}

这是我们如何设置获取的内容的样式

amp-list div[role='list'] {
  display: grid;
  grid-gap: 0.5em;
}

请求始终从客户端发出，即使文档是从 AMP 缓存提供的也是如此。加载是使用正常的 AMP 规则触发的，具体取决于元素与当前视口之间的距离。

如果 <amp-list> 在加载后需要更多空间，它会请求 AMP 运行时使用正常的 AMP 流程更新其高度。如果 AMP 运行时无法满足对新高度的请求，它将在可用时显示 overflow 元素。但是请注意，<amp-list> 元素在文档底部的典型位置几乎总是保证 AMP 运行时可以调整它们的大小。

amp-list 的可访问性注意事项

默认情况下，<amp-list> 会向列表元素添加 list ARIA 角色，并向通过模板呈现的项目元素添加 listitem 角色。如果列表元素或其任何子元素不是“可制表”（可通过键盘键（如 a 和 button 元素或具有正 tabindex 的任何元素）访问），则默认情况下会向列表项添加 tabindex 为 0。这种行为并非总是合适的 - 通常，只有交互式控件/内容才应该是可聚焦的。如果您想抑制此行为，请确保将 tabindex="-1" 作为模板最外层元素的一部分包含进来。

<template type="amp-mustache">

  <div class="item">{{item}}</div>
  <div class="price">{{price}}</div>
</template>

<template type="amp-mustache">

  <div>
    <div class="item">{{item}}</div>
    <div class="price">{{price}}</div>
  </div>
</template>

XHR 批处理

AMP 将 XMLHttpRequests (XHR) 批处理到 JSON 端点，也就是说，您可以使用单个 JSON 数据请求作为 AMP 页面上多个使用者（例如，多个 <amp-list> 元素）的数据源。例如，如果您的 <amp-list> 向端点发出 XHR，那么在 XHR 处于活动状态时，所有后续对同一端点的 XHR 都不会触发，而是会返回来自第一个 XHR 的结果。

在 <amp-list> 中，您可以使用 items 属性来呈现 JSON 响应的子集，从而允许您拥有多个 <amp-list> 元素呈现不同的内容但共享单个 XHR。

指定溢出

（可选）<amp-list> 组件可以包含带有 overflow 属性的元素。如果满足以下所有条件，AMP 将显示此元素

• 呈现到 amp-list 中的内容超出其指定的大小。
• amp-list 的底部位于视口内。
• amp-list 的底部不在页面底部附近（定义为文档底部 15% 或底部 1000 像素的最小值）

如果 amp-list 在视口之外，它将自动扩展。

示例：当列表需要更多空间时显示溢出

在以下示例中，我们显示图像和标题的列表。由于 <amp-list> 内容需要比可用空间更多的空间，AMP 框架会显示 overflow 元素。

<amp-list
  width="auto"
  height="140"
  layout="fixed-height"
  src="/static/inline-examples/data/amp-list-data.json"
>
  <template type="amp-mustache">

    <div class="image-entry">
      <amp-img src="{{imageUrl}}" width="100" height="75"></amp-img>
      <span class="image-title">{{title}}</span>
    </div>
  </template>
  <div overflow class="list-overflow" style="background-color:red;">
    See more
  </div>
</amp-list>

AMP 将以下 CSS 应用于带有 overflow 属性的元素

.list-overflow[overflow] {
  position: absolute;
  bottom: 0;
  left: 0;
  right: 0;
}

占位符和回退

（可选）<amp-list> 支持占位符和/或回退。

• 占位符是带有 placeholder 属性的子元素。此元素会一直显示，直到 <amp-list> 成功加载。如果还提供了回退，则当 <amp-list> 加载失败时，占位符将被隐藏。
• 回退是带有 fallback 属性的子元素。如果 <amp-list> 加载失败，则会显示此元素。

在占位符和回退中了解更多信息。请注意，子元素不能既是占位符又是回退。

<amp-list src="https://foo.com/list.json">
  <div placeholder>Loading ...</div>
  <div fallback>Failed to load data.</div>
</amp-list>

刷新数据

<amp-list> 元素公开一个 refresh 操作，其他元素可以在 on="tap:..." 属性中引用该操作。

<button on="tap:myList.refresh">Refresh List</button>
<amp-list id="myList" src="https://foo.com/list.json">
  <template type="amp-mustache">
    <div>{{title}}</div>
  </template>
</amp-list>

动态调整大小

在几种情况下，我们可能需要 <amp-list> 在用户交互时调整大小。例如，当 <amp-list> 包含一个用户可以点击的 amp-accordion 时，当 <amp-list> 的内容由于绑定的 CSS 类而改变大小时。changeToLayoutContainer 操作通过在触发此操作时将 amp 列表更改为 layout="CONTAINER" 来处理此问题。请参阅以下示例

<button on="tap:list.changeToLayoutContainer()">Show Grid</button>
<amp-list
  id="list"
  width="396"
  height="80"
  layout="responsive"
  src="/test/manual/amp-list-data.json?RANDOM"
>
  <template type="amp-mustache">
{{title}}  </template>
</amp-list>

属性

src（必需）

返回 amp-list 呈现的 JSON 的远程端点的 URL。这必须引用 CORS HTTP 服务，并且不支持不安全的 HTTP。

如果获取 src URL 处的数据失败，则 <amp-list> 会触发低信任的 fetch-error 事件。

items

定义一个表达式，以定位响应中要呈现的数组。这是一个点符号表达式，通过 JSON 响应的字段导航。默认情况下，<amp-list> 期望一个数组，可以使用 single-item 属性从对象加载数据。

• 默认值为 "items"。预期的响应：{items: [...]}。
• 如果响应本身是所需的数组，请使用值 "."。预期的响应是：[...]。
• 允许嵌套导航（例如，"field1.field2"）。预期的响应是：{field1: {field2: [...]}}。

当指定 items="items" 时（这是默认值），响应必须是一个 JSON 对象，其中包含一个名为 "items" 的数组属性。

{
  "items": [...]
}

max-items

一个整数值，指定要呈现的 items 数组的最大长度。如果返回的值超过 max-items，则 items 数组将被截断为 max-items 个条目。

single-item

使 <amp-list> 将返回的结果视为单个元素数组。对象响应将被包装在一个数组中，因此 {items: {...}} 的行为将如同 {items: [{...}]}。

binding

对于也使用 amp-bind 的 <amp-list> 的页面，控制是否阻止在呈现的子项中评估绑定（例如，[text]）时进行渲染。

我们建议使用 binding="no" 或 binding="refresh" 以获得更快的性能。

• binding="no"：从不阻止渲染（最快）。
• binding="refresh"：不要在初始加载时阻止渲染（更快）。
• binding="always"：始终阻止渲染（慢）。

如果未提供 binding 属性，则默认值为 always。

通用属性

此元素包含扩展到 AMP 组件的通用属性。

无效的 AMP 电子邮件属性

AMP for Email 规范禁止在 AMP 电子邮件格式上使用以下属性。

• [src]
• [state]
• [is-layout-container]
• auto-resize
• credentials
• data-amp-bind-src
• load-more
• load-more-bookmark
• reset-on-refresh
• xssi-prefix

验证

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