TadNav v1.5.0

📁 一、檔案結構

tadnav/
├── tadnav.css      ← 套件樣式（CSS 變數主題系統）
├── tadnav.js       ← 套件核心邏輯
└── index.html      ← 本說明文件 & 互動展示頁

套件本身僅需 tadnav.css 與 tadnav.js 兩個檔案。 Font Awesome 為選用依賴，僅用於箭頭與圖示顯示。

🚀 二、快速開始

步驟 1：引入檔案

<!-- Font Awesome（選用，用於箭頭圖示）-->
<link rel="stylesheet"
      href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.5.1/css/all.min.css">

<!-- TadNav 樣式 -->
<link rel="stylesheet" href="tadnav.css">

<!-- TadNav 核心（放在 </body> 前）-->
<script src="tadnav.js"></script>

步驟 2：建立 HTML 結構

<nav class="tadnav-wrapper" aria-label="導覽工具列">
  <div class="tadnav-inner">

    <!-- 品牌名稱（選用）-->
    <div class="tadnav-brand">網站名稱</div>

    <!-- 漢堡按鈕（手機版）-->
    <button class="tadnav-toggle"
            aria-expanded="false"
            aria-controls="my-menu"
            aria-label="切換選單顯示狀態">
      <span class="bar" aria-hidden="true"></span>
      <span class="bar" aria-hidden="true"></span>
      <span class="bar" aria-hidden="true"></span>
    </button>

    <!-- 主選單 -->
    <ul id="my-menu" class="tadnav-menu" role="menubar" aria-label="主選單">

      <!-- 一般連結 -->
      <li role="none">
        <a href="/home" role="menuitem">首頁</a>
      </li>

      <!-- 有子選單的項目 -->
      <li role="none">
        <button class="tadnav-submenu-toggle" role="menuitem"
                aria-haspopup="true" aria-expanded="false">
          服務 <span class="tadnav-arrow" aria-hidden="true"></span>
        </button>
        <ul class="tadnav-submenu" role="menu" aria-label="服務">
          <li role="none"><a href="/svc1" role="menuitem">服務一</a></li>
          <li role="none"><a href="/svc2" role="menuitem">服務二</a></li>
        </ul>
      </li>

      <!-- Spacer：其後項目靠右 -->
      <li class="tadnav-spacer" role="none" aria-hidden="true"></li>

      <!-- 靠右項目（JS 自動標記，無需手寫 style）-->
      <li role="none">
        <a href="/login" role="menuitem">登入</a>
      </li>

    </ul>
  </div>
</nav>

步驟 3：初始化

document.addEventListener('DOMContentLoaded', function () {

  var nav = new TadNav('#my-menu', {

    // 展開方式
    trigger:    'hover',   // 'hover'（預設）| 'click'
    hoverClose: true,      // hover 模式下滑走是否收合

    // 主題色彩（全部選用，未設定則使用 CSS 預設值）
    theme: {
      navBg:           '#2c3e50',
      itemColor:       '#ffffff',
      itemHoverBg:     'rgba(255,255,255,0.15)',
      itemFontSize:    '0.95rem',
      subBg:           '#ffffff',
      subItemColor:    '#2c3e50',
      subItemHoverBg:  '#f0f4f8',
      subItemFontSize: '0.9rem',
      subShadow:       '0 4px 16px rgba(0,0,0,0.12)',
      innerMaxWidth:   '1200px',
    }

  });

});

🏗️ 三、HTML 結構規則

TadNav 依賴特定的 class 與 ARIA 屬性組合，請嚴格遵守以下規則：

📌 四、Spacer 自動靠右機制

在頂層 <ul> 中放置一個 .tadnav-spacer， TadNav 初始化時會自動掃描並將其後所有 <li> 標記 is-right， 子選單自動靠右展開。完全不需手寫任何 style 屬性。

運作原理

<!-- spacer 之前：靠左展開（預設）-->
<li role="none">...</li>
<li role="none">...</li>

<!-- ★ Spacer -->
<li class="tadnav-spacer" role="none" aria-hidden="true"></li>

<!-- spacer 之後：JS 自動加上 is-right，子選單靠右展開 -->
<li role="none">...</li>   <!-- → <li class="is-right"> -->

巢狀子選單方向

• 靠左項目的巢狀子選單：向右展開（left: 100%）
• 靠右項目（is-right）的巢狀子選單：向左展開（right: 100%），避免超出視窗

⚙️ 五、完整 API 參數

var nav = new TadNav('#my-menu', {

  // ── 展開觸發 ──────────────────────────────
  trigger:             'hover',   // 'hover'（預設）| 'click'
  hoverClose:          true,      // hover 模式：滑走是否收合（預設 true）
  hoverDelay:          200,       // 滑入後延遲展開 ms
  hideDelay:           300,       // 滑出後延遲收合 ms（hoverClose:true 時有效）

  // ── 響應式 ────────────────────────────────
  breakpoint:          768,       // 切換漢堡選單的視窗寬度斷點 px

  // ── 行為 ──────────────────────────────────
  collisionDetection:  true,      // 子選單超出視窗時自動翻轉
  closeOnOutsideClick: true,      // 點擊外部關閉
  closeOnEsc:          true,      // Esc 鍵關閉

  // ── 主題色彩（見第六節）──────────────────
  theme: { ... },

  // ── 事件回呼 ──────────────────────────────
  onInit:             null,       // (instance) => {}
  onOpen:             null,       // (submenu, triggerEl) => {}
  onClose:            null,       // (submenu, triggerEl) => {}
  onBreakpointChange: null,       // (isMobile) => {}
  onDestroy:          null,       // () => {}

});

🎨 六、主題色彩系統

TadNav 使用 CSS 自訂屬性（Custom Properties）管理所有顏色與尺寸。 tadnav.css 的 :root 定義預設值； JS 初始化時若傳入 theme 物件，會將對應值寫入 .tadnav-wrapper 的 inline style， 覆寫預設值，支援同頁多個導覽列各自獨立主題。

theme 參數完整列表

📐 版面

🟦 導覽列

🔤 頂層項目

📋 子選單面板

🔤 子選單項目

📱 漢堡按鈕 & 手機版

動態更換主題

// 部分更新（合併）
nav.setTheme({
  navBg:      '#2c3e50',
  itemColor:  '#ecf0f1',
});

// 完全取代（先清除所有舊設定）
nav.setTheme({
  navBg:           '#ffffff',
  itemColor:       '#333333',
  itemHoverBg:     '#f0f0f0',
  itemHoverColor:  '#000000',
}, false);

// 重設回 CSS 預設值
nav.resetTheme();

// 取得目前主題
var current = nav.getTheme();
console.log(current);

🖌️ 七、主題互動展示

以下控制項可即時調整上方導覽列的外觀，所有變更都透過 nav.setTheme() 套用。

🖱️ 八、trigger 模式

控制子選單的展開觸發方式，可在初始化時設定，也可執行期間動態切換。

// 初始化時設定
var nav = new TadNav('#my-menu', { trigger: 'click' });

// 執行期間動態切換
nav.setTrigger('click');
nav.setTrigger('hover');

🔒 九、hoverClose 控制

hoverClose 控制 hover 模式下，滑鼠離開後是否自動收合子選單。 在 trigger: 'click' 模式下此參數無作用。

// 滑入展開，滑走不收合
var nav = new TadNav('#my-menu', {
  trigger:    'hover',
  hoverClose: false
});

// 執行期間動態切換
nav.setHoverClose(false);  // 關閉自動收合
nav.setHoverClose(true);   // 恢復自動收合

🔧 十、公開方法