amp-carousel

0.2 0.1

<script async custom-element="amp-carousel" src="https://cdn.ampproject.org/v0/amp-carousel-0.2.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>

与 <amp-carousel> 0.1 的区别

• autoplay 允许用于 type="carousel"
• loop 允许用于 type="carousel"

迁移说明

• 将所需的脚本从 amp-carousel-0.1 更新为 amp-carousel-0.2。
• 确保用于定位下一个/上一个箭头的任何 CSS 仍然有效。有关箭头定位的更多信息，请参阅样式。
• 确保用于设置轮播样式的任何 CSS 仍然有效。<amp-carousel> 0.2 的内部 DOM 结构与 0.1 不同，会影响以 amp-carousel > div 等内部元素为目标的 CSS 选择器。任何使用 .amp-class-name 格式的选择器都应该仍然有效。
• 注意：对 amp-carousel-0.1 的支持是有限的，并且计划在未来弃用。

前进到特定幻灯片

将元素上 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>

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 (默认值)：所有幻灯片都显示并且可以水平滚动。每个幻灯片都可以使用 CSS 指定不同的宽度。
• slides：一次显示一个幻灯片，每个幻灯片在用户滑动时都会卡入到位。

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 属性覆盖。
• 自动播放需要至少 2 张幻灯片。

如果存在且有值

• 在完成所需的循环次数后停止自动播放。

delay (可选)

指定启用 autoplay 时延迟前进到下一张幻灯片的持续时间（以毫秒为单位）。请注意，延迟允许的最小值是 1000 毫秒。

loop (可选)

允许用户前进到第一个项目之前或最后一个项目之后。循环必须至少有 3 张幻灯片。

以下示例显示了一个带有控件、循环和延迟自动播放的幻灯片轮播。

<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>

slide (可选)

指定首次渲染轮播时应显示的索引。可以使用 amp-bind 更新此索引以更改显示的索引。

通用属性

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

操作

goToSlide(index=INTEGER)

将轮播前进到指定的幻灯片索引。

toggleAutoplay(toggleOn=true|false)

切换轮播的自动播放状态。toggleOn 是可选的。

活动

slideChange

在轮播的当前幻灯片更改时触发。

// Slide number.
Event.index

样式

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

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

.amp-carousel-button-prev {
  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 {
  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 来完成。

• 您可以使用 align-self 和/或相对定位来定位轮播按钮。请注意，轮播箭头在 RTL 中会自动翻转，因此您不应更改它们的 flex 顺序。

.amp-carousel-button-prev {
  position: relative;
  bottom: 20px;
  align-self: flex-end;
}

验证

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