CaaS 企業級前端模組集成手冊 (CaaS Frontend Integration Guide)

本目錄包含提供給外部系統引用的核心 CaaS (Component as a Service) Web Components 模組。這些組件完全封裝於 Shadow DOM 中，實現了對宿主系統的「零侵入性」集成。

1. 快速開始 (Quick Start)

外部系統工程師僅需引用模組腳本，即可在任何 HTML 環境中部署強大的功能模組。

1.1 引用腳本

<script src="https://cdn.caas-system.com/frontend/v1/main.js" type="module"></script>

1.2 放置容器

<!-- 呼叫 CaaS 核心模組 -->
<caas-system></caas-system>

2. 核心功能模組 (Modules)

目前系統支援以下模組，預設透過內置路由進行切換：

• Dashboard (儀表板)：包含 8 項核心指標、10 種專業數據圖表（財務、流量、負載、庫存等）。
• Authentication (認證)：包含標準化的登入頁面與註冊頁面，支援外部 Slot 注入。

3. 模組詳細引用指南 (Module-specific Integration)

您可以透過為 <caas-system> 標籤添加屬性 (Attributes) 來精確控制顯示的模組。

3.1 儀表板模組 (Dashboard Module)

用於展示全域數據監控中心。

• 引用方式：

  <caas-system initial-module="dashboard"></caas-system>

• 專屬自定義 (Attributes & Slots)： | 屬性/插槽名稱 | 類型 | 說明 | | :--- | :--- | :--- | | initial-module | Attribute | 必須設為 dashboard | | refresh-interval | Attribute | 圖表自動刷新頻率 (ms)，預設 30000 | | chart-theme | Attribute | 可選 light (預設) 或 dark | | dashboard-title | Slot | 自定義儀表板頂部的標題文字 | | sidebar-mode | Attribute | 側邊欄模式：push (預設) 或 overlay (懸浮) | | show-mode-toggle | Attribute | 是否顯示模式切換按鈕，預設 true (僅限儀表板) |

3.2 認證模組 (Auth Module)

提供登入與註冊功能。

• 引用方式：

  <!-- 預設顯示登入頁 -->
  <caas-system initial-module="login"></caas-system>

• 專屬自定義 (Attributes & Slots)： | 屬性/插槽名稱 | 類型 | 說明 | | :--- | :--- | :--- | | redirect-url | Attribute | 登入成功後跳轉的外部 URL | | form-prepend | Slot | 在表單上方注入自定義 HTML (如：資安聲明) | | login-logo | Slot | 自定義登入框上方的 Logo 圖片 |

4. 原子組件引用指南 (Atomic Components)

如果您不需要整個儀表板，可以單獨引用特定的原子組件。

4.1 數據指標卡片 <caas-metric-card>

用於在外部系統的任何位置插入單個數據指標。

4.1.1 引用方式

<caas-metric-card 
  title="今日營收" 
  value="$12,840" 
  trend="+12%" 
  trend-type="positive" 
  icon="DollarSign">
</caas-metric-card>

4.1.2 尺寸與佈局 (Sizing & Layout)

• 預設尺寸：組件採自適應寬度 (width: 100%)，預設高度約為 140px。
• 建議容器：建議放置於寬度介於 220px 至 400px 之間的容器中以獲得最佳視覺比例。
• 自定義尺寸：工程師可直接在標籤上透過 CSS 控制寬度：

  <caas-metric-card style="width: 300px;"></caas-metric-card>

• Grid 佈局範例：

  .my-grid {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(240px, 1fr));
    gap: 16px;
  }

4.1.3 屬性詳細說明 (Attributes)

| 屬性名稱 | 類型 | 預設值 | 說明 | 範例值 | | :--- | :--- | :--- | :--- | :--- | | title | String | (空) | 卡片左上角顯示的標題文字 | 總註冊用戶 | | value | String/Num | (空) | 中間加粗顯示的核心數值 | 1,284,500 | | trend | String | (空) | 底部顯示的趨勢百分比或描述文字 | +5.2% from last week | | trend-type | Enum | neutral | 趨勢顏色類型。影響趨勢文字顏色： - positive: 綠色 (Success) - negative: 紅色 (Danger) - neutral: 灰色 (Slate) | positive | | icon | String | Activity | 採用的 Lucide 圖標名稱 (大小寫敏感)。常用：Users, DollarSign, ShoppingBag, Server, Clock | Users |

4.1.4 設計規範 (Design Tokens)

• 圓角：12px
• 背景：#FFFFFF (Solid)
• 邊框：1px solid #E2E8F0
• 陰影：0 1px 3px 0 rgba(0, 0, 0, 0.1) (Soft)

4.2 基礎按鈕 <caas-button>

通用按鈕，支援品牌主色、幽靈按鈕等多種樣式。

4.2.1 引用方式

<caas-button variant="primary" size="lg">立即報名</caas-button>

4.2.2 屬性詳細說明 (Attributes)

| 屬性名稱 | 類型 | 預設值 | 說明 | | :--- | :--- | :--- | :--- | | variant | Enum | primary | primary, secondary, outline, danger, ghost | | size | Enum | md | sm, md, lg |

4.3 文字輸入框 <caas-text-field>

標準輸入框，具備標籤與必填校驗功能。

4.3.1 引用方式

<caas-text-field label="電子郵件" placeholder="[email protected]" required></caas-text-field>

4.3.2 屬性詳細說明 (Attributes)

| 屬性名稱 | 類型 | 預設值 | 說明 | | :--- | :--- | :--- | :--- | | label | String | (空) | 輸入框上方的標題文字 | | placeholder | String | (空) | 佔位提示文字 | | required | Boolean | false | 是否顯示必填紅星號 | | type | String | text | HTML input 類型 (password, email 等) |

4.4 狀態標籤 <caas-status-badge>

用於展示語義化狀態的標籤。

4.4.1 引用方式

<caas-status-badge type="success" variant="soft" pill>已完成</caas-status-badge>

4.4.2 屬性詳細說明 (Attributes)

| 屬性名稱 | 類型 | 預設值 | 說明 | | :--- | :--- | :--- | :--- | | type | Enum | neutral | primary, success, warning, danger, info, neutral | | variant | Enum | soft | solid, outline, soft | | size | Enum | md | sm, md, lg | | pill | Boolean | false | 是否為全圓角樣式 |

4.5 彈窗容器 <caas-modal>

用於展示互動式對話框或詳細表單。

4.5.1 引用方式

<caas-modal title="新增案場資料" size="md" open>
  <div slot="body">
    <caas-text-field label="案場名稱" placeholder="請輸入"></caas-text-field>
  </div>
</caas-modal>

4.5.2 屬性詳細說明 (Attributes)

| 屬性名稱 | 類型 | 預設值 | 說明 | | :--- | :--- | :--- | :--- | | title | String | (空) | 彈窗標題 | | size | Enum | md | sm, md, lg, xl, full | | open | Boolean | false | 控制彈窗開啟狀態 |

4.6 專案時間軸 <caas-timeline>

用於展示連續事件或進度。

4.5.1 引用方式

<caas-timeline mode="horizontal" id="case-steps"></caas-timeline>
<script>
  document.getElementById('case-steps').items = [
    { id: 1, title: '接案', status: 'completed' },
    { id: 2, title: '施工', status: 'active' }
  ];
</script>

4.6 照片網格 <caas-photo-grid>

通用的圖片展示網格。

4.6.1 引用方式

<caas-photo-grid columns="3" aspect-ratio="square" id="site-photos"></caas-photo-grid>
<script>
  document.getElementById('site-photos').photos = [
    { id: 1, url: 'path/to/img1.jpg', tag: '施工前' },
    { id: 2, url: 'path/to/img2.jpg', tag: '施工後' }
  ];
</script>

4.7 切換按鈕 <caas-switch>

用於切換二元狀態的開關組件。

4.7.1 引用方式

<caas-switch label="開啟深色模式" color="primary" size="medium"></caas-switch>

4.7.2 屬性詳細說明 (Attributes)

| 屬性名稱 | 類型 | 預設值 | 說明 | | :--- | :--- | :--- | :--- | | label | String | (空) | 顯示在按鈕旁的標籤文字 | | size | Enum | medium | small, medium, large | | color | Enum | primary | primary, success, danger, warning | | checked | Boolean | false | 是否選中 (存在即為 true) | | disabled | Boolean | false | 是否禁用 (存在即為 true) |

4.8 標籤頁 <caas-tabs>

用於內容分組切換。

4.8.1 引用方式

<caas-tabs 
  type="pills" 
  items='[{"key":"1","label":"基本資料"},{"key":"2","label":"進階設定"}]'>
</caas-tabs>

4.9 數據分頁 <caas-pagination>

處理大數據列表。

4.9.1 引用方式

<caas-pagination 
  current="1" 
  total="500" 
  show-quick-jumper 
  show-first-last>
</caas-pagination>

4.9.2 事件監聽

document.querySelector('caas-pagination').addEventListener('change', (e) => {
  console.log('跳轉至第', e.detail.page, '頁');
});

4.10 麵包屑 <caas-breadcrumb>

展示層級路徑。

4.10.1 引用方式

<caas-breadcrumb 
  items='[{"label":"首頁","href":"/"}, {"label":"當前頁面"}]'>
</caas-breadcrumb>

4.8 佈局網格容器 <caas-grid-container>

強大的響應式佈局工具。

4.7.1 引用方式

<caas-grid-container mode="adaptive" min-child-width="300px">
  <!-- 放置多個原子組件 -->
</caas-grid-container>

4.8 下拉選單 <caas-select> (React Prop-based)

企業級 MUI 風格下拉選單，支援單選、多選、可搜尋篩選。使用 Inline Styles 架構，確保在任何宿主環境下視覺一致。

4.4.1 基礎單選

<Select
  label="居住城市"
  options={[{ label: '台北市', value: 'tpe' }, { label: '新北市', value: 'npt' }]}
  value={city}
  onChange={(v) => setCity(v as string | number)}
/>

4.4.2 多選 + Checkbox

<Select
  label="多選城市"
  multiple
  showCheckbox
  options={cityOptions}
  value={cities}
  onChange={(v) => setCities(v as (string | number)[])}
/>

4.4.3 Props 速覽

| Prop | 類型 | 預設值 | 說明 | |---|---|---|---| | options | SelectOption[] | — | 必填。{ label, value, icon? } | | value | string \| number \| (string \| number)[] | — | 受控值 | | onChange | Function | — | 必填。值變更回調 | | multiple | boolean | false | 多選模式 | | searchable | boolean | false | 前端即時搜尋篩選 | | showRadio | boolean | false | Radio 圖示（單選推薦） | | showCheckbox | boolean | false | Checkbox 圖示（多選推薦） | | error | string | — | 錯誤訊息（紅框） |

⚠️ 類型注意：onChange 接受聯合類型，需用 wrapper function 搭配 type cast，詳見 src/components/select/README.md。

4.9 全域訊息反饋 (Message API)

不同於其他宣告式標籤，訊息反饋系統提供的是一組掛載於全域的命令式 API，讓您能隨時在 Javascript 業務邏輯中觸發浮動提示。

4.9.1 引用方式

外部環境可直接透過全域變數 window.CaaS.message 進行呼叫 (需確認 CaaS 系統已完成載入)：

// 基礎狀態提示
window.CaaS.message.success('資料存檔成功！');
window.CaaS.message.error('連線逾時，請重試。');
window.CaaS.message.info('系統將於五分鐘後維護');
window.CaaS.message.warning('請注意庫存不足');

// 自定義進階選項
window.CaaS.message.show({
  text: '請注意，此操作不可逆！',
  type: 'warning',
  duration: 8, // 顯示 8 秒 (預設為 3 秒)
  animation: 'bounce' // 彈跳進場
});

4.10 數據表格 <caas-table>

高性能表格，支援自定義渲染、排序與列寬拖曳。

4.10.1 引用方式

<caas-table id="my-table" divided bordered allow-resize></caas-table>
<script>
  const table = document.getElementById('my-table');
  table.columns = [
    { title: '名稱', dataIndex: 'name', key: 'name', sortable: true, width: 150 },
    { title: '角色', dataIndex: 'role', key: 'role', width: 120 }
  ];
  table.dataSource = [
    { id: 1, name: '張三', role: '管理員' },
    { id: 2, name: '李四', role: '開發者' }
  ];
</script>

4.10.2 屬性詳細說明 (Attributes)

| 屬性名稱 | 類型 | 預設值 | 說明 | | :--- | :--- | :--- | :--- | | loading | Boolean | false | 顯示超大加載狀態 | | divided | Boolean | false | 顯示垂直分隔線 | | bordered | Boolean | false | 顯示完整邊框 | | allow-resize | Boolean | false | 開啟列寬手動調整 |

4.11 空數據狀態 <caas-empty>

數據為空時的視覺展示。

4.11.1 引用方式

<caas-empty description="目前沒有相關紀錄"></caas-empty>

4.12 氣泡提示 <caas-tooltip>

懸停文字提示。

4.12.1 引用方式

<caas-tooltip title="這是一個提示訊息" placement="top">
  <button>Hover Me</button>
</caas-tooltip>

4.13 複選框 <caas-checkbox>

支援單一開關與半選狀態的複選框。

4.13.1 引用方式

<caas-checkbox label="記住密碼" checked></caas-checkbox>

4.14 單選鈕 <caas-radio>

通用單選按鈕組件。

4.14.1 引用方式

<caas-radio label="選項一" checked></caas-radio>

4.15 數字輸入器 <caas-input-number>

帶有防護機制、範圍限制與加減按鈕的數字輸入框。

4.15.1 引用方式

<caas-input-number label="購買數量" value="10" min="1" max="100"></caas-input-number>

4.16 檔案上傳 <caas-upload>

具備拖曳感知與圖片預覽的高階上傳組件。

4.16.1 引用方式

<caas-upload label="上傳合約" accept=".pdf,.doc" multiple></caas-upload>

4.17 顏色選擇器 <caas-color-picker>

封裝原生色盤，支援即時預覽、無限預設色板管理與狀態連動。

4.17.1 引用方式

<caas-color-picker label="主題顏色" value="#14b8a6"></caas-color-picker>

4.18 日期/時間選擇器 <caas-date-picker>

整合多種交互模式的進階選擇器，支援時鐘撥盤 (Material)、無限滾輪 (Wheel) 與日期範圍 (Range)。

4.18.1 引用方式

<!-- 標準日期選擇 -->
<caas-date-picker label="開始日期" picker="date" value="2026-05-12"></caas-date-picker>

<!-- Material 樣式時間選擇 -->
<caas-date-picker label="到訪時間" picker="time-material" value="14:30"></caas-date-picker>

<!-- 年月/季度滾輪選擇 -->
<caas-date-picker label="結算季度" picker="quarter" variant="arrow"></caas-date-picker>

4.18.2 屬性詳細說明 (Attributes)

| 屬性名稱 | 類型 | 預設值 | 說明 | | :--- | :--- | :--- | :--- | | picker | Enum | date | date, month, quarter, week, time, time-material, date-range, time-range, datetime-local | | variant | Enum | default | default (標準輸入框), arrow (左右箭頭切換年份/季度) | | value | String | (空) | 遵循標準格式 (如 YYYY-MM-DD, HH:mm) | | disabled | Boolean | false | 是否禁用 |

4.19 滑動條 <caas-slider>

用於數值選擇的滑動條，支援音量模式、高度自定義刻度系統 (Marks) 與精密對齊補償。

4.19.1 引用方式

<caas-slider 
  min="0" 
  max="100" 
  value="50" 
  mark-style="line"
  show-tooltip>
</caas-slider>

4.19.2 屬性詳細說明 (Attributes)

| 屬性名稱 | 類型 | 預設值 | 說明 | | :--- | :--- | :--- | :--- | | value | Number | 0 | 當前數值 | | min | Number | 0 | 最小值 | | max | Number | 100 | 最大值 | | step | Number | 1 | 步進值 | | vertical | Boolean | false | 是否開啟垂直模式 | | mark-style | Enum | dot | 刻度預設樣式：dot, line, icon | | show-tooltip | Boolean | true | 是否顯示數值提示 | | is-volume | Boolean | false | 音量交互模式 (含前後圖標) |

4.19.3 特色功能

• 尺規刻度: 支援透過 marks 屬性傳入複雜刻度清單，並可混搭不同樣式。
• 自動間隔: 根據滑鈕大小自動計算 mark-gap，確保視覺不重疊。
• 精密對齊: 內建偏移補償邏輯，確保刻度中心與滑鈕中心完美重疊。

4.20 頁面提示 <caas-alert>

用於顯示訊息、成功、警告或錯誤的反饋提示。

4.20.1 引用方式

<caas-alert type="success" message="操作成功" closable></caas-alert>

4.21 抽屜面版 <caas-drawer>

側邊滑出的容器，支援 Portal 渲染以確保層級最優。

4.21.1 引用方式

<caas-drawer title="詳情面版" placement="right" open>
  <div slot="content">自定義內容</div>
</caas-drawer>

4.22 氣泡確認框 <caas-popconfirm>

就近的二次確認氣泡，自動處理觸發邏輯。

4.22.1 引用方式

<caas-popconfirm title="確定刪除嗎？">
  <caas-button variant="danger">刪除</caas-button>
</caas-popconfirm>

4.23 全域通知與訊息 <caas-notification>

雖然透過 JS API 調用，但組件標籤可預先放置或由 API 自動建立。

4.23.1 調用方式

window.CaaS.notification.notify('標題', '描述內容', 'success');

4.24 行事曆組件 <caas-calendar>

提供多視圖（月、週、日）的高密度企業級行事曆管理模組。

4.24.1 引用方式

<caas-calendar id="my-calendar" view="month" week-starts-on="1"></caas-calendar>
<script>
  document.getElementById('my-calendar').events = [
    {
      id: '1',
      title: '業務會議',
      startDate: new Date(),
      endDate: new Date(new Date().getTime() + 3600000),
      color: '#0ea5e9'
    }
  ];
</script>

5. 高度客製化規範 (General Customization)

CaaS 模組設計之初即考慮到高度的「白牌化 (White-labeling)」需求。

5.1 樣式與主題 (Theming via CSS Variables)

外部工程師可以透過在宿主頁面的 CSS 中定義變數，直接覆蓋模組內部的主題色：

/* 在外部系統的 CSS 中定義 */
caas-system {
  --caas-color-primary-500: #14b8a6; /* 更換品牌主色 */
  --caas-color-success: #10b981;     /* 更換成功狀態色 */
  --caas-font-family: 'Inter', sans-serif; /* 統一字體 */
}

5.2 深色模式支援 (Dark Mode)

系統內建完整的深色模式設計代幣 (Design Tokens)。要啟用深色模式，只需在包含 CaaS Web Component 的父節點（或 <html>, <body>）加上 data-theme="dark" 屬性即可：

<!-- 為整個系統或單一組件開啟深色模式 -->
<caas-system data-theme="dark"></caas-system>

深色模式將自動切換所有背景、文字色階與邊框等顏色，外部系統完全無須介入處理。

5.3 全域插槽 (Global Slots)

| 插槽名稱 (Slot Name) | 作用位置 | 建議用途 | | :--- | :--- | :--- | | top-brand | 頂部導航欄左側 | 放置宿主系統的 Logo 或品牌名稱 | | sidebar-footer | 側邊欄底部 | 放置客服電話或版本資訊 |

6. 事件通訊 (Events)

模組會與宿主環境進行非同步通訊，外部工程師可以監聽以下事件：

6.1 caas:system:ready

當 Web Component 完成掛載且內部 React 應用初始化完畢後觸發。

window.addEventListener('caas:system:ready', (event) => {
  console.log('CaaS 模組已就緒:', event.detail.timestamp);
});

7. 技術規格與限制 (Specifications)

• 封裝技術：Shadow DOM (Mode: Open)。
• 寬度適應：:host 為 display: block，寬度預設 100% 適應父容器。
• 圖表引擎：基於 Recharts，已解決 Shadow DOM 下的寬度偵測問題，支援 RWD。
• 圖示規範：嚴禁 Emoji，全面採用 Lucide-React 語義化圖示。
• 字體處理：優先繼承宿主系統字體。

8. 性能優化與載入策略 (Performance & Loading)

為了確保宿主系統的加載速度，建議採取以下優化措施：

8.1 延遲加載 (Lazy Loading)

建議僅在用戶滾動至組件可見區域時才初始化組件。

const observer = new IntersectionObserver((entries) => {
  entries.forEach(entry => {
    if (entry.isIntersecting) {
      const caas = document.createElement('caas-system');
      caas.setAttribute('initial-module', 'dashboard');
      entry.target.appendChild(caas);
      observer.unobserve(entry.target);
    }
  });
});
observer.observe(document.getElementById('chart-container'));

8.2 CDN 緩存與版本控制

• 正式環境：請引用帶有版本號的 URL (如 /v1.2.3/main.js) 以獲得極速的長時間緩存。
• 測試環境：可引用 /latest/main.js 以獲取最新功能。

9. 瀏覽器相容性 (Compatibility)

CaaS 模組基於 Web Components V1 規範開發，支援以下瀏覽器：

| 瀏覽器 | 最低支援版本 | 備註 | | :--- | :--- | :--- | | Chrome / Edge | 80+ | 完整支援 | | Firefox | 63+ | 完整支援 | | Safari | 13.1+ | 完整支援 | | Opera | 67+ | 完整支援 |

註：不支援 Internet Explorer (IE11) 或非 Chromium 內核的舊版 Edge。

10. 安全性規範 (Security)

• 資料消毒 (Sanitization)：模組內部會對所有傳入的 Attribute 進行 XSS 消毒處理，嚴禁惡意腳本注入。
• 跨域防禦 (CORS)：CDN 節點已配置嚴格的來源白名單，僅允許授權域名進行資源請求。
• 內容安全策略 (CSP)：建議宿主系統配置 CSP 頭，允許從 *.caas-system.com 加載腳本。

11. 常見問題排查 (Troubleshooting)

Q: 為什麼我的 CSS 無法改變模組內部的按鈕顏色？

• A: 因為 Shadow DOM 的隔離特性，一般的 CSS 選擇器無法進入組件內部。請務必使用 README 第 5.1 節 提到的 CSS Variables 進行變更。

Q: 圖表在縮放視窗時沒有自動適應大小？

• A: 請檢查組件的父容器是否設定了確定的寬度或 flex: 1。若父容器寬度為 0 或 auto，Recharts 引擎將無法正確計算佈局。

Q: 出現 customElements.define 重複定義錯誤？

• A: 模組內部已具備冪等性檢查，但若您在頁面中重複加載了不同版本的 main.js，仍可能發生衝突。請確保頁面中僅存在一個版本的 CaaS 引用。

12. 聯絡與支援

若在集成過程中遇到任何問題，請透過開發者門戶提交工單。