GX-Breadcrumb

Angular 麵包屑導航組件，支援自動路由生成和手動配置兩種模式。

🎉 v2.0 重大更新：全新組合式設計，參考 @sanring/gx-table 的架構，提供更高的靈活性和可組合性！

✨ 特性

• ✅ 組合式設計：可自由組合 Container、List、Item 組件（v2.0 新增）
• ✅ 三種使用模式：自動/手動/自定義組合
• ✅ Signal API：完整的 Angular Signal 支援（v2.0）
• ✅ 靈活的圖標支援：Lucide 圖標（可選）或文字/Emoji 圖標
• ✅ 主題系統：內建 default、glass、minimal、colorful 等主題
• ✅ 響應式設計：支援不同螢幕尺寸
• ✅ 完整的樣式自定義：CSS 變數支援
• ✅ 無障礙支援：符合 ARIA 標準
• ✅ TypeScript：完整的類型定義
• ✅ 向後兼容：保留舊版 API（使用 gx-breadcrumb-legacy）

📦 安裝

npm install @sanring/gx-breadcrumb

可選依賴

如果你想使用 Lucide 圖標：

npm install lucide-angular

注意：lucide-angular 是可選的。你可以使用文字或 Emoji 圖標而無需安裝它。

🎯 使用方式

🆕 方式 1：組合式 API（推薦 - v2.0）

完全自由組合，類似 @sanring/gx-table 的設計：

import { Component } from '@angular/core';
import {
  GxBreadcrumbContainer,
  GxBreadcrumbList,
  GxBreadcrumbItemV2
} from '@sanring/gx-breadcrumb';

@Component({
  selector: 'app-example',
  standalone: true,
  imports: [GxBreadcrumbContainer, GxBreadcrumbList, GxBreadcrumbItemV2],
  template: `
    <gx-breadcrumb-container theme="default" variant="modern">
      <gx-breadcrumb-list>
        <gx-breadcrumb-item-v2
          label="首頁"
          link="/"
          icon="🏠"
          [showIcon]="true"
        />
        <gx-breadcrumb-item-v2
          label="產品"
          link="/products"
          icon="📦"
          [showIcon]="true"
        />
        <gx-breadcrumb-item-v2
          label="詳情"
          [active]="true"
          icon="📄"
          [showIcon]="true"
          [showSeparator]="false"
        />
      </gx-breadcrumb-list>
    </gx-breadcrumb-container>
  `
})
export class ExampleComponent {}

優點：

• ✅ 完全控制每個項目
• ✅ 可以在 Item 之間插入自定義內容
• ✅ 每個組件都可以獨立使用
• ✅ 類似 gx-table 的設計，學習曲線低

方式 2：包裝組件 - 自動模式

import { Component } from '@angular/core';
import { GxBreadcrumb } from '@sanring/gx-breadcrumb';

@Component({
  selector: 'app-layout',
  standalone: true,
  imports: [GxBreadcrumb],
  template: `
    <!-- mode="auto" 從路由自動生成 -->
    <gx-breadcrumb mode="auto" [showIcon]="true" />
  `
})
export class LayoutComponent {}

需要配置路由：

// app.routes.ts
export const routes: Routes = [
  {
    path: '',
    data: { breadcrumb: '首頁' }
  },
  {
    path: 'products',
    data: { breadcrumb: '產品列表' },
    children: [
      {
        path: ':id',
        data: {
          breadcrumb: (route) => `產品 ${route.params['id']}`
        }
      }
    ]
  }
];

方式 3：包裝組件 - 手動模式

import { Component } from '@angular/core';
import { GxBreadcrumb, IGxBreadCrumb } from '@sanring/gx-breadcrumb';

@Component({
  selector: 'app-example',
  standalone: true,
  imports: [GxBreadcrumb],
  template: `
    <gx-breadcrumb
      mode="manual"
      [data]="breadcrumbs"
      [showIcon]="true"
    />
  `
})
export class ExampleComponent {
  breadcrumbs: IGxBreadCrumb[] = [
    { label: '首頁', link: '/', icon: '🏠' },
    { label: '產品', link: '/products', icon: '📦' },
    { label: '詳情', link: '/products/123', icon: '📄' }
  ];
}

🔄 向後兼容（舊版 API）

如果您使用舊版本，可以繼續使用 gx-breadcrumb-legacy：

import { GxBreadcrumbLegacy } from '@sanring/gx-breadcrumb';

@Component({
  imports: [GxBreadcrumbLegacy],
  template: `
    <gx-breadcrumb-legacy [data]="breadcrumbs" />
  `
})
export class LegacyComponent {}

圖標使用方式

選項 1：使用 Lucide 圖標（需要安裝 lucide-angular）

import { Component } from '@angular/core';
import { GxBreadcrumb, IGxBreadCrumb } from '@sanring/gx-breadcrumb';
import { Home, Package, FileText } from 'lucide-angular';

@Component({
  template: `
    <gx-breadcrumb
      [data]="breadcrumbs"
      [showIcon]="true">
    </gx-breadcrumb>
  `
})
export class MyComponent {
  breadcrumbs: IGxBreadCrumb[] = [
    { label: '首頁', link: '/', iconImg: Home },
    { label: '產品', link: '/products', iconImg: Package },
    { label: '詳情', link: '/products/123', iconImg: FileText }
  ];
}

選項 2：使用文字/Emoji 圖標（無需額外安裝）

breadcrumbs: IGxBreadCrumb[] = [
  { label: '首頁', link: '/', icon: '🏠' },
  { label: '產品', link: '/products', icon: '📦' },
  { label: '詳情', link: '/products/123', icon: '📄' }
];

自定義分隔符號

import { GxBreadcrumbSeparator } from '@sanring/gx-breadcrumb';

@Component({
  template: `
    <gx-breadcrumb
      [data]="breadcrumbs"
      [separator]="separator">
    </gx-breadcrumb>
  `
})
export class MyComponent {
  separator = GxBreadcrumbSeparator.Arrow; // '›'
  // 其他選項：
  // GxBreadcrumbSeparator.Slash  → '/'
  // GxBreadcrumbSeparator.Dot    → '·'
  // GxBreadcrumbSeparator.Hyphen → '–'
}

主題和變體

@Component({
  template: `
    <gx-breadcrumb
      [data]="breadcrumbs"
      [theme]="'default'"
      [variant]="'glass'">
    </gx-breadcrumb>
  `
})

📖 API 文檔

🆕 GxBreadcrumbContainer

容器組件，提供主題和變體樣式。

Inputs

| 屬性 | 類型 | 預設值 | 說明 | |------|------|--------|------| | theme | GxTheme | 'default' | 主題樣式（'default' | 'dark' | 'brand'） | | variant | GxVariant | 'modern' | 變體樣式（'modern' | 'glass' | 'minimal' | 'colorful'） |

🆕 GxBreadcrumbList

列表組件，負責渲染麵包屑項目容器。

Inputs

| 屬性 | 類型 | 預設值 | 說明 | |------|------|--------|------| | separator | GxBreadcrumbSeparator | Slash | 分隔符號類型 | | ariaLabel | string | 'Breadcrumb navigation' | 無障礙標籤 |

🆕 GxBreadcrumbItemV2

麵包屑項目組件（完全獨立可用）。

Inputs

| 屬性 | 類型 | 預設值 | 說明 | |------|------|--------|------| | label | string | 必填 | 顯示文字 | | link | string \| undefined | undefined | 連結路徑 | | icon | string \| undefined | undefined | 文字/Emoji 圖標 | | iconImg | any | undefined | Lucide 圖標 | | active | boolean | false | 是否為當前頁 | | disabled | boolean | false | 是否禁用 | | showIcon | boolean | false | 是否顯示圖標 | | separator | string | '/' | 分隔符字元 | | showSeparator | boolean | true | 是否顯示分隔符 | | target | '_self' \| '_blank' | '_self' | 外部連結的 target |

Outputs

| 事件 | 類型 | 說明 | |------|------|------| | itemClick | OutputEmitter<{label: string; link?: string}> | 點擊項目時觸發 |

GxBreadcrumb（包裝組件）

Inputs

| 屬性 | 類型 | 預設值 | 說明 | |------|------|--------|------| | mode | 'auto' \| 'manual' \| 'custom' | 'auto' | 使用模式 | | data | IGxBreadCrumb[] | null | 手動模式：提供麵包屑數據 | | theme | GxTheme | 'default' | 主題樣式 | | variant | GxVariant | 'modern' | 變體樣式 | | separator | GxBreadcrumbSeparator | Slash | 分隔符號 | | showIcon | boolean | false | 是否顯示圖標 | | rootCrumb | IGxBreadCrumb \| false \| undefined | undefined | 自定義根麵包屑 |

Outputs

| 事件 | 類型 | 說明 | |------|------|------| | itemClick | OutputEmitter<IGxBreadCrumb> | 點擊麵包屑項目時觸發 |

IGxBreadCrumb 介面

interface IGxBreadCrumb {
  label: string;           // 顯示文字
  link?: string;           // 連結路徑
  icon?: string;           // 文字/Emoji 圖標（不需要 lucide-angular）
  iconImg?: any;           // Lucide 圖標（需要 lucide-angular）
  active?: boolean;        // 是否為當前頁
  disabled?: boolean;      // 是否禁用
  [key: string]: any;      // 其他自定義屬性
}

GxBreadcrumbSeparator 枚舉

enum GxBreadcrumbSeparator {
  Slash = 'slash',   // '/'
  Arrow = 'arrow',   // '›'
  Dot = 'dot',       // '·'
  Hyphen = 'hyphen'  // '–'
}

🎨 樣式自定義

使用 CSS 變數進行自定義：

:root {
  /* 麵包屑顏色 */
  --gx-bc-fg: var(--gx-color-gray-900);           /* 文字顏色 */
  --gx-bc-muted: var(--gx-color-gray-500);        /* 非活動項顏色 */
  --gx-bc-hover: var(--gx-color-accent-500);      /* Hover 顏色 */

  /* 字重 */
  --gx-normal-weight: var(--gx-weight-medium);    /* 一般字重 */
  --gx-active-weight: var(--gx-weight-extraBold); /* 活動項字重 */

  /* 間距 */
  --gx-bc-gap: 16px;                              /* 項目間距 */
  --gx-bc-item-gap: 16px;                         /* 圖標與文字間距 */

  /* 效果 */
  --gx-bc-scale: 1.03;                            /* Hover 縮放 */
  --gx-bc-fsz: 16px;                              /* 字體大小 */

  /* 容器 */
  --gx-breadcrumb-bg: var(--gx-color-gray-50);    /* 背景色 */
}

Glass 變體樣式

:root {
  /* Glass 效果會自動套用半透明和毛玻璃效果 */
  --gx-breadcrumb-glass-bg: rgba(255, 255, 255, 0.25);
  --gx-breadcrumb-glass-border: rgba(255, 255, 255, 0.3);
}

🔧 進階用法

自定義根麵包屑

@Component({
  template: `
    <gx-breadcrumb
      [rootCrumb]="customRoot">
    </gx-breadcrumb>
  `
})
export class MyComponent {
  customRoot: IGxBreadCrumb = {
    label: '控制台',
    link: '/dashboard',
    icon: '📊'
  };
}

動態路由麵包屑

// app.routes.ts
{
  path: 'users/:id',
  data: {
    breadcrumb: (route: ActivatedRouteSnapshot) => {
      const userId = route.params['id'];
      return `用戶 ${userId}`;
    }
  }
}

禁用特定麵包屑

breadcrumbs: IGxBreadCrumb[] = [
  { label: '首頁', link: '/' },
  { label: '設定', link: '/settings', disabled: true }, // 禁用
  { label: '個人資料', link: '/settings/profile' }
];

📝 完整範例

import { Component } from '@angular/core';
import { GxBreadcrumb, IGxBreadCrumb, GxBreadcrumbSeparator } from '@sanring/gx-breadcrumb';

@Component({
  selector: 'app-product-detail',
  standalone: true,
  imports: [GxBreadcrumb],
  template: `
    <gx-breadcrumb
      [data]="breadcrumbs"
      [showIcon]="true"
      [separator]="separator"
      [variant]="'glass'"
      (itemClick)="onBreadcrumbClick($event)">
    </gx-breadcrumb>

    <div class="content">
      <!-- 頁面內容 -->
    </div>
  `,
  styles: [`
    :host {
      display: block;
      padding: 20px;
    }
  `]
})
export class ProductDetailComponent {
  separator = GxBreadcrumbSeparator.Arrow;

  breadcrumbs: IGxBreadCrumb[] = [
    { label: '首頁', link: '/', icon: '🏠' },
    { label: '產品', link: '/products', icon: '📦' },
    { label: '電子產品', link: '/products/electronics', icon: '💻' },
    { label: 'iPhone 15', icon: '📱' }
  ];

  onBreadcrumbClick(crumb: IGxBreadCrumb) {
    console.log('Clicked:', crumb);
  }
}

🐛 常見問題

Q: 為什麼分隔符號不顯示？

A: 有兩個可能原因：

原因 1：沒有麵包屑數據

確保你提供了麵包屑數據。有兩種方式：

1. 手動模式：提供 [data] input

   <gx-breadcrumb [data]="breadcrumbs"></gx-breadcrumb>

2. 自動模式：配置路由的 breadcrumb data

   {
     path: 'products',
     data: { breadcrumb: '產品' }
   }

原因 2：CSS 變數未定義（分隔符號顏色透明）

如果分隔符號存在但看不見，可能是 CSS 變數未定義。解決方法：

在你的全局 CSS 中添加：

:root {
  --gx-color-gray-500: #6b7280;  /* 分隔符號顏色 */
}

或直接覆蓋：

.gx-breadcrumb-separator {
  color: #6b7280 !important;
}

注意：從 v3.1.0 開始，組件已內建回退值 #6b7280，即使沒有定義 CSS 變數也能正常顯示。

Q: Lucide 圖標不顯示？

A: 確保已安裝並導入 lucide-angular：

npm install lucide-angular

如果不想使用 Lucide，可以使用 icon 屬性配合 Emoji 或文字：

{ label: '首頁', icon: '🏠' }  // ✅ 不需要 lucide-angular

Q: 如何自定義樣式？

A: 使用 CSS 變數覆蓋默認樣式：

:root {
  --gx-bc-hover: #3b82f6;
  --gx-bc-fsz: 18px;
}

📚 參考資料

• Angular Router
• Lucide Icons
• ARIA Breadcrumb Pattern

🤝 貢獻

歡迎提交 Issue 或 Pull Request！

📄 授權

MIT License