AMP
EN
Deutsch Français العربية Español Italiano Indonesia 日本語 한국어 Português Русский Türkçe 中文 Polski Tiếng việt

amp-carousel

說明

沿著水平軸顯示多個相似的內容片段。

 

必要指令碼

<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>
在 Playground 中開啟此程式碼片段

與 <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>
在 Playground 中開啟此程式碼片段

自動播放，尤其是無限循環播放的輪播，可能會讓使用者非常分心和困惑，尤其是對於有認知障礙的使用者而言。一般而言，我們建議避免使用自動播放輪播。雖然自動播放輪播會在使用者與輪播互動後停止，但請考慮新增明確的「播放/暫停」控制項。

預設情況下，<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 (下一個按鈕 aria 標籤資料) (選填)

設定 amp-carousel-button-next 的 aria 標籤。如果未提供值，則 aria 標籤預設為「輪播中的下一個項目」。

data-prev-button-aria-label (上一個按鈕 aria 標籤資料) (選填)

設定 amp-carousel-button-prev 的 aria 標籤。如果未提供值，則 aria 標籤預設為「輪播中的上一個項目」。

data-button-count-format (按鈕計數格式資料) (選填)

格式字串，看起來像 (%s of %s)，用作 amp-carousel-button-next/amp-carousel-button-prev 的 aria 標籤的後綴。這向使用螢幕閱讀器的使用者提供關於他們在輪播中進度的資訊。如果未提供值，則預設為 (%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>
在 Playground 中開啟此程式碼片段

slide (投影片) (選填)

指定首次呈現輪播時應顯示哪個索引。可以使用 amp-bind 更新此設定，以變更顯示的索引。

通用屬性

此元素包含擴充到 AMP 元件的通用屬性。

動作

goToSlide(index=INTEGER) (前往投影片 (索引=整數))

將輪播前進到指定的投影片索引。

toggleAutoplay(toggleOn=true|false) (切換自動播放 (開啟切換=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 中自動翻轉，因此您不應變更其彈性順序。
.amp-carousel-button-prev {
  position: relative;
  bottom: 20px;
  align-self: flex-end;
}

驗證

請參閱 AMP 驗證器規格中的 amp-carousel 規則。

需要更多協助嗎？

您已經讀過這份文件十幾次，但它仍然沒有涵蓋您的所有問題？也許其他人也有相同的感受：在 Stack Overflow 上與他們交流。

前往 Stack Overflow
發現錯誤或缺少功能？

AMP 專案強烈鼓勵您的參與和貢獻！我們希望您能成為我們開放原始碼社群的長期參與者，但我們也歡迎您針對您特別熱衷的問題做出一次性貢獻。

前往 GitHub