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 电子商务入门产品浏览页面产品页面 amp-carousel amp-lightbox-gallery 使用 amp-carousel 的图像画廊使用 amp-carousel 的视频轮播新闻文章食谱如何支持具有未知尺寸的图像滚动绑定效果的基础房屋 amp-analytics

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

行为

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) 将在用户点击或单击时，将具有 "carousel-id" 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="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

发现错误或缺少功能？

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

前往 GitHub

amp-carousel 0.2 0.1

描述