跳至主要内容

元件總覽

內容來源

本頁內容源自 appfuse-web/lib/components/README.md，如有差異以 README 為準。

AppFuse Web 提供一套完整的企業級 React 元件庫，所有元件皆可透過 @appfuse/appfuse-web 匯入。

匯入路徑

// UI 元件（按鈕、表格、下拉選單等）
import { Button, DataTable, Dropdown } from '@appfuse/appfuse-web/components'

// 表單元件（Input、Select、Checkbox 等）
import { Input, Select, Checkbox } from '@appfuse/appfuse-web/form'

// 表單驗證
import { schema, validatorResolver } from '@appfuse/appfuse-web/form/validator'

// 訊息系統
import { prompt, MessageToast, MessageDialog } from '@appfuse/appfuse-web/messaging'

// Hooks
import { useTimeout, useInfiniteList } from '@appfuse/appfuse-web/hooks'

// 工具函數
import { cn, time, logger, i18n } from '@appfuse/appfuse-web/utils'

元件分類

表單元件

匯入路徑：@appfuse/appfuse-web/form

用於資料輸入和表單處理，整合 react-hook-form。

文字輸入

元件	說明	Storybook
`Input`	單行文字輸入，支援 text / number / date / email / password	查看
`Textarea`	多行文字輸入，自動調整高度	查看
`TagInput`	標籤輸入，多值輸入、可創建新標籤	查看
`RichTextEditor`	富文本編輯器，基於 Slate.js	查看

選擇輸入

元件	說明	Storybook
`Select`	下拉選單，支援單選/多選、搜尋、創建	查看
`Checkbox` / `CheckboxGroup`	核取方塊，支援布林/多選模式	查看
`Radio` / `RadioGroup`	單選按鈕	查看
`Switch`	開關切換	查看

檔案輸入

元件	說明	Storybook
`FileInput`	檔案上傳，支援拖放、多檔、驗證	查看
`MediaInput`	媒體上傳，支援圖片/影片預覽、裁切	查看

表單驗證

匯入路徑：@appfuse/appfuse-web/form/validator

匯出	說明
`schema`	輕量驗證 Schema 建構器（~5KB，替代 Zod）
`validatorResolver`	react-hook-form resolver
`mapViolationsToFormErrors`	後端違例轉換為表單錯誤
`createServerErrorHandler`	伺服器錯誤處理器

詳細用法請參閱表單元件指南。

動作元件

匯入路徑：@appfuse/appfuse-web/components

元件	說明	Storybook
`Button`	按鈕，支援 variant / color / density / loading / confirmation	查看

資料顯示

匯入路徑：@appfuse/appfuse-web/components

元件	說明	Storybook
`DataTable`	資料表格，傳統分頁模式	查看
`VirtualTable`	虛擬化表格，無限捲動模式	查看
`Icon`	圖示，Lucide React 包裝	查看
`MediaViewer`	媒體查看器，圖片/影片檢視	查看
`AuthImage`	認證圖片，帶 Token 的圖片載入	查看

圖表元件

匯入路徑：@appfuse/appfuse-web/components

基於 @nivo 的圖表元件，支援主題配色。

元件	說明	Storybook
`LineChart`	折線圖	查看
`AreaChart`	面積圖	查看
`BarChart`	長條圖	查看
`PieChart`	圓餅圖	查看
`RadarChart`	雷達圖	查看
`ScatterPlot`	散佈圖	查看
`FunnelChart`	漏斗圖	查看
`ParallelCoordinates`	平行座標圖	查看

版面配置

匯入路徑：@appfuse/appfuse-web/components

元件	說明	Storybook
`CollapsibleCard`	可折疊卡片	查看

導航元件

匯入路徑：@appfuse/appfuse-web/components

元件	說明	Storybook
`Tabs`	索引標籤，支援鍵盤導航	查看

覆蓋層元件

匯入路徑：@appfuse/appfuse-web/components

元件	說明	Storybook
`Dropdown`	下拉選單，Compound Component 模式	查看

回饋元件

匯入路徑：@appfuse/appfuse-web/components（元件）/ @appfuse/appfuse-web/messaging（服務）

元件	說明	Storybook
`Toast`	快顯通知（低階元件）	查看
`Dialog`	對話框（低階元件）	查看
`MessageToast`	全域通知容器（搭配 prompt API）	—
`MessageDialog`	全域對話框容器（搭配 prompt API）	—

詳細用法請參閱訊息系統指南。

Hooks

匯入路徑：@appfuse/appfuse-web/hooks

Hook	說明
`useTimeout`	setTimeout 包裝，自動清理
`useInterval`	setInterval 包裝，自動清理
`useFloatingPortal`	浮動定位（Dropdown / Tooltip 用）
`useInfiniteList`	TanStack Query 無限捲動

工具函數

匯入路徑：@appfuse/appfuse-web/utils

模組	說明
`createHttpClient` / `HttpClientProvider` / `useHttpClient`	HTTP 客戶端（axios 封裝）
`i18n` / `useTranslation` / `I18nProvider`	國際化
`time` / `toDateString`	日期時間處理（date-fns 封裝）
`logger`	日誌系統（loglevel 封裝）
`cn`	CSS 類別合併（clsx + tailwind-merge）
`cookie`	Cookie 操作
`environ`	環境配置
`browser`	瀏覽器偵測
`numeral`	數字格式化
`template`	字串模板
`filter`	RSQL/FIQL 查詢建構

詳細用法請參閱工具函數指南。

互動式展示

所有元件都可以在 Storybook 中互動式瀏覽和測試。

共用屬性

大部分元件支援以下共用屬性，確保 API 一致性：

屬性	說明	適用元件
`label`	浮動標籤（自動翻譯）	所有 Data Input、Form 元件
`variant`	外觀變體（`bordered` / `ghost`）	Input, Select, TagInput, RichTextEditor, MediaInput, FileInput
`density`	間距密度（`compact` / `comfortable`）	所有 Data Input 元件
`color`	顏色變體（8 種語意色）	所有 Data Input 元件、Button
`disabled`	停用狀態	所有表單元件
`readOnly`	唯讀模式	所有表單元件

設計原則

可存取性 (a11y)：所有元件遵循 WCAG 2.1 AA 標準
密度支援：compact（40px）和 comfortable（48px，預設）兩種密度
顏色變體：支援 8 種 DaisyUI 語意顏色（default / primary / secondary / accent / info / success / warning / error）
主題化：支援 DaisyUI 主題切換（含深色模式），禁止使用 dark: prefix 或硬編碼顏色
TypeScript：完整的型別定義與 JSDoc

匯入路徑
元件分類
Hooks
工具函數
互動式展示
共用屬性
設計原則