Commons Vue Library

這是一個 Vue 3 公用元件/函式庫，提供常用的 UI 元件、API 服務、權限管理等功能，基於 TypeScript 和 Bootstrap 5。

功能概述

• API 服務: 封裝 Axios，提供統一的 API 呼叫介面，支持身份驗證、檔案下載等。
• 權限管理: 提供角色權限映射和選單權限控制。
• UI 元件: 包括表格、表單欄位、警示、載入動畫等 Vue 元件。
• 指令: 提供權限控制、日期格式化、表單驗證等 Vue 指令。
• 模型與工具: 提供資料模型、工具函式等。

安裝

npm install ch3chi-commons-vue

相依套件

此函式庫依賴以下套件，請確保您的專案已安裝：

• Vue 3
• Bootstrap 5
• Axios
• Vee-Validate
• Yup
• Day.js
• Lodash
• 其他請參考 package.json 的 peerDependencies

使用方式

APIService 範例

import { ApiService, ApiRequest } from 'ch3chi-commons-vue';

// 註冊多個 API 端點
ApiService.registerEndpoints({
  getUser: { path: '/user/{id}', method: 'GET' },
  createUser: { path: '/user', method: 'POST' }
});

// 新增單一 API 端點
ApiService.addEndpoints('deleteUser', { path: '/user/{id}', method: 'DELETE' });

// 呼叫 API
const req = new ApiRequest({
  endpointKey: 'getUser',
  pathParam: { id: 123 }
});
ApiService.call(req).then(resp => {
  if (resp.isOk()) {
    console.log('取得使用者資料:', resp.data);
  } else {
    console.error('API 錯誤:', resp.message);
  }
});

// 下載檔案
const downloadReq = new ApiRequest({
  endpointKey: 'exportUser',
  queryParam: { id: 123 },
  downloadFileName: 'user_123.xlsx'
});
ApiService.download(downloadReq).then(() => {
  console.log('檔案下載完成');
}).catch(err => {
  console.error('下載失敗:', err);
});

AuthorizationService 範例

import { AuthorizationService, CMenuItem, MenuItem } from 'ch3chi-commons-vue';

// 設定角色權限映射
AuthorizationService.rolePermissionMap = {
  admin: ['user.read', 'user.write', 'menu.view'],
  user: ['user.read', 'menu.view']
};

// 設定選單定義映射
AuthorizationService.menuDefineMap = {
  default: [
    { title: '使用者管理', permission: 'user.read' },
    { title: '系統設定', permission: 'user.write' }
  ]
};

// 檢查角色是否有某權限
const hasWrite = AuthorizationService.hasPermissionByRole(['user'], 'user.write');
console.log('user 是否有寫入權限:', hasWrite);

// 取得符合權限的選單
const menu = AuthorizationService.provideMenuByPermission({
  roleCode: 'user',
  permissions: ['user.read', 'menu.view']
});
console.log('使用者可見選單:', menu);

UI 元件範例

CTable 表格元件

<template>
  <CTable
    :columns="columns"
    :data-list="dataList"
    :query-param="queryParam"
    @page-change="handlePageChange"
    @sort-change="handleSortChange"
  />
</template>

<script setup lang="ts">
import { CTable, CTableColumn } from 'ch3chi-commons-vue';

const columns: CTableColumn[] = [
  { key: 'name', label: '名稱', sortable: true },
  { key: 'email', label: '電子郵件' }
];

const dataList = [
  { name: 'John Doe', email: '[email protected]' }
];

const queryParam = reactive({
  page: 1,
  size: 10,
  sort: []
});
</script>

表單欄位元件

<template>
  <CTextInputFormField
    v-model="formData.name"
    label="名稱"
    :validation-rules="{ required: true }"
  />
  <CDateFormField
    v-model="formData.birthDate"
    label="生日"
  />
</template>

<script setup lang="ts">
import { CTextInputFormField, CDateFormField } from 'ch3chi-commons-vue';

const formData = reactive({
  name: '',
  birthDate: null
});
</script>

其他元件

• CAlert: 警示訊息元件
• CBSToast: Toast 通知
• CGlobalSpinner: 全域載入動畫

指令範例

權限指令

<template>
  <button v-permission="'user.write'">編輯使用者</button>
</template>

<script setup lang="ts">
import { PermissionDirective } from 'ch3chi-commons-vue';
</script>

日期格式化指令

<template>
  <span v-date-formatter="dateValue"></span>
</template>

<script setup lang="ts">
import { vdDateFormatter } from 'ch3chi-commons-vue';
</script>

文件

請參考以下文件以獲取詳細資訊：

• API Service 使用指南
• CTable 樣式配置指南
• 權限管理指南
• 其他文件請參考 doc/ 目錄

開發與建置

# 安裝依賴
npm install

# 建置
npm run vite-build

# 發行新版本
npm run release

授權

此專案採用 MIT 授權。