AMP

Important: this documentation is not applicable to your currently selected format stories!

amp-carousel

Description

沿着一条横轴显示多个相似的内容片段。

 

Required Scripts

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

用于沿着一条横轴显示多个相似的内容片段的通用轮播界面;具有高度灵活性和高性能。

必需的脚本 <script async custom-element="amp-carousel" src="https://cdn.ampproject.org/v0/amp-carousel-0.1.js"></script>
支持的布局
  • 轮播界面:fixed、fixed-height 和 nodisplay。
  • 幻灯片:fill、fixed、fixed-height、flex-item、nodisplay 和 responsive。
示例 AMP By Example 的:

行为

每个 amp-carousel 组件的直接子级在轮播界面中均视为一个项。每个节点还可能包含任意 HTML 子级。

轮播界面包含任意数量的项,以及用于前往或返回单个项的可选导航箭头。

如果用户滑动、使用箭头键或点击可选导航箭头,则轮播界面会在两个项之间前进。

<amp-carousel width="450"
  height="300">
  <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 的轮播界面前往 index=N 位置的幻灯片(第一张幻灯片的位置为 index=0,第二张幻灯片的位置为 index=1,以此类推)。

在以下示例中,我们提供了一个包含三张图片的轮播界面,轮播界面下方是预览按钮。当用户点击其中一个按钮时,系统会显示相应的轮播项。

<amp-carousel id="carousel-with-preview"
    width="450"
    height="300"
    layout="responsive"
    type="slides">
    <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 中打开此代码段

属性

type 指定轮播项的显示类型,可以是如下类型:
  • carousel(默认):显示所有幻灯片,并且可以水平滚动。此类型仅支持以下布局:fixed, fixed-heightnodisplay
  • slides:每次显示一张幻灯片。此类型支持以下布局:fill, fixed, fixed-height, flex-item, nodisplay 以及 responsive
height(必需) 指定轮播界面的高度(以像素为单位)。
controls(可选) 永久显示左箭头和右箭头,以便用户在移动设备上浏览轮播项。默认情况下,移动设备上的导航箭头会在几秒种后消失。箭头的可见性还可以通过样式设置来控制,媒体查询只能用于在特定宽度的屏幕上显示箭头。在桌面设备上,除非只存在一个子级,否则将始终显示箭头。
data-next-button-aria-label(可选) 设置 amp-carousel-button-next 的 aria-label。如果未给出值,则 aria-label 默认为 'Next item in carousel'。
data-prev-button-aria-label(可选) 设置 amp-carousel-button-prev 的 aria-label。如果未给出值,则 aria-label 默认为 'Previous item in carousel'。
data-button-count-format(可选) 类似于 (%s of %s) 的格式字符串,用作 amp-carousel-button-next/amp-carousel-button-prev 的 aria-label 的后缀。该属性向使用屏幕阅读器的用户提供关于他们在轮播界面上的进度的信息。如果未给出值,则此属性默认为 '(%s of %s)'。
autoplay(可选) 从当前幻灯片前往下一张幻灯片,无需用户互动。
如果有该属性,但没有值:
  • 默认情况下,将以 5000 毫秒(5 秒)的间隔播放幻灯片;这可被 delay 属性替换。
  • amp-carousel 附加 loop 属性(如果该属性尚不存在)。
  • 至少需要两张幻灯片才能自动播放。
  • 仅适用于具有 type=slides 属性的轮播界面。
如果有该属性,且有值:
  • amp-carousel 附加 loop 属性(如果该属性尚不存在)。
  • 在完成必要的循环次数之后移除 loop 属性。
delay(可选) 指定时长(以毫秒为单位),以便在启用 autoplay 后延迟前往下一张幻灯片。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">
  <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,<svg xmlns="http://www.w3.org/2000/svg" width="18" height="18" viewBox="0 0 18 18"><path d="M15 8.25H5.87l4.19-4.19L9 3 3 9l6 6 1.06-1.06-4.19-4.19H15v-1.5z" fill="#fff" /></svg>');
}

示例:替换默认 .amp-carousel-button 内嵌 SVG

.amp-carousel-button-prev {
  left: 5%;
  background-image: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" width="18" height="18" viewBox="0 0 18 18"><path d="M11.56 5.56L10.5 4.5 6 9l4.5 4.5 1.06-1.06L8.12 9z" fill="#fff" /></svg>');
}

验证

请参阅 AMP 验证工具规范中的 amp-carousel 规则

需要更多帮助?

您已多次阅读本文档,但它仍未能涵盖您的所有问题?也许其他人也这么觉得:在 Stack Overflow 上与他们联系。

前往 Stack Overflow
发现错误或缺少功能?

AMP 项目强烈鼓励您参与并做出贡献!我们希望您能成为我们开放源代码社区的持续参与者,但我们也欢迎您对所热衷问题做出一次性贡献。

前往 GitHub