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="Carousel" 或更具描述性的标签，例如 aria-label="Latest news items"）。

目前，<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 验证器规范中的 amp-carousel 规则。