amp-carousel

說明

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

必要指令碼

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

支援的版面配置

fill fixed fixed-height flex-item intrinsic nodisplay responsive

範例

AMP 電子商務入門產品瀏覽頁面產品頁面 amp-carousel amp-lightbox-gallery 使用 amp-carousel 的圖片庫使用 amp-carousel 的影片輪播新聞報導食譜如何支援尺寸未知的圖片捲軸繫結效果基礎知識房屋 amp-analytics

通用的輪播，用於沿水平軸顯示多個相似的內容片段；旨在實現高度彈性和高效能。

行為

每個 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="輪播" 或更具描述性的標籤，例如 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 (data-下一個按鈕 aria 標籤) (選用)	設定 `amp-carousel-button-next` 的 aria-label。如果未提供值，aria-label 預設為「輪播中的下一個項目」。
data-prev-button-aria-label (data-上一個按鈕 aria 標籤) (選用)	設定 `amp-carousel-button-prev` 的 aria-label。如果未提供值，aria-label 預設為「輪播中的上一個項目」。
data-button-count-format (data-按鈕計數格式) (選用)	格式字串，看起來像 `(%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 中開啟此程式碼片段
common attributes (通用屬性)	此元素包含擴充到 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

說明