SwCarousel

SwCarousel 是基於 transform: translateX 的自動輪播元件，用於 banner / 首圖等場景。首尾各克隆一張做無縫循環（切到克隆幀時無動畫跳回真實幀，視覺無跳變），內建 autoplay、觸控閾值翻頁、dots / 縮圖指示器。

items 制：傳 :items 資料 + #default="{ item, index }" 作用域插槽渲染每張（元件按 items 克隆，index 為真實邏輯索引）。

必須寫 #default 插槽：元件不知道怎麼渲染你的 item，傳了 :items 卻沒寫 #default 會渲染空白幀（dev 期 console 警告）。

自由橫排捲動用 SwRail：SwCarousel 是「一次一屏 + 自動輪播」；「一行 N 個靠捲動」用 SwRail。

基礎用法

<SwCarousel :items="banners" aria-label="首頁 banner">
  <template #default="{ item }">
    <SwLink :to="item.link"><SwImage :src="item.img" ratio="16/9" /></SwLink>
  </template>
</SwCarousel>

banner 連結（SwCarousel 不內建連結）

SwCarousel 本身不提供任何連結 / 文案 / 按鈕——每張 banner 的內容（圖片 / 標題 / 按鈕 / 跳轉位址）全部來自 item 資料，透過 #default="{ item, index }" 作用域插槽渲染。需要可點擊的 banner 時按下面兩種形態二選一：

• 純圖 banner（整張可點）：用 SwLink 包住整張 slide（見上方基礎用法）。
• 帶文案 + 按鈕的 banner：把 SwLink / SwButton 作為 CTA 放進 slide 內部，不要把整張再套 <a>（連結裡嵌套可互動元素是非法 HTML）。

<!-- 真實 banner：圖片 + 標題 + CTA 按鈕，連結來自 item.link -->
<SwCarousel :items="banners" aria-label="首頁 banner">
  <template #default="{ item }">
    <div class="banner">
      <SwImage :src="item.img" ratio="12/5" />
      <h3 class="title">{{ item.title }}</h3>
      <SwLink :to="item.link" class="cta">{{ item.cta }}</SwLink>
    </div>
  </template>
</SwCarousel>

autoplay 與暫停

預設開 autoplay（autoplayDelay 控制每張停留 ms，預設 4000——帶文案 banner 夠閱讀；純圖可傳 3000）。桌面 hover、鍵盤焦點落入、按下拖曳、頁面切到背景（visibilitychange）會自動暫停，離開 / 回到前景續播；命中系統「減少動態」（prefers-reduced-motion）時不自動播放。單圖或 :autoplay="false" 不開。手動切換（指示器 / 縮圖 / 鍵盤 / ref 方法）會重置自動輪換計時——剛選中的 slide 享受完整 autoplayDelay，不會被臨近的下一次 tick 立即換走。

<SwCarousel :items="banners" :autoplay-delay="5000" :pause-on-hover="true" />
<SwCarousel :items="banners" :autoplay="false" />  <!-- 關閉自動播放 -->

循環與單圖降級

• loop（預設 true）：無縫循環。:loop="false" 時到首 / 尾停住不繞。
• 單圖自動降級：items.length <= 1 時不渲克隆、不開 autoplay、不顯指示器。

觸控翻頁

行動端手指滑動超過 dragThreshold（佔容器寬比例，預設 0.15）即翻頁，否則回彈。

指示器（dots / 縮圖 / 自訂）

indicator 選 'dots'（預設）/ 'thumbnails' / 'none'；位置由 indicatorPlacement 統一控制（dots 與縮圖共用）：

dots 樣式

預設 dots 是白色圓點 + 投影（任意背景上都可見，不綁主色）；激活點變成變長條並帶動畫（橫排變長 / 豎排變高）。dots 還帶放大的點擊熱區（透明，不改視覺），方便觸控點擊。全部樣式由 CSS 變數定制：

<SwCarousel
  :items="banners"
  style="--sw-carousel-dot-active-color: var(--primary); --sw-carousel-dot-size: 0.625rem"
>
  <template #default="{ item }"><SwImage :src="item.img" ratio="16/9" /></template>
</SwCarousel>

縮圖導覽

indicator="thumbnails" + :thumbnails（圖源陣列，長度需與 items 一致）渲染縮圖條。激活縮圖用白色 box-shadow 描邊（非硬邊框，reflow-safe）；非激活項用 brightness 壓暗、hover 時回亮。縮圖較多時自動變成可橫向捲動的縮圖條，切換時把激活項自動捲進可視區（滑鼠滾輪也能捲動條帶）。

thumbnailTrigger 控制縮圖的切換觸發方式：'click'（預設，點擊切換）/ 'hover'（懸停即切換）。

thumbnailLabels 為每個縮圖外層按鈕提供完整可存取名稱，例如 :thumbnail-labels="movies.map(m => m.title)"。即使視覺片名省略，或 #thumbnail 自訂內容，按鈕仍使用完整標籤。標籤會去除首尾空白；未傳、空白或缺少的項目回退本地化序號。請與 thumbnails 保持等長同序；長度不齊時開發環境警告，已有標籤照常使用、缺項按序號回退。aria-current、鍵盤與觸控行為不變。

縮圖預設渲染為裸 <img>（不經 SwImage、無解密能力）。要自訂單張縮圖的渲染——最典型是 .bnc 加密圖（裸 img 必裂）——用 #thumbnail 作用域插槽（{ thumb, index, active }）塞 SwImage，不傳插槽時行為與舊版完全一致：

<SwCarousel :items="movies" indicator="thumbnails" :thumbnails="movies.map((m) => m.cover)">
  <template #default="{ item }"><SwImage :src="item.cover" alt="" fill /></template>
  <!-- 兜底裸 img 不解密；SwImage fill 填滿縮圖按鈕盒，.bnc 自動解密 -->
  <template #thumbnail="{ thumb }"><SwImage :src="thumb" alt="" fill /></template>
</SwCarousel>

<!-- 縮圖導覽（右側豎排，懸停切換） -->
<SwCarousel
  :items="list"
  indicator="thumbnails"
  :thumbnails="list.map(x => x.thumb)"
  indicator-placement="right"
  thumbnail-trigger="hover"
>
  <template #default="{ item }"><SwImage :src="item.img" ratio="16/9" /></template>
</SwCarousel>

自訂指示器

要完全自訂指示器（進度條 / 數字 / 帶標題縮圖等）用 #indicator 插槽：

<SwCarousel :items="list">
  <template #default="{ item }"><img :src="item.img"></template>
  <template #indicator="{ current, count, goTo }">
    <div class="my-pager">{{ current + 1 }} / {{ count }}</div>
  </template>
</SwCarousel>

CSS 變數

指示器（dots / 縮圖）樣式全部走 CSS 變數定制，無需覆寫內部選擇器：

命令式控制

<script setup>
const carouselRef = ref()
</script>

<template>
  <SwCarousel ref="carouselRef" :items="list"><template #default="{ item }">…</template></SwCarousel>
  <button @click="carouselRef.next()">下一張</button>
</template>

一屏多卡（slidesPerView）

推薦位 / 創作者位「一行 N 卡自動輪播」形態——slidesPerView 定一屏張數（支援語義斷點響應式）、gap 定卡間距；步進恆為 1 張，loop / autoplay / 拖拽 / dots 照常工作。與 SwRail（自由橫滾、無 loop/autoplay）互補。

Props

逐張曝光埋點（:track）

輪播的曝光語意與 SwLink 的「進視口一次」不同：loop / autoplay 下非當前 slide 被 transform 挪出可視區，slot 內 SwLink 的 IntersectionObserver 判定不可靠——「輪到哪張」只有輪播引擎自己知道，所以由元件級 :track 承擔：

<SwCarousel :items="banners" :track="{
  exposure: (item, index) => ({
    event: 'appPageitemExposure',
    payload: {
      item_id: (item as Banner).id, item_type: 'banner', item_name: (item as Banner).title,
      parent_item_id: '', position: index + 1, page_key: 'home', page_name: '首頁',
    },
  }),
}">
  <template #default="{ item }">
    <SwLink :to="item.link"><SwImage :src="item.img" ratio="16/9" /></SwLink>
  </template>
</SwCarousel>

• 時機：每張輪到且容器進過視口（IO ≥50% 一次性）時上報；實例生命週期內每張只報一次（autoplay 多圈不重複刷曝光）；items 引用變化（換內容）後重新計。
• exposure(item, index) 由業務把輪播 item 映射為埋點指令，回傳 undefined = 該張不上報。
• 點擊埋點不內建——slide 內容是業務 slot，點擊語意歸內容上的 SwLink :track.click（見上方範例）。
• 上報走 useTracker（tracker gate 關閉時靜默 no-op）。

Events

Slots

暴露方法（defineExpose）

注意事項

• items 制 + 必寫 #default：每張內容走 #default="{ item, index }" 作用域插槽；index 是真實邏輯索引（克隆幀也映射回真實索引）。傳了 :items 卻沒寫 #default 會渲染空白幀，dev 期 console 警告。
• banner 連結來自 item 資料：元件不內建連結；純圖 banner 用 SwLink 包整張，帶按鈕的 banner 把 CTA（SwLink / SwButton）放進 slide 內部，別把整張再套 <a>。
• 自動輪播必靜音媒體：若 slide 內是影片，autoplay 場景遵循瀏覽器策略（靜音）。
• 橫排捲動用 SwRail：SwCarousel 是一次一屏的輪播，不是自由橫排。

active 僅目前真實項為 true，首尾複製項一律 false。autoplay 支援響應式切換；影片準備/播放期間設為 false，失敗回退圖片後設為 true，恢復時重新計完整間隔。參見 SwVideoBackground。