Overview

概覽

Tad Carousel 是一套輕量、無依賴的輪播（Carousel）元件，以無障礙設計為核心， 支援鍵盤操作、觸控拖曳、自動播放、響應式斷點，並遵循 WCAG 2.3 AAA 規範。

元件以 UMD 格式封裝，可在 CommonJS、AMD 或純瀏覽器環境直接使用，不需安裝任何框架或套件管理工具。

主要特色

• ✦ 零外部依賴，檔案體積極小
• ✦ 完整 WCAG 2.3 AAA 無障礙支援
• ✦ 觸控與滑鼠拖曳支援
• ✦ 響應式斷點設定
• ✦ 深色模式、高對比模式自動適應
• ✦ 減少動態效果（prefers-reduced-motion）

Quick Start

快速開始

步驟一：撰寫 HTML 結構

在容器元素內直接放置輪播項目，元件將自動包裝為正確的 DOM 結構。

HTML

<div id="myCarousel">
  <div><img src="slide1.jpg" alt="第一張投影片說明"></div>
  <div><img src="slide2.jpg" alt="第二張投影片說明"></div>
  <div><img src="slide3.jpg" alt="第三張投影片說明"></div>
</div>

步驟二：初始化元件

JavaScript

const carousel = new TadCarousel('#myCarousel', {
  items: 1,
  nav: true,
  dots: true
});

帶自動播放的基本範例

JavaScript

const carousel = new TadCarousel('#myCarousel', {
  items: 1,
  autoplay: true,        // 啟用自動播放
  autoplayTimeout: 4000, // 每 4 秒切換
  loop: true,             // 循環播放
  nav: true,
  dots: true
});

Responsive

響應式設定

透過 responsive 選項，可依視窗寬度（斷點）設定不同的顯示數量。 物件的 key 為最大寬度（px），value 為該斷點的設定覆蓋值。

JavaScript

new TadCarousel('#carousel', {
  items: 4,           // 桌機顯示 4 張
  responsive: {
    1024: { items: 3 },  // ≤ 1024px 顯示 3 張
    768:  { items: 2 },  // ≤ 768px  顯示 2 張
    480:  { items: 1 }   // ≤ 480px  顯示 1 張
  }
});

API

公開方法

使用範例

JavaScript

const carousel = new TadCarousel('#carousel');

// 跳至第 3 頁（索引 2）
carousel.goTo(2);

// 取得當前狀態
console.log(carousel.getCurrentIndex()); // 2
console.log(carousel.getPageCount());    // 投影片總數

// 銷毀（例如元件卸載時）
carousel.destroy();

Keyboard

鍵盤操作

Tad Carousel 完整支援鍵盤操作，符合 WCAG 2.1.1 鍵盤無障礙要求。

在輪播區域內

在分頁圓點（Tablist）中

Tab 焦點遊走順序（autoplay 啟用時）

① 暫停／播放按鈕為第一個焦點，符合 WCAG 2.4.3 由左至右、由上而下的焦點順序要求。

Bug Fix · WCAG 2.4.3

WCAG 2.4.3 焦點順序修正

指引 2.4：可導覽 — 成功準則 2.4.3 焦點順序（GN1240300E）要求： 互動元件的放置順序應按照內容的序列及關連性，鍵盤焦點遊走順序須符合由左至右、由上而下的邏輯順序。

問題描述

原始版本存在兩個不符合規範的問題：

修正方式

修正 1 — _setupA11y() 移除容器 tabindex

// ❌ 原始程式碼
if (!element.hasAttribute('tabindex')) {
    element.setAttribute('tabindex', '0');
}

// ✅ 修正後：移除容器 tabindex，焦點應由子元件接管
element.removeAttribute('tabindex');

修正 2 — _buildStructure() 暫停鈕優先插入 DOM，軌道次之，導航鍵最後

// ❌ 原始程式碼（autoplayToggle 最後建立）
trackContainer.appendChild(track);
element.appendChild(trackContainer);
if (options.nav)     this._buildNav();
if (options.dots)    this._buildDots();
if (options.autoplay) this._buildAutoplayToggle(); // ← 最後，焦點排末位

// ✅ 修正後：① autoplayToggle 最先 → ② trackContainer（投影片）→ ③ nav（上一張／下一張）→ ④ dots
if (options.autoplay) this._buildAutoplayToggle(); // ← ① 暫停／播放，焦點排首位
trackContainer.appendChild(track);
element.appendChild(trackContainer);                 // ← ② 投影片（可見項目設 tabindex="0"）
if (options.nav)     this._buildNav();              // ← ③ 上一張 → 下一張
if (options.dots)    this._buildDots();             // ← ④ 分頁圓點

修正 4 — _updateItemsState() 可見投影片加入 tabindex="0"

// ❌ 原始程式碼（投影片項目從未設 tabindex，Tab 鍵直接跳過投影片）
if (!isVisible) {
    item.setAttribute('inert', '');
} else {
    item.removeAttribute('inert');
}

// ✅ 修正後：可見投影片設 tabindex="0"，成為焦點順序中的 ② 投影片 停駐點
if (!isVisible) {
    item.setAttribute('inert', '');
    item.removeAttribute('tabindex');      // 隱藏項目不可聚焦
} else {
    item.removeAttribute('inert');
    item.setAttribute('tabindex', '0');   // 可見項目可聚焦
}

修正 3 — tad_carousel.css 視覺位置配合調整

/* ❌ 原始：按鈕位於右下角，與「由上而下」邏輯相矛盾 */
.tad-carousel__autoplay-toggle {
    bottom: 0.5rem;
    right: 0.5rem;
}

/* ✅ 修正：按鈕移至右上角，視覺位置與焦點順序一致 */
.tad-carousel__autoplay-toggle {
    top: 0.5rem;
    right: 0.5rem;
}

修正後的焦點順序

Changelog

更新紀錄