簡介

TadMarquee 是一套純 JavaScript 跑馬燈套件，無需任何外部依賴，支援四方向捲動、無縫循環播放，並完整符合 WCAG AAA 無障礙標準。

快速開始

引入檔案

<!-- CSS -->
<link rel="stylesheet" href="tad_marquee.css">
<!-- JS -->
<script src="tad_marquee.js"></script>

HTML 容器

<div id="my-marquee" style="width:100%; height:44px;"></div>

初始化

const marquee = new TadMarquee('my-marquee', {
direction: 'left',
speed: 60,
items: [
  { type: 'text', content: '第一則公告' },
  { type: 'text', content: '第二則公告' },
  { type: 'text', content: '第三則公告' }
]
});

即時展示

基本選項

項目格式

文字

{ type: 'text', content: '公告內容',
style: 'color:red; font-weight:bold', // 可選
className: 'my-class' }             // 可選

圖片

{ type: 'image', content: 'https://example.com/img.png',
alt: '圖片說明', text: '附加文字' }

HTML

{ type: 'html', content: '<strong>重要</strong> 公告' }

含連結（任何類型皆可加）

{ type: 'text', content: '點我前往',
link: 'https://example.com',
target: '_blank',
rel: 'noopener noreferrer',
ariaLabel: '前往範例網站（另開新視窗）' }

樣式選項

// CSS 字串格式
itemStyle: 'color:#fff; font-size:15px; padding:0 8px'

// JS 物件格式
itemStyle: { color: '#fff', fontSize: '15px', padding: '0 8px' }

無障礙選項

響應式選項

responsiveBreakpoints: {
mobile:  480,
tablet:  768,
desktop: 1024
}

暫停按鈕選項

位置設定

角落模式（浮動圓形按鈕）

按鈕以 position: absolute 疊加在跑馬燈內部四個角落，不影響容器尺寸。

並排模式（input-group 矩形按鈕）

在容器外自動插入 .tad-marquee-root flex 外層，按鈕與跑馬燈並排，高度自動撐滿。

圖示切換邏輯

API：播放控制

所有方法皆回傳 this，支援鏈式呼叫。

marquee.start()    // 開始播放
marquee.stop()     // 停止播放並重置狀態
marquee.pause()    // 暫停（保持目前位置）
marquee.resume()   // 從暫停處繼續

API：內容更新

// 更換所有項目
marquee.updateItems([
{ type: 'text', content: '新公告一' },
{ type: 'text', content: '新公告二' }
]);

// 修改捲動速度
marquee.setSpeed(80);

// 修改捲動方向（會重建 DOM 結構）
marquee.changeDirection('up');

API：樣式更新

// 合併更新（預設）
marquee.setItemStyle('color:red; font-size:18px');
marquee.setItemStyle({ color: 'red' });

// 完全取代
marquee.setItemStyle({ color: 'blue' }, false);

// 更換 CSS 類別
marquee.setItemClassName('new-class', 'old-class');

API：查詢狀態

// 取得所有設定
const opts = marquee.getOptions();

// 取得執行狀態
const status = marquee.getStatus();
// 回傳：{
//   isRunning, isPaused, isPausedByUser,
//   direction, speed, itemCount, isSingleItem,
//   prefersReducedMotion, currentBreakpoint,
//   loopSize, inlineMode
// }

// 銷毀並還原 DOM
marquee.destroy();

回呼函式

new TadMarquee('my-marquee', {
onStart:            () => console.log('開始播放'),
onStop:             () => console.log('停止播放'),
onPause:            () => console.log('已暫停'),
onResume:           () => console.log('已繼續'),
onDirectionChange:  (dir) => console.log('方向：', dir),
onBreakpointChange: (bp)  => console.log('斷點：', bp)
});

鍵盤操作

無障礙設計說明

螢幕閱讀器行為

• 複本項目（無縫循環用）統一設定 aria-hidden="true" 及 tabindex="-1"
• 鍵盤導航僅能聚焦原始組的項目，不會重複播報
• 操作（暫停、繼續、方向變更）透過 role="status" 的隱藏元素即時播報

DOM 結構說明

角落模式

並排模式（left / right）

完整範例

範例一：水平左捲 + 右側暫停按鈕

<div id="marquee-h" style="height:44px; background:#1a1a2e;"></div>
<script>
new TadMarquee('marquee-h', {
direction: 'left',
speed: 60,
pauseButtonPosition: 'right',
itemStyle: 'color:#fff; font-size:15px; padding:0 8px',
items: [
  { type: 'text', content: '📢 系統將於今晚 23:00 進行維護' },
  { type: 'text', content: '🎉 新功能上線：支援深色模式' },
  { type: 'text', content: '📌 請更新您的密碼以確保帳號安全' },
  { type: 'text', content: '🔔 活動報名截止日期：2026/03/31' },
  { type: 'text', content: '✅ 服務恢復正常，感謝您的耐心等候' }
]
});
</script>

範例二：垂直向上捲 + 左側暫停按鈕

<div id="marquee-v" style="height:120px; background:#0f3460;"></div>
<script>
new TadMarquee('marquee-v', {
direction: 'up',
speed: 40,
gap: 16,
pauseButtonPosition: 'left',
itemStyle: { color: '#e0e0e0', fontSize: '14px', padding: '6px 12px' },
items: [
  { type: 'text', content: '第一則：超出容器寬度時會自動換行顯示' },
  { type: 'text', content: '第二則：系統更新通知' },
  { type: 'text', content: '第三則：活動資訊' },
  { type: 'text', content: '第四則：重要提醒事項' },
  { type: 'text', content: '第五則：聯絡客服請撥 0800-000-000' }
]
});
</script>

範例三：含連結 + 角落暫停按鈕 + 回呼

new TadMarquee('marquee-link', {
direction: 'left',
pauseButtonPosition: 'bottom-right',
pauseButtonLabel: { pause: 'Pause', resume: 'Play' },
items: [
  { type: 'text', content: '🔗 查看最新公告',
    link: 'https://example.com',
    ariaLabel: '查看最新公告（另開新視窗）' },
  { type: 'html',
    content: '<span style="color:#ff6b6b">⚠️ 緊急通知</span>：請立即更新系統' }
],
onPause:  () => console.log('使用者暫停'),
onResume: () => console.log('使用者繼續')
});

範例四：動態更新內容

const marquee = new TadMarquee('my-marquee', {
direction: 'left',
items: [{ type: 'text', content: '初始內容' }]
});

// 3 秒後更換內容
setTimeout(() => {
marquee.updateItems([
  { type: 'text', content: '更新後的第一則' },
  { type: 'text', content: '更新後的第二則' }
]);
}, 3000);

marquee.setSpeed(100);
console.log(marquee.getStatus());

版本異動記錄