amp-carousel

描述

沿水平轴显示多个相似的内容片段。

必需脚本

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

支持的布局

fill fixed fixed-height flex-item intrinsic nodisplay responsive

示例

你好，世界，电子邮件

一个通用的轮播图，用于沿水平轴显示多个相似的内容片段；旨在具有高度的灵活性和高性能。

行为

amp-carousel 组件的每个直接子元素都被视为轮播图中的一个项目。这些节点中的每一个也可能具有任意的 HTML 子元素。

轮播图包含任意数量的项目，以及用于向前或向后移动的可选导航箭头。对于 type="slides"，箭头一次移动一个项目。对于 type="carousel"，箭头一次向前或向后移动一个轮播图的宽度。

如果用户滑动或单击可选的导航箭头，轮播图会在项目之间前进。

<amp-carousel
  width="450"
  height="300"
  layout="responsive"
  type="slides"
  role="region"
  aria-label="Basic carousel"
>
  <amp-img
    src="/static/inline-examples/images/image1.jpg"
    width="450"
    height="300"
  ></amp-img>
  <amp-img
    src="/static/inline-examples/images/image2.jpg"
    width="450"
    height="300"
  ></amp-img>
  <amp-img
    src="/static/inline-examples/images/image3.jpg"
    width="450"
    height="300"
  ></amp-img>
</amp-carousel>

在 Playground 中打开此代码段

前进到特定幻灯片

在元素上为 on 属性设置 tap:carousel-id.goToSlide(index=N) 方法，将在用户点击或单击时，将 ID 为“carousel-id”的轮播图前进到 index=N 的幻灯片（第一张幻灯片的索引为 0，第二张幻灯片的索引为 1，依此类推）。

在以下示例中，我们有一个包含三个图像的轮播图，轮播图下方有预览按钮。当用户单击其中一个按钮时，将显示相应的轮播图项目。

<amp-carousel
  id="carousel-with-preview"
  width="450"
  height="300"
  layout="responsive"
  type="slides"
  role="region"
  aria-label="Carousel with slide previews"
>
  <amp-img
    src="/static/inline-examples/images/image1.jpg"
    width="450"
    height="300"
    layout="responsive"
    alt="apples"
  ></amp-img>
  <amp-img
    src="/static/inline-examples/images/image2.jpg"
    width="450"
    height="300"
    layout="responsive"
    alt="lemons"
  ></amp-img>
  <amp-img
    src="/static/inline-examples/images/image3.jpg"
    width="450"
    height="300"
    layout="responsive"
    alt="blueberries"
  ></amp-img>
</amp-carousel>
<div class="carousel-preview">
  <button on="tap:carousel-with-preview.goToSlide(index=0)">
    <amp-img
      src="/static/inline-examples/images/image1.jpg"
      width="60"
      height="40"
      alt="apples"
    ></amp-img>
  </button>
  <button on="tap:carousel-with-preview.goToSlide(index=1)">
    <amp-img
      src="/static/inline-examples/images/image2.jpg"
      width="60"
      height="40"
      alt="lemons"
    ></amp-img>
  </button>
  <button on="tap:carousel-with-preview.goToSlide(index=2)">
    <amp-img
      src="/static/inline-examples/images/image3.jpg"
      width="60"
      height="40"
      alt="blueberries"
    ></amp-img>
  </button>
</div>

在 Playground 中打开此代码段

关于 `amp-carousel` 的辅助功能注意事项

自动播放，特别是无限循环的轮播图，可能会对用户造成非常大的干扰和困惑，特别是对于有认知障碍的用户。一般来说，我们建议避免使用自动播放的轮播图。虽然自动播放的轮播图会在用户与轮播图交互后停止，但也请考虑添加明确的“播放/暂停”控件。

默认情况下，当呈现 <amp-carousel> 时，它会通过程序识别为一个列表（在容器元素上使用 role="list"，在每个项目上使用 role="listitem"）。但是，对于 <amp-carousel type="slides">，目前未提供特定的 role。因此，当使用辅助技术的用户阅读/浏览页面并到达轮播图时，这将不明显。我们建议在 <amp-carousel> 中包含显式的 role="region" 和描述性的 aria-label（可以是通用的 aria-label="Carousel" 或更具描述性的标签，例如 aria-label="Latest news items"）。

目前，<amp-carousel type="slides"> 轮播图被声明为一个 ARIA 活动区域（使用 aria-live="polite"），这意味着每次显示新的幻灯片时，辅助技术（如屏幕阅读器）都会播报幻灯片的全部内容。由于轮播图的初始呈现方式，这也可能导致在加载页面时完整播报轮播图的内容。这也意味着包含 autoplay 轮播图的页面会在幻灯片自动前进时持续播报。目前，没有解决此问题的方法。

属性

type	指定轮播图项目的显示类型，可以是 `carousel`（默认）：显示所有幻灯片，并且可以水平滚动。此类型仅支持以下布局：`fixed`、`fixed-height` 和 `nodisplay`。 `slides`：一次显示一个幻灯片。此类型支持以下布局：`fill`、`fixed`、`fixed-height`、`flex-item`、`nodisplay` 和 `responsive`。
height（必需）	以像素为单位指定轮播图的高度。
controls（可选）	永久显示左箭头和右箭头，供用户在移动设备上浏览轮播图项目。默认情况下，导航箭头在移动设备上几秒钟后消失。箭头的可见性也可以通过样式来控制，并且可以使用媒体查询来仅在某些屏幕宽度下显示箭头。在桌面上，始终会显示箭头，除非只有一个子元素存在。
data-next-button-aria-label（可选）	为 `amp-carousel-button-next` 设置 aria-label。如果未提供值，则 aria-label 默认为“轮播图中的下一项”。
data-prev-button-aria-label（可选）	为 `amp-carousel-button-prev` 设置 aria-label。如果未提供值，则 aria-label 默认为“轮播图中的上一项”。
data-button-count-format（可选）	一个格式字符串，类似于 `(%s of %s)`，用作 `amp-carousel-button-next`/`amp-carousel-button-prev` 的 aria-label 的后缀。这会向使用屏幕阅读器的用户提供有关其在轮播图中的进度的信息。如果未提供值，则此默认值为“(%s of %s)”。
autoplay（可选）	无需用户交互即可定期前进到下一张幻灯片。如果用户手动更改幻灯片，则自动播放停止。如果存在且没有值默认情况下，以 5000 毫秒间隔（5 秒）前进一个幻灯片；可以通过 `delay` 属性覆盖此值。如果 `loop` 尚未存在，则将 `loop` 属性附加到 `amp-carousel`。需要至少 2 张幻灯片才能进行自动播放。仅适用于具有 `type=slides` 的轮播图。如果存在且有值如果 `loop` 尚未存在，则将 `loop` 属性附加到 `amp-carousel`。在完成所需的循环次数后，删除 `loop` 属性。
delay（可选）	指定启用 `autoplay` 时延迟前进到下一张幻灯片的持续时间（以毫秒为单位）。请注意，`delay` 允许的最小值是 1000 毫秒。`delay` 属性仅适用于具有 `type=slides` 的轮播图。
loop（可选）	允许用户前进到第一项或最后一项之外。必须至少有 3 张幻灯片才能进行循环。`loop` 属性仅适用于具有 `type=slides` 的轮播图。示例：显示一个带有控件、循环和延迟自动播放的幻灯片轮播图 <amp-carousel type="slides" width="450" height="300" controls loop autoplay delay="3000" data-next-button-aria-label="Go to next slide" data-previous-button-aria-label="Go to previous slide" role="region" aria-label="Looping carousel"> <amp-img src="/static/inline-examples/images/image1.jpg" width="450" height="300"></amp-img> <amp-img src="/static/inline-examples/images/image2.jpg" width="450" height="300"></amp-img> <amp-img src="/static/inline-examples/images/image3.jpg" width="450" height="300"></amp-img> </amp-carousel> 在 Playground 中打开此代码段
通用属性	此元素包含扩展到 AMP 组件的通用属性。

样式

您可以使用 amp-carousel 元素选择器自由设置其样式。
您可以使用 .amp-carousel-slide 类选择器来定位轮播图项目。
禁用时，amp-carousel 按钮的视觉状态会被隐藏。
默认情况下，.amp-carousel-button 使用内联 SVG 作为按钮的背景图像。您可以使用自己的 SVG 或图像来覆盖此内容，如下例所示。

示例：默认的 .amp-carousel-button 内联 SVG

.amp-carousel-button-prev {
  left: 16px;
  background-image: url('data:image/svg+xml;charset=utf-8,%3Csvg xmlns="http://www.w3.org/2000/svg" width="18" height="18" fill="%23fff"%3E%3Cpath d="M15 8.25H5.87l4.19-4.19L9 3 3 9l6 6 1.06-1.06-4.19-4.19H15v-1.5z"/%3E%3C/svg%3E');
}

示例：覆盖默认的 .amp-carousel-button 内联 SVG

.amp-carousel-button-prev {
  left: 5%;
  background-image: url('data:image/svg+xml;charset=utf-8,%3Csvg xmlns="http://www.w3.org/2000/svg" width="18" height="18" fill="%23fff"%3E%3Cpath d="M11.56 5.56L10.5 4.5 6 9l4.5 4.5 1.06-1.06L8.12 9z"  /%3E%3C/svg%3E');
}

请注意，SVG 内容需要对某些字符（包括 <、> 和 #）进行编码。可以使用 SVGO 或使用 encodeURIComponent 等工具来完成此操作。

幻灯片支持的布局

如上所述，amp-carousel 0.1 上的 type="slides" 指定支持以下布局：fill、fixed、fixed-height、flex-item、nodisplay 和 responsive。

发布者应该知道，尽管此模式显式支持 fixed 布局大小，但它还在其样式中采用了 display: flex;。换句话说，嵌套元素可以具有 layout=fixed 大小，但通过样式设置，它仅尊重高达 100% 的绝对宽度。解决此限制的一种方法是在任何固定布局的幻灯片上使用 flex-shrink: 0。

为了获得可访问且流畅的用户体验，通常在同时使用 type="slides" 时，最佳做法是该轮播图的所有子元素和轮播图本身都共享相同的尺寸比例以及相同的布局类型。

验证

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

需要更多帮助？

您已经阅读了本文档十几次，但它并没有真正涵盖您的所有问题？也许其他人也有同样的感觉：请在 Stack Overflow 上与他们联系。

前往 Stack Overflow

发现 Bug 或缺少功能？

AMP 项目强烈鼓励您的参与和贡献！我们希望您能成为我们开源社区的长期参与者，但我们也欢迎您针对自己特别关注的问题做出一次性贡献。

前往 GitHub

amp-carousel 0.2 0.1

描述