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="Carousel" 或更具描述性的标签，例如 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 作为按钮的背景图像。您可以使用自己的 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

描述