重要提示：此文档不适用于您当前选择的格式故事！

amp-carousel

描述

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

必需的脚本

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

支持的布局

填充固定固定高度弹性项目固有不显示响应式

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

行为

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” 的轮播前进到索引为 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="轮播"，也可以是更具描述性的标签，例如 aria-label="最新新闻项目"）。

目前，<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 作为按钮的 background-image。您可以像下面的示例中那样，使用您自己的 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

发现错误或缺少功能？

AMP 项目强烈鼓励您的参与和贡献！我们希望您成为我们开源社区的持续参与者，但也欢迎您针对您特别感兴趣的问题进行一次性贡献。

转到 GitHub

amp-carousel 0.2 0.1

描述