jobdone-ui-core

PrimeVue + Tailwind CSS 共用元件庫與 Design Tokens for Jobdone Enterprise。

目錄

• 安裝
• Peer Dependencies
• 共用函式 (Common)
  • 格式化函式 — format.js
  • SweetAlert 彈窗 — sweetalert.js
• 共用元件 (Components)
  • ProjectNavbar
  • LoadingOverlay
  • Paginate
  • GradientButton
• 樣式系統 (Style)
  • 樣式檔案總覽
  • 樣式入口 — index.css
  • Design Tokens — token.css
  • Tailwind 主題 — tailwind-theme.css
  • 全域基礎樣式 — projectBase.css
  • 工具類別 — utilities.css
  • PrimeVue Token — primevue-token.css
  • PrimeVue 覆寫 — primevue-overrides.css
  • 元件專用樣式 — components/
  • 完整 CSS Layer 載入範例

安裝

npm install jobdone-ui-core

樣式設定（必要）

安裝後，請在專案的主要 CSS 入口檔案中加入以下引入，確保元件的 Tailwind utility classes 與 Design Tokens 能正確載入：

@import "tailwindcss";
@import "jobdone-ui-core/style/index.css";

為什麼需要這步？ 本套件的元件使用了 Tailwind CSS utility classes（如 bg-gray-900、flex、text-gray-500 等）。Tailwind CSS v4 預設不會掃描 node_modules 內的檔案，因此需要透過 @source 指令讓 Tailwind 掃描本套件的元件，才能產生正確的樣式。style/index.css 已包含所需的 @source 設定及 Design Tokens。

Peer Dependencies

使用此套件前，請確保專案已安裝以下依賴：

| 套件 | 版本 | |------|------| | vue | ^3.5.0 | | primevue | ^4.0.0 | | @primeuix/themes | ^2.0.0 | | tailwindcss | ^4.0.0 | | @tailwindcss/vite | ^4.0.0 | | axios | ^1.0.0 |

共用函式 (Common)

匯入方式

可透過套件主入口或子路徑匯入：

// 從主入口匯入
import { formatDate, formatDT, formatThousands } from 'jobdone-ui-core'
import { successAlert, confirmAlert, errorAlert } from 'jobdone-ui-core'

// 從子路徑匯入
import { formatDate, formatDT, formatThousands } from 'jobdone-ui-core/common/format'
import { successAlert, confirmAlert, dangerConfirmAlert, errorAlert, hintAlert } from 'jobdone-ui-core/common/sweetalert'

格式化函式 — format.js

基於 dayjs 的日期與數字格式化工具。

formatDate(value)

將日期值格式化為 YYYY-MM-DD。

formatDate('2026-03-23T10:30:00') // '2026-03-23'
formatDate(null)                   // null

formatDT(value)

將日期值格式化為 YYYY-MM-DD HH:mm:ss。

formatDT('2026-03-23T10:30:00') // '2026-03-23 10:30:00'

formatThousands(number)

將數字加上千分位分隔。

formatThousands(1234567) // '1,234,567'

SweetAlert 彈窗 — sweetalert.js

基於 sweetalert2 封裝的彈窗函式，統一視覺風格。所有函式皆回傳 Promise。

successAlert(title, message?)

成功提示（綠色勾勾圖示），確認按鈕為 Primary 色 #647AF1。

await successAlert('儲存成功', '資料已更新')

confirmAlert(title, message?)

確認對話框（警告圖示），包含「確定」與「取消」按鈕。

const result = await confirmAlert('確定要送出嗎？')
if (result.isConfirmed) {
  // 使用者按下確定
}

dangerConfirmAlert(title, message?)

危險確認對話框，確認按鈕為紅色 #DC3D4E，適用於刪除等破壞性操作。

const result = await dangerConfirmAlert('確定要刪除？', '此操作無法復原')
if (result.isConfirmed) {
  // 執行刪除
}

errorAlert(title, message?)

錯誤提示（紅色叉叉圖示）。

errorAlert('操作失敗', '請稍後再試')

hintAlert(title, message?)

提示警告（黃色警告圖示）。

hintAlert('注意', '您尚未填寫必填欄位')

共用元件 (Components)

匯入方式

// 從主入口匯入
import { ProjectNavbar, LoadingOverlay, Paginate, GradientButton } from 'jobdone-ui-core'

// 從子路徑匯入
import ProjectNavbar from 'jobdone-ui-core/components/ProjectNavbar.vue'
import LoadingOverlay from 'jobdone-ui-core/components/LoadingOverlay.vue'
import Paginate from 'jobdone-ui-core/components/Paginate.vue'
import GradientButton from 'jobdone-ui-core/components/GradientButton.vue'

ProjectNavbar

專案導覽列元件，包含主選單、功能選單下拉、使用者選單及專案資訊列。

Props

| Prop | 類型 | 必填 | 說明 | |------|------|------|------| | arrowBackLink | String | 是 | 返回首頁的連結 | | projectId | String | 是 | 專案 ID | | projectInfo | String \| Object | 是 | 專案資訊（傳入 URL 字串會自動 fetch，或直接傳入物件） | | projectApps | String \| Object | 是 | 功能選單資料（同上） | | activeClientId | String | 否 | 當前激活的功能 Client ID | | rootDomain | String | 是 | 網站根網域 | | userId | String | 是 | 使用者帳號 | | userPicture | String | 是 | 使用者頭像圖片 URL | | logOutLink | String | 否 | 登出連結 | | logoutParams | String | 否 | 登出參數 |

使用範例

<ProjectNavbar
  arrow-back-link="/dashboard"
  project-id="123"
  :project-info="projectInfoObj"
  :project-apps="projectAppsObj"
  active-client-id="app-001"
  root-domain="https://example.com"
  user-id="[email protected]"
  user-picture="/img/avatar.png"
  log-out-link="/logout"
>
  <!-- slot: 專案資訊列右側自訂內容 -->
  <span>自訂區域</span>
</ProjectNavbar>

LoadingOverlay

全頁或區域載入遮罩，基於 vue-loading-overlay。

Props

| Prop | 類型 | 預設值 | 說明 | |------|------|--------|------| | isActive | Boolean | false | 是否顯示 loading | | loader | String | 'bars' | 載入動畫類型 | | colors | String | '#647AF1' | 動畫顏色 | | backgroundColor | String | '#000' | 遮罩背景色 | | opacity | Number | 0.5 | 遮罩透明度 | | fullPage | Boolean | true | 是否全頁遮罩 |

使用範例

<script setup>
import { ref } from 'vue'
import { LoadingOverlay } from 'jobdone-ui-core'

const isLoading = ref(false)

async function fetchData() {
  isLoading.value = true
  try {
    // ... 非同步操作
  } finally {
    isLoading.value = false
  }
}
</script>

<template>
  <LoadingOverlay :is-active="isLoading" />
</template>

Paginate

分頁元件，使用 PrimeVue Button 實作，支援首頁/末頁、上下頁、頁碼範圍與省略號。

Props

| Prop | 類型 | 預設值 | 說明 | |------|------|--------|------| | currentPage | Number | 1 | 當前頁碼 | | totalPages | Number | 1 | 總頁數 | | pageRange | Number | 5 | 顯示的頁碼按鈕數量 | | containerClass | String | '' | 容器額外 CSS class | | pageItemClass | String | '' | 頁碼按鈕額外 CSS class | | clickHandler | Function | null | 點擊回呼（向後相容） |

Events

| 事件 | 參數 | 說明 | |------|------|------| | to-page | pageNum: number | 頁碼變更時觸發 |

使用範例

<script setup>
import { ref } from 'vue'
import { Paginate } from 'jobdone-ui-core'

const currentPage = ref(1)
const totalPages = ref(10)

function onPageChange(page) {
  currentPage.value = page
  // 重新載入資料...
}
</script>

<template>
  <Paginate
    :current-page="currentPage"
    :total-pages="totalPages"
    :page-range="5"
    @to-page="onPageChange"
  />
</template>

可透過 containerClass 切換尺寸：

<!-- 小型分頁 -->
<Paginate container-class="pagination-sm" ... />

<!-- 大型分頁 -->
<Paginate container-class="pagination-lg" ... />

GradientButton

漸層動畫按鈕，基於 PrimeVue Button 封裝，帶有流動式漸層背景動畫效果。

Props

| Prop | 類型 | 預設值 | 說明 | |------|------|--------|------| | label | String | '' | 按鈕文字 | | icon | String | null | 圖示 class（PrimeIcons 等） | | iconPos | String | 'left' | 圖示位置（left / right / top / bottom） | | disabled | Boolean | false | 是否禁用 | | loading | Boolean | false | 是否顯示 loading 狀態 | | size | String | null | 按鈕尺寸（'small' / 'large'） | | severity | String | null | PrimeVue 語意色彩 | | rounded | Boolean | false | 是否圓角 | | class | String / Array / Object | '' | 額外 CSS class | | gradientStart | String | var(--cyan) | 漸層起始色 | | gradientMiddle | String | var(--purple) | 漸層中間色 | | gradientEnd | String | var(--cyan) | 漸層結束色 | | animationDuration | Number / String | 3 | 動畫週期（秒） |

Events

| 事件 | 說明 | |------|------| | click | 按鈕點擊事件 |

使用範例

<script setup>
import { GradientButton } from 'jobdone-ui-core'
</script>

<template>
  <!-- 基本用法 -->
  <GradientButton label="送出" @click="handleSubmit" />

  <!-- 自訂漸層色 -->
  <GradientButton
    label="特殊按鈕"
    gradient-start="#ff6b6b"
    gradient-middle="#feca57"
    gradient-end="#ff6b6b"
    :animation-duration="5"
  />

  <!-- 使用 slot 自訂內容 -->
  <GradientButton>
    <span class="material-icons mr-1">rocket_launch</span>
    啟動
  </GradientButton>
</template>

樣式系統 (Style)

樣式檔案總覽

style/
├── index.css              # 📦 樣式入口（@source + token + theme + utilities 一站式引入）
├── token.css              # 🎨 Design Tokens — 所有色碼、語意色、間距、字型等 CSS Variables
├── tailwind-theme.css     # 🎨 Tailwind v4 @theme — 將 token.css 橋接為 Tailwind utility classes
├── tailwind.config.ts     # ⚙️ Tailwind 非顏色設定（目前未啟用，保留參考）
├── projectBase.css        # 📐 全域 Reset & Layout Primitives
├── utilities.css          # 🔧 自訂 Utility Classes
├── primevue-token.css     # 🎯 PrimeVue 元件 Token 覆寫
├── primevue-overrides.css # 🎨 PrimeVue 元件樣式覆寫
└── components/            # 📦 第三方/特定元件樣式覆寫
    ├── filepond.css       #   FilePond 上傳元件
    ├── loading-overlay.css #   vue-loading-overlay
    ├── outline-pill.css   #   PrimeVue Tag 客製 outline 膠囊
    ├── sidebar-list.css   #   側邊選單 list-group
    └── sweetalert2.css    #   SweetAlert2 對話框

樣式入口 — index.css

index.css 是消費端專案引入本套件樣式的統一入口，一次完成以下工作：

1. @source — 告知 Tailwind v4 掃描本套件的 components/ 和 common/ 目錄，產生所需的 utility classes
2. Design Tokens — 載入 token.css（所有色碼、語意色、間距、字型等 CSS Variables）
3. Tailwind @theme — 載入 tailwind-theme.css（將 token 橋接為 Tailwind utility classes）
4. Utility Classes — 載入 utilities.css（flex-center、scrollbar、text-overflow 等）

為什麼需要 @source？

Tailwind CSS v4 預設不掃描 node_modules。當消費端專案透過 npm 安裝本套件後，元件內使用的 Tailwind class（如 bg-gray-900、flex、text-gray-500）不會被 Tailwind 編譯產出，導致元件樣式失效。

@source 指令顯式註冊需掃描的目錄，讓 Tailwind 能偵測到套件內的 class 並正確產出樣式。

最簡引入

消費端的主 CSS 入口只需兩行：

@import "tailwindcss";
@import "jobdone-ui-core/style/index.css";

也可以使用 package.json exports 的快捷路徑：

@import "tailwindcss";
@import "jobdone-ui-core/style";

如果專案需要 CSS Layer 細分控制（搭配 PrimeVue 等），請參考下方 完整 CSS Layer 載入範例。

Design Tokens — token.css

所有色碼、語意色、間距、字型等原始 CSS Variables 的定義源頭。

基礎色彩

| 變數 | 色碼 | 說明 | |------|------|------| | --purple | #647af1 | Primary 主色 | | --blue | #4f94ff | 藍色 | | --indigo | #1a62e3 | 靛藍 | | --pink | #ed7aad | 粉紅 | | --red | #dc3d4e | 紅色 | | --orange | #fca053 | 橘色 | | --yellow | #f8c945 | 黃色 | | --green | #47b684 | 綠色 | | --teal | #01b9b9 | 藍綠 | | --cyan | #24bce7 | 青色 |

每個色彩皆有 50–950 色階，例如 --purple-50 至 --purple-950。

語意色

| 變數 | 對應色 | 用途 | |------|--------|------| | --primary | --purple | 主色調 | | --secondary | --gray-600 | 次要色 | | --success | --green | 成功 | | --info | --cyan | 資訊 | | --warning | --yellow | 警告 | | --danger | --red | 危險/錯誤 | | --light | --gray-100 | 淺色 | | --dark | --gray-900 | 深色 |

Tailwind 主題 — tailwind-theme.css

將 token.css 的變數橋接至 Tailwind v4 的 @theme 指令，使其可作為 Tailwind utility classes 使用。

<!-- 可直接使用 token 中的色彩 -->
<div class="bg-primary text-white">Primary 背景</div>
<div class="text-gray-600">次要文字</div>
<div class="border-danger">危險邊框</div>
<div class="bg-success-subtle text-success-emphasis">成功提示區塊</div>

全域基礎樣式 — projectBase.css

HTML/Body 層級的 Reset 及全站 Layout Primitives。

• [v-cloak] 隱藏（Vue 載入前不閃爍）
• html, body 基礎字型、行高、背景色設定
• a 連結 reset（移除底線）
• .mobile-forbidden — 行動裝置禁止使用畫面（< 992px 全螢幕覆蓋）
• .a-reset-color — 連結顏色繼承父層
• ul.list-reset / ol.list-reset — 清除 list 預設樣式

工具類別 — utilities.css

常用的 Utility Classes，對應原 SCSS Mixins。

Layout

| Class | 說明 | |-------|------| | .flex-center | Flex 水平 + 垂直置中 | | .flex-center-col | Flex 垂直方向置中 | | .position-center | Absolute 定位於父層正中央 | | .position-full | Absolute 填滿父層 |

Text

| Class | 說明 | |-------|------| | .text-overflow | 單行文字溢位省略號 | | .text-line-clamp-{1~5} | 多行文字溢位省略號（1 至 5 行） | | .text-with-icon | 文字搭配 icon 垂直對齊 |

Icon

| Class | 說明 | |-------|------| | .material-icons | Material Icons 基礎（24px） | | .material-icons.icon-14 | 14px icon | | .material-icons.icon-18 | 18px icon | | .material-icons.icon-24 | 24px icon | | .material-icons.icon-28 | 28px icon | | .material-icons.icon-32 | 32px icon |

Interactive

| Class | 說明 | |-------|------| | .hover-border | Hover 時顯示 focus ring | | .active-border | 常駐 focus ring 效果 |

Scrollbar

| Class | 說明 | |-------|------| | .scrollbar | 自訂垂直捲軸樣式（hover 變 primary 色） | | .scrollbar-x | 自訂水平捲軸樣式 |

PrimeVue Token — primevue-token.css

將 token.css 的色彩推入 PrimeVue 的 --p-* 命名空間，覆寫 Aura 預設色。

映射關係：

| PrimeVue Token | 對應來源 | |----------------|----------| | --p-primary-* | --purple-* | | --p-success-* | --green-* | | --p-warn-* | --yellow-* | | --p-danger-* | --red-* | | --p-info-* | --cyan-* |

PrimeVue 覆寫 — primevue-overrides.css

針對 PrimeVue 元件的結構性樣式調整：

• Button — Link Button 移除內距
• DataTable — 表頭字級與 th-center 置中
• Menu — Hover 色彩（primary / danger）、子選單標題字級
• Tab — 上方圓角

元件專用樣式 — components/

filepond.css

FilePond 上傳元件的客製化樣式：虛線邊框、標籤排版及面板背景色。

@import "jobdone-ui-core/style/components/filepond.css";

loading-overlay.css

vue-loading-overlay 的基礎樣式定義。

outline-pill.css

PrimeVue <Tag> 元件的 outline 膠囊樣式變體。

<Tag class="outline-pill-blue" value="進行中" rounded />
<Tag class="outline-pill-red" value="已逾期" rounded />
<Tag class="outline-pill-green" value="已完成" rounded />

可用色彩：blue、indigo、purple、pink、red、orange、yellow、green、teal、cyan、black、gray、gray-dark

sidebar-list.css

側邊欄選單 .list-group-aside 樣式，包含 active/hover 狀態與漸層背景效果。

sweetalert2.css

SweetAlert2 對話框客製化：z-index、字型、按鈕排列、取消按鈕色彩。

@import "jobdone-ui-core/style/components/sweetalert2.css";

完整 CSS Layer 載入範例

若專案使用 PrimeVue 並需要 CSS @layer 控制優先級，建議在 global.css 中按以下順序引入：

/* 定義 layer 順序（越後面優先級越高） */
@layer base, primevue, tokens, primevue-tokens, utilities, overrides;

/* Tailwind CSS */
@import "tailwindcss";
@import "tailwindcss-primeui";

/* ✅ 一站式引入：@source（掃描元件）+ token + theme + utilities */
@import "jobdone-ui-core/style/index.css";

/* Base */
@import "jobdone-ui-core/style/projectBase.css" layer(base);

/* PrimeVue Tokens */
@import "jobdone-ui-core/style/primevue-token.css" layer(primevue-tokens);
@import "primeicons/primeicons.css";

/* Overrides（依需求引入） */
@import "jobdone-ui-core/style/primevue-overrides.css" layer(overrides);
@import "jobdone-ui-core/style/components/sidebar-list.css" layer(overrides);
@import "jobdone-ui-core/style/components/sweetalert2.css" layer(overrides);
@import "jobdone-ui-core/style/components/outline-pill.css" layer(overrides);
@import "./custom.css" layer(overrides);

| Layer | 優先級 | 用途 | |-------|--------|------| | base | 1（最低） | 全域 Reset、HTML 基礎樣式 | | primevue | 2 | PrimeVue 元件預設樣式（自動注入） | | tokens | 3 | Design Tokens 與 Tailwind theme | | primevue-tokens | 4 | 覆寫 PrimeVue 元件 Token | | utilities | 5 | 工具類別樣式 | | overrides | 6（最高） | 最終覆寫、專案客製化 |

更完整的樣式遷移說明請參閱 style/MIGRATION_GUIDE.md。