GX-Wizard

一個功能完整的 Angular 步驟導航組件，提供直觀的多步驟流程體驗。採用 Angular Standalone Components 架構實現，適合用於表單嚮導、註冊流程、多階段任務等場景。

✅ 已完成的組件

核心組件

• ✅ GxWizardContainer - 步驟器容器（支援步驟指示器、導航、狀態管理）
• ✅ GxWizardStep - 單一步驟容器
• ✅ GxWizardHeader - 步驟標頭（支援標題、描述、圖標）
• ✅ GxWizardContent - 步驟內容區域
• ✅ GxWizardActions - 步驟動作按鈕（上一步、下一步、完成）

類型定義

• ✅ WizardStepConfig - 步驟配置介面
• ✅ WizardCustomClass - 自定義樣式介面
• ✅ StepChangeEvent - 步驟變更事件
• ✅ NextStepEvent / PrevStepEvent / FinishEvent - 各種事件介面

📦 安裝

npm install @sanring/gx-wizard

🎯 使用方式

基本範例

import { Component } from '@angular/core';
import {
  GxWizardContainer,
  WizardStepConfig
} from '@sanring/gx-wizard';

@Component({
  selector: 'app-example',
  standalone: true,
  imports: [GxWizardContainer],
  template: `
    <gx-wizard-container
      [wizardId]="'registration-wizard'"
      [steps]="steps"
      [showStepsIndicator]="true"
      (finish)="onFinish($event)">

      <!-- 自定義步驟內容 -->
      <div step-content>
        @switch (wizardContainer.currentStep()) {
          @case (1) {
            <h3>步驟 1：基本資料</h3>
            <p>請輸入您的基本資料...</p>
          }
          @case (2) {
            <h3>步驟 2：聯絡方式</h3>
            <p>請輸入您的聯絡方式...</p>
          }
          @case (3) {
            <h3>步驟 3：確認資料</h3>
            <p>請確認您的資料...</p>
          }
        }
      </div>
    </gx-wizard-container>
  `
})
export class ExampleComponent {
  steps: WizardStepConfig[] = [
    { id: 'basic', title: '基本資料', description: '填寫基本資訊' },
    { id: 'contact', title: '聯絡方式', description: '填寫聯絡資訊' },
    { id: 'confirm', title: '確認資料', description: '檢查並確認' }
  ];

  onFinish(event: { wizardId: string }) {
    console.log('Wizard 完成:', event.wizardId);
  }
}

完整範例（含步驟監聽）

import { Component, signal } from '@angular/core';
import {
  GxWizardContainer,
  WizardStepConfig,
  StepChangeEvent
} from '@sanring/gx-wizard';
import { CommonModule } from '@angular/common';

@Component({
  selector: 'app-multi-step-form',
  standalone: true,
  imports: [CommonModule, GxWizardContainer],
  template: `
    <gx-wizard-container
      [wizardId]="'user-registration'"
      [steps]="steps"
      [initialStep]="1"
      [showStepsIndicator]="true"
      [allowStepJump]="false"
      (stepChange)="onStepChange($event)"
      (next)="onNext($event)"
      (prev)="onPrev($event)"
      (finish)="onFinish($event)">
    </gx-wizard-container>
  `
})
export class MultiStepFormComponent {
  steps: WizardStepConfig[] = [
    {
      id: 'personal',
      title: '個人資料',
      description: '請提供您的個人資訊',
    },
    {
      id: 'account',
      title: '帳號設定',
      description: '設定您的帳號資訊',
    },
    {
      id: 'preferences',
      title: '偏好設定',
      description: '自訂您的偏好',
    },
    {
      id: 'review',
      title: '檢視確認',
      description: '檢查所有資訊',
    }
  ];

  onStepChange(event: StepChangeEvent) {
    console.log(`步驟變更：從 ${event.from} 到 ${event.to}`);
  }

  onNext(event: { step: number }) {
    console.log('下一步:', event.step);
  }

  onPrev(event: { step: number }) {
    console.log('上一步:', event.step);
  }

  onFinish(event: { wizardId: string }) {
    console.log('完成 Wizard:', event.wizardId);
    // 提交表單或導航到其他頁面
  }
}

自定義樣式

@Component({
  template: `
    <gx-wizard-container
      [wizardId]="'custom-wizard'"
      [steps]="steps"
      [customClass]="{
        container: 'my-wizard-container',
        indicator: 'my-indicator',
        header: 'my-header',
        body: 'my-body',
        actions: 'my-actions',
        prevButton: 'my-prev-btn',
        nextButton: 'my-next-btn',
        finishButton: 'my-finish-btn'
      }">
    </gx-wizard-container>
  `,
  styles: [`
    .my-wizard-container {
      max-width: 800px;
      margin: 0 auto;
    }

    .my-next-btn {
      background: #10b981;
      color: white;
    }
  `]
})
export class CustomStyledWizardComponent {
  // ...
}

📖 API 文檔

GxWizardContainer

| 屬性 | 類型 | 預設值 | 說明 | |------|------|--------|------| | wizardId | string | 必填 | Wizard 唯一識別 | | steps | WizardStepConfig[] | [] | 步驟配置陣列 | | initialStep | number | 1 | 初始步驟 | | showStepsIndicator | boolean | true | 是否顯示步驟指示器 | | allowStepJump | boolean | false | 是否允許跳轉步驟 | | customClass | WizardCustomClass | {} | 自定義樣式 |

事件：

• stepChange: EventEmitter<StepChangeEvent> - 步驟變更事件
• next: EventEmitter<NextStepEvent> - 下一步事件
• prev: EventEmitter<PrevStepEvent> - 上一步事件
• finish: EventEmitter<FinishEvent> - 完成事件

插槽：

• [indicator] - 自定義步驟指示器
• [step-content] - 自定義步驟內容

GxWizardStep

| 屬性 | 類型 | 預設值 | 說明 | |------|------|--------|------| | wizardId | string | 必填 | Wizard ID | | step | number | 必填 | 當前步驟序號 | | totalSteps | number | 0 | 總步驟數 | | title | string | undefined | 步驟標題 | | description | string | undefined | 步驟描述 | | active | boolean | false | 是否為目前啟用的步驟 | | customClass | WizardCustomClass | {} | 自定義樣式 |

事件：

• next: EventEmitter<{wizardId: string, step: number}> - 下一步事件
• prev: EventEmitter<{wizardId: string, step: number}> - 上一步事件
• finish: EventEmitter<{wizardId: string}> - 完成事件

插槽：

• [header] - 自定義標頭
• [content] - 自定義內容
• [actions] - 自定義動作按鈕

GxWizardHeader

| 屬性 | 類型 | 預設值 | 說明 | |------|------|--------|------| | wizardId | string | 必填 | Wizard ID | | step | number | 必填 | 當前步驟序號 | | totalSteps | number | 0 | 總步驟數 | | title | string | undefined | 標題 | | description | string | undefined | 描述文字 | | showIcon | boolean | false | 是否顯示圖標 | | showStepIndicator | boolean | true | 是否顯示步驟指示器 |

插槽：

• [icon] - 自定義圖標
• [title] - 自定義標題
• [description] - 自定義描述
• [indicator] - 自定義步驟指示器

GxWizardActions

| 屬性 | 類型 | 預設值 | 說明 | |------|------|--------|------| | wizardId | string | 必填 | Wizard ID | | step | number | 必填 | 當前步驟序號 | | totalSteps | number | 0 | 總步驟數 | | showPrev | boolean | true | 是否顯示上一步按鈕 | | showNext | boolean | true | 是否顯示下一步按鈕 | | showFinish | boolean | false | 是否顯示完成按鈕 | | prevLabel | string | '上一步' | 上一步按鈕文字 | | nextLabel | string | '下一步' | 下一步按鈕文字 | | finishLabel | string | '完成' | 完成按鈕文字 |

事件：

• next: EventEmitter<void> - 下一步事件
• prev: EventEmitter<void> - 上一步事件
• finish: EventEmitter<void> - 完成事件

插槽：

• [prev-button] - 自定義上一步按鈕內容
• [next-button] - 自定義下一步按鈕內容
• [finish-button] - 自定義完成按鈕內容

WizardStepConfig 介面

interface WizardStepConfig {
  id: string;              // 步驟唯一識別
  title: string;           // 步驟標題
  description?: string;    // 步驟描述
  disabled?: boolean;      // 是否禁用
  [key: string]: any;      // 其他自定義屬性
}

WizardCustomClass 介面

interface WizardCustomClass {
  container?: string;        // 容器樣式
  indicator?: string;        // 指示器樣式
  content?: string;          // 內容區樣式
  header?: string;           // 標頭樣式
  body?: string;             // 主體樣式
  actions?: string;          // 動作區樣式
  actionContainer?: string;  // 動作容器樣式
  prevButton?: string;       // 上一步按鈕樣式
  nextButton?: string;       // 下一步按鈕樣式
  finishButton?: string;     // 完成按鈕樣式
}

🎨 樣式自定義

使用 CSS 變數進行自定義：

:root {
  /* 主要顏色 */
  --gx-wizard-primary-color: #3b82f6;
  --gx-wizard-primary-hover-color: #2563eb;

  /* 容器 */
  --gx-wizard-bg: #ffffff;
  --gx-wizard-shadow: 0 1px 3px 0 rgba(0, 0, 0, 0.1);
  --gx-wizard-border-color: #e5e7eb;

  /* 文字顏色 */
  --gx-wizard-title-color: #111827;
  --gx-wizard-description-color: #6b7280;
  --gx-wizard-counter-color: #6b7280;

  /* 次要按鈕 */
  --gx-wizard-secondary-text-color: #374151;
  --gx-wizard-secondary-hover-bg: #f3f4f6;

  /* 指示器顏色 */
  --gx-wizard-gray-300: #d1d5db;
  --gx-wizard-gray-400: #9ca3af;
}

🔄 技術實現

本組件採用 Angular 18+ 的 Standalone Components 架構，提供現代化的開發體驗。

組件架構

| 組件名稱 | 功能說明 | |---------|---------| | GxWizardContainer | 步驟容器，負責狀態管理與導航控制 | | GxWizardStep | 單一步驟組件，處理步驟生命週期與狀態 | | GxWizardHeader | 步驟標頭，顯示標題、描述與視覺指示 | | GxWizardContent | 步驟內容區域，支援完全自定義內容 | | GxWizardActions | 步驟操作按鈕，處理導航邏輯與事件 |

核心特點

• 響應式狀態管理：完全使用 Angular Signals 進行狀態管理
• 靈活的內容投影：支援多層級的 Content Projection
• 豐富的事件系統：提供完整的生命週期事件掛鉤
• 無障礙支援：內建 ARIA 屬性，符合無障礙標準
• 高度可客製化：支援樣式與行為的完全自定義

🛠️ 開發

# 構建
npm run build

# 查看生成的文件
ls -la dist/gx-wizard

🤝 貢獻

歡迎提交 PR 或 Issue！