🔄 TadLoop

🎬 即時展示 Live Demo

以下是一個實際運作的範例，可使用右上角的暫停按鈕或下方按鈕控制：

⚡ 快速開始

1. 引入檔案

<link rel="stylesheet" href="tad_loop.css">
<script src="tad_loop.js"></script>

2. HTML 結構

<div id="my-marquee" class="tad-loop">
  <div class="item-wrap">
    <div class="item"><a href="#">項目 1</a></div>
    <div class="item"><a href="#">項目 2</a></div>
    <div class="item"><a href="#">項目 3</a></div>
    <div class="item"><a href="#">項目 4</a></div>
  </div>
</div>

3. 初始化（含 WCAG 2 AA 無障礙設定）

var marquee = new TadLoop('#my-marquee', {
  velocity: 2,
  forward: true,
  pauseOnHover: true,
  // WCAG 2 AA 無障礙設定
  ariaLabel: '促銷活動跑馬燈',
  ariaLabelPause: '暫停跑馬燈',
  ariaLabelPlay:  '播放跑馬燈',
  ariaLabelPrev:  '向左捲動',
  ariaLabelNext:  '向右捲動',
  controlPosition: 'top-right'   // 暫停鍵置於右上角
});

⚙️ 設定選項 Options

所有可用的設定參數一覽：

🛠 公開方法 API Methods

透過實例呼叫以下方法來控制跑馬燈行為：

使用範例

var marquee = new TadLoop('#my-marquee', { velocity: 3 });

// 暫停
marquee.pause(true);

// 恢復
marquee.resume(true);

// 切換
marquee.toggle();

// 加速
marquee.setVelocity(5);

// 改變方向
marquee.setDirection(false); // 改為向右

// 銷毀
marquee.destroy();

⌨️ 鍵盤操作

♿ 無障礙特性 Accessibility（WCAG 2 AA）

焦點順序（SC 2.4.3 Focus Order）

控制按鈕依 DOM 順序排列，Tab 鍵焦點路徑為： 暫停/播放 → 捲動項目 → 向左 → 向右， 符合上至下、左至右的閱讀邏輯，輔助科技可正確報讀每個控制項的名稱與狀態。

暫停機制（SC 2.2.2 Pause, Stop, Hide）

• ✅ 暫停/播放切換按鈕置於跑馬燈區塊最上方，使用者進入區塊前即可暫停
• ✅ 鍵盤焦點移入捲動項目時，動畫自動暫停，焦點離開後恢復
• ✅ 滑鼠移入時暫停（pauseOnHover: true）
• ✅ 自動偵測 prefers-reduced-motion 系統設定，停用動畫

名稱、角色、值（SC 4.1.2 Name, Role, Value）

• ✅ 容器具有 role="region"、aria-label、aria-live
• ✅ 切換按鈕使用單一按鈕搭配 aria-pressed（true=已暫停） 與動態 aria-label（描述「下一步動作」），螢幕閱讀器報讀清晰
• ✅ 向左／向右按鈕各有明確的 aria-label（可本地化）
• ✅ 複製項目標記為 aria-hidden="true"，複製項目內的連結設為 tabindex="-1"

焦點可見性（SC 2.4.7 Focus Visible）

• ✅ 所有按鈕具有高對比度 :focus-visible 輪廓（#005fcc，對比 7.6:1）
• ✅ 項目連結具有 :focus-visible 輪廓
• ✅ 支援 Windows 高對比模式（forced-colors: active）

色彩對比（SC 1.4.3 Contrast）

• ✅ 一般項目：深色文字 #1a1a1a 於 #d3d0d0 背景，對比約 7.3:1（通過 AA）
• ✅ 高亮項目：白色文字 #fff 於 #c0392b 背景，對比約 4.6:1（通過 AA）
• ✅ 按鈕圖示：#1a1a1a 於白色半透明背景，對比 16:1

🔄 從 jQuery grouploop 遷移

如果你原本使用 jQuery 版本的 grouploop，以下是遷移對照：

Before (jQuery)

$('.promo-carousel').grouploop({
  velocity: 2,
  forward: true,
  pauseOnHover: true
});

After (TadLoop)

var marquee = new TadLoop('.promo-carousel', {
  velocity: 2,
  forward: true,
  pauseOnHover: true,
  // 加入 WCAG 2 AA 無障礙標籤
  ariaLabel: '促銷活動跑馬燈',
  ariaLabelPause: '暫停跑馬燈',
  ariaLabelPlay:  '播放跑馬燈'
});

主要差異

🧪 進階用法

搭配 FontAwesome

<!-- 引入 FontAwesome -->
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.5.0/css/all.min.css">

<script>
var marquee = new TadLoop('#my-marquee', {
  useFontAwesome: true  // 使用 FA 圖示
});
</script>

自訂回呼函式

var marquee = new TadLoop('#my-marquee', {
  onComplete: function() {
    console.log('TadLoop 初始化完成！');
  },
  onPause: function() {
    console.log('動畫已暫停');
  },
  onResume: function() {
    console.log('動畫已恢復');
  }
});

多個實例

var marquee1 = new TadLoop('#marquee-top', {
  velocity: 1,
  forward: true,
  ariaLabel: '頂部促銷跑馬燈',
  ariaLabelPause: '暫停頂部跑馬燈',
  ariaLabelPlay:  '播放頂部跑馬燈'
});

var marquee2 = new TadLoop('#marquee-bottom', {
  velocity: 3,
  forward: false,
  controlPosition: 'top-left',
  ariaLabel: '底部公告跑馬燈',
  ariaLabelPause: '暫停底部跑馬燈',
  ariaLabelPlay:  '播放底部跑馬燈'
});

不自動播放（手動控制）

var marquee = new TadLoop('#my-marquee', {
  autoStart: false,
  showControls: true,
  ariaLabel: '促銷跑馬燈（未播放）'
});

// 在某個事件後啟動
document.getElementById('startBtn').addEventListener('click', function() {
  marquee.resume(true);
});

🌐 瀏覽器支援

核心技術需求：requestAnimationFrame、CSS transform、Object.assign（或 polyfill）。