ch3chi-commons-vue 1.2.0 → 1.8.1

package/src/model/BaseListViewModel.ts

@@ -0,0 +1,392 @@
+import {QueryPage, QueryParameter} from "./QueryParameter";
+import {BaseFormDataModel} from "./BaseFormDataModel";
+import {
+  CTableColumn,
+  CTableColumnActionMeta,
+  CTableColumnActionType,
+  CTableColumnType
+} from "../components/CTableDefine";
+import {isReactive, reactive, toRaw} from "vue";
+import {Router} from "vue-router";
+import {useQueryFormDataStore} from "../stores/FormDataStore";
+import type {GlobalViewActions} from '../stores/ViewStore'
+import _ from "lodash";
+import {ApiResponse, ApiService} from "../api/ApiService";
+
+export interface ListApiEndpointMeta {
+  key: string; // API 端點鍵值
+  pathParam?: Record<string, any>;
+  dataListFinder?: (response: ApiResponse) => any[]; // 用於從 API 回應中提取資料列表的函式
+  dataParser: (dataItem: any) => any; // 用於解析 API 回
+}
+
+/**
+ * BaseListViewModel 是一個抽象類別，用於定義列表視圖模型的基本結構和行為。
+ */
+export abstract class BaseListViewModel<Q extends QueryParameter, V extends BaseFormDataModel> {
+  queryParam: Q; // 查詢參數
+  dataList: V[]; // 顯示資料
+  tableColumnArray: CTableColumn[]; // 表格欄位定義
+  tableActionFilter?: (action: CTableColumnActionMeta, dataItem?: V) => boolean; // 權限過濾函式
+  router?: Router;
+  storeAction?: GlobalViewActions;
+  enableQueryParamDefault?: boolean = false; // 是否啟用查詢參數的默認值
+  queryParamDefaultValues?: Record<string, any>; // 用於存儲屬性的默認值
+  saveOnQueryFormDataStore?: boolean = false; // 是否在查詢表單數據存儲中保存, 預設為 false
+  autoSearchOnClear?: boolean = true; // 是否啟用清除查詢條件後重新再呼叫search功能, 預設為 true
+
+  protected constructor(data: Partial<BaseListViewModel<Q, V>> = {}) {
+    this.tableColumnArray = this.useTableColumnArray() || [];
+    this.dataList = reactive([]);
+    this.queryParam = data.queryParam as Q;
+    this.onSortChange = this.onSortChange.bind(this);
+    this.onPageChange = this.onPageChange.bind(this);
+    // 設定 table action filter
+    this.tableActionFilter = data.tableActionFilter;
+    // 針對 tableColumnArray 設定 action 的過濾函式
+    if(this.tableActionFilter) {
+      this.tableColumnArray
+        .filter(col => col.type === CTableColumnType.Action)
+        .forEach((col) => {
+          col.actionFilter = (action: CTableColumnActionMeta, rowData?: V) => {
+            return this.tableActionFilter!(action, rowData);
+          }
+        });
+    }
+  }
+
+  /**
+   * 初始化方法
+   * @param options
+   */
+  init(options: {
+    router: Router,
+    storeAction?: GlobalViewActions
+  }) : this {
+    this.router = options.router;
+    this.storeAction = options.storeAction;
+    return this;
+  }
+
+  // ~ ----------------------------------------------------------
+  // ~ abstract methods or 可選的覆寫方法
+  // 抽象方法，子類別必須實現 或是 可選覆寫
+
+  /**
+   * 查詢列表的 API 端點元資料
+   */
+  queryListApiEndpointMeta() : ListApiEndpointMeta {
+    return {
+      key: '',
+      dataParser: (dataItem: any) => {}
+    }
+  }
+
+  /**
+   * 生成新增的 URL
+   * @returns {string} 新增頁面的 URL
+   */
+  abstract toCreateUrl(): string;
+
+  /**
+   * 生成編輯的 URL
+   * @param rowData 資料模型
+   * @returns {string} 編輯頁面的 URL
+   */
+  abstract toEditUrl(rowData: V): string;
+
+  /**
+   * 使用表格欄位定義
+   */
+  abstract useTableColumnArray(): CTableColumn[];
+
+  // ~ ----------------------------------------------------------
+  // ~ methods
+
+  /**
+   * 在組件掛載時調用的函式
+   */
+  async callOnMounted() {
+    this.readQueryParamFromStore();
+    await this.doSearch();
+  }
+
+  /**
+   * 儲存目前 query param 的屬性值為預設值
+   */
+  storeQueryDefaultValues(defValues: Record<string, any>) {
+    this.queryParamDefaultValues = defValues;
+    if(this.queryParam) {
+      _.merge(this.queryParam, _.cloneDeep(this.queryParamDefaultValues));
+    }
+    this.enableQueryParamDefault = true;
+  }
+
+  /**
+   * 重設查詢參數為預設值
+   */
+  resetToDefaultValues() {
+    if(_.isNil(this.queryParamDefaultValues) || _.isEmpty(this.queryParamDefaultValues)) {
+      return;
+    }
+    _.merge(this.queryParam, _.cloneDeep(this.queryParamDefaultValues));
+  }
+
+  /**
+   * 載入 API 回應資料
+   * @param response API 回應物件
+   * @param options 載入選項
+   */
+  loadApiResponse(response:ApiResponse, options: {
+    dataListFinder?: (response: ApiResponse) => any[],
+    parser?: (data: any) => V,
+  }) {
+    this.queryParam.loadResponse(response);
+    this.cleanDataList();
+    const dataList = _.invoke(options, 'dataListFinder', response) || _.get(response.data, 'items', response.data);
+    if(!_.isArray(dataList)) {
+      return;
+    }
+    let dataListToAdd = dataList as V[];
+    if(options.parser) {
+      dataListToAdd = dataList.map((dataItem,idx) => {
+        const b = options.parser!(dataItem);
+        this.setupRowNumber(b, idx);
+        return b;
+      });
+    }
+    this.addDataList(dataListToAdd);
+  }
+
+  /**
+   * 設定列號 根據當下的分頁資訊計算
+   * @param dataItem 當前資料項目
+   * @param dataIndex 當前資料的索引
+   */
+  setupRowNumber(dataItem: V, dataIndex: number) {
+    // __rowNumber
+    const pageObj = this.queryParam.page;
+    const pageIndex = pageObj?.pageIndex || 0;
+    const pageSize = pageObj?.pageSize || 0;
+    const rowNumber =  (pageObj?.offset ?? 0) + (dataIndex + 1);
+    dataItem.__rowNumber = rowNumber;
+    // 判斷是否為最後一頁的最後一筆
+    dataItem.__isLastAndLastPage = pageObj?.totalCount === rowNumber && pageObj?.totalPage === (pageIndex + 1);
+  }
+
+  /**
+   * 添加單筆資料到列表中
+   * @param dataToAdd
+   */
+  addData(dataToAdd: V) {
+    // 添加單筆資料到列表中
+    this.dataList.push(dataToAdd);
+  }
+
+  /**
+   * 添加多筆資料到列表中
+   * @param dataListToAdd
+   */
+  addDataList(dataListToAdd: V[]) {
+    // 添加多筆資料到列表中
+    this.dataList.push(...dataListToAdd);
+  }
+
+  /**
+   * 清除資料列表
+   */
+  cleanDataList() {
+    // 清除資料列表
+    this.dataList.splice(0, this.dataList.length);
+  }
+
+  /**
+   * 顯示錯誤訊息對話框
+   * @param content 錯誤訊息內容
+   * @param onOk 確認按鈕點擊事件
+   * @param onCancel 取消按鈕點擊事件
+   */
+  showConfirm(params: { content: string, onOk: () => void, onCancel?: () => void }) {
+    // 顯示確認對話框
+    this.storeAction?.showModalConfirm({
+      content: params.content,
+      onOk: params.onOk,
+      onCancel: params.onCancel
+    });
+  }
+
+  makeQueryParamStoreKey(): string {
+    return `R-${this.router?.currentRoute.value.name as string}`;
+  }
+
+  /**
+   * 將查詢參數保存到查詢表單數據存儲中
+   */
+  saveQueryParamToStore() {
+    if(!this.saveOnQueryFormDataStore) {
+      return;
+    }
+    const store = useQueryFormDataStore();
+    store.save(this.makeQueryParamStoreKey(), this.queryParam);
+  }
+
+  /**
+   * 從查詢表單數據存儲中讀取查詢參數
+   */
+  readQueryParamFromStore() {
+    if(!this.saveOnQueryFormDataStore) {
+      return;
+    }
+    const store = useQueryFormDataStore();
+    const savedData = store.getQueryParam(this.makeQueryParamStoreKey());
+    if(savedData) {
+      this.queryParam.load(savedData);
+    }
+  }
+
+  // ~ ----------------------------------------------------------
+  // ~ event handlers
+
+  /**
+   * 前往新增頁面
+   */
+  goToCreatePage() {
+    console.log('goToCreatePage', this.toCreateUrl());
+    if(!this.router) {
+      console.warn('Router is not initialized.');
+    }
+    this.router?.push({path: this.toCreateUrl()});
+  }
+
+  /**
+   * 執行搜尋操作
+   * 查詢時會將查詢參數保存到 store 中，並呼叫 API 獲取資料
+   */
+  async doSearch(event?: Event) {
+    const {key, dataListFinder, dataParser, pathParam} = this.queryListApiEndpointMeta();
+    if(_.isNil(key) || _.isEmpty(key)) {
+      return;
+    }
+
+    // 如果是從表單觸發的 doSearch，則把 pageIndex 重設為 0
+    if(event) {
+      if(this.queryParam.page) {
+        this.queryParam.page.pageIndex = 0;
+      }
+    }
+
+    // 儲存查詢參數到 store
+    this.saveQueryParamToStore();
+    // 呼叫 API 取得資料
+    const resp = await ApiService.call({
+      endpointKey: key,
+      pathParam: pathParam,
+      queryParam: this.queryParam.toQueryStringParam(),
+      postBody: this.queryParam.toPayload()
+    });
+    if(!resp.isOk()) {
+      return;
+    }
+    // 載入 API 回應資料
+    this.loadApiResponse(resp, {
+      parser: dataParser,
+      dataListFinder: dataListFinder
+    });
+  }
+
+
+  /**
+   * 處理清除事件
+   * 清除查詢參數，並根據設定決定是否重新執行搜尋
+   */
+  async doClear() {
+    // 清除查詢參數
+    this.queryParam.clear();
+    // 如果啟用預設值，則重設為預設值
+    if(this.enableQueryParamDefault) {
+      this.resetToDefaultValues();
+    }
+    // 視設定再次執行搜尋
+    if(this.autoSearchOnClear) {
+      await this.doSearch();
+    }
+  }
+
+  /**
+   * 處理排序變更事件
+   */
+  async onSortChange() {
+    await this.doSearch();
+  }
+
+  /**
+   * 處理分頁變更事件
+   * @param params
+   */
+  async onPageChange(params: QueryPage) {
+    await this.doSearch();
+  }
+
+  /**
+   * 處理 row action編輯事件
+   * @param rowMeta
+   */
+  async onColumnActionEdit(rowMeta: {actionType:CTableColumnActionType, rowData: V}) {
+    // 前往編輯頁面
+    await this.router?.push({path: this.toEditUrl(rowMeta.rowData)});
+  }
+
+  /**
+   * 刪除列後的處理
+   * @param rowData
+   */
+  async callOnAfterDeleteRow(rowData: V) {
+    // 刪除後的處理
+    // 如果是最後一頁的最後一筆，則把分頁往前一頁
+    if(rowData.__isLastAndLastPage) {
+      this.queryParam.page?.previous();
+    }
+    return await this.doSearch();
+  }
+
+  // ~ ----------------------------------------------------------
+}
+
+
+/**
+ * CheckableListViewModel 是一個抽象類別，擴展自 BaseListViewModel，提供了查找被選中資料的功能。
+ */
+export abstract class CheckableListViewModel<Q extends QueryParameter, V extends BaseFormDataModel> extends BaseListViewModel<Q, V> {
+
+  /**
+   * 查找所有被選中的資料
+   */
+  findCheckedData(): V[] {
+    // 查找所有被選中的資料
+    if (isReactive(this.dataList)) {
+      const rawDataList = toRaw(this.dataList)  as unknown as V[];
+      return rawDataList.filter((data) => {
+        return _.get(data, 'checked', false) === true;
+      });
+    }
+    return [];
+  }
+
+  /**
+   * 重置所有資料的選中狀態
+   */
+  resetCheckedData() {
+    // 重置所有資料的選中狀態
+    this.dataList.forEach((data) => {
+      _.set(data, 'checked', false);
+    })
+  }
+}
+
+
+// ~ ----------------------------------------------------------
+
+// 防止 Vite/rollup tree-shake 掉 type export
+export const __BaseListViewModelDefine__ = null as unknown as
+  ListApiEndpointMeta
+  ;

package/src/model/CBSModalViewModel.ts

@@ -0,0 +1,91 @@
+import {ref} from 'vue';
+import {Modal} from 'bootstrap';
+import {v4 as uuid} from 'uuid';
+
+export enum ICBSModalViewType {
+  Info = 'infoModal',
+  Form = 'formModal',
+  Table = 'tableModal',
+}
+
+export interface ICBSModalViewModel {
+  type: ICBSModalViewType;
+  title?: string;
+  config?: Record<string, any>; // 額外的配置選項與 Modal config 一致
+  onOpen?: () => void;
+  onClose?: () => void;
+}
+
+export class CBSModalViewModel {
+
+  modalInstance = ref<Modal | null>(null);
+  elt: HTMLElement | null = null;
+  type: ICBSModalViewType;
+  modalId: string;
+  labelId: string;
+  title?: string;
+  config?: Record<string, any>; // 額外的配置選項與 Modal config 一致
+  onOpen?: () => void;
+  onClose?: () => void;
+
+  constructor(data?: Partial<ICBSModalViewModel>) {
+    this.type = data?.type || ICBSModalViewType.Info;
+    this.modalId = `${this.type}-${uuid()}`;
+    this.labelId = `${this.modalId}-label`;
+    this.title = data?.title || this.defaultTitle();
+    this.onOpen = data?.onOpen;
+    this.onClose = data?.onClose;
+    this.config = Object.assign({
+      backdrop: 'static',
+      keyboard: false
+    }, data?.config);
+  }
+
+  defaultTitle(): string {
+    switch(this.type) {
+      case ICBSModalViewType.Info:
+        return '資訊';
+      case ICBSModalViewType.Form:
+        return '請填寫表單';
+      case ICBSModalViewType.Table:
+        return '請選擇';
+      default:
+        return '';
+    }
+  }
+
+  show() {
+    this.modalInstance.value?.show();
+  }
+
+  hide() {
+    this.modalInstance.value?.hide();
+  }
+
+
+  init({elt} : { elt: HTMLElement }) {
+    if(!elt) {
+      return;
+    }
+    this.elt = elt;
+    this.modalInstance.value = new Modal(this.elt, {
+      ...this.config
+    });
+
+    this.elt.addEventListener('show.bs.modal', () => {
+      this.onOpen?.();
+    });
+
+    this.elt.addEventListener('hidden.bs.modal', () => {
+      this.onClose?.();
+    });
+  }
+
+  unmount() {
+    if (this.modalInstance.value) {
+      this.modalInstance.value.dispose();
+      this.modalInstance.value = null;
+    }
+    this.elt = null;
+  }
+}

package/src/model/CFileDataModel.ts

@@ -0,0 +1,181 @@
+import _ from 'lodash';
+
+/**
+ * CFileDataModel.ts
+ * 用來定義檔案資料模型的介面和實作類別
+ */
+
+/**
+ * CFileDataModel 介面
+ */
+export interface CFileDataModel {
+  uid?: string; // 檔案 ID
+  originalFilename?: string; // 原始檔案名稱
+  name?: string; // 檔案名稱
+  mimeType?: string; // 檔案 MIME 類型
+  ext?: string; // 檔案類型(副檔名)
+  size?: number; // 檔案大小 (以位元組為單位)
+  url?: string; // 檔案 URL
+  createdAt?: Date; // 創建時間
+  fileObj?: File; // 檔案物件 native File object
+  icon?: string; // 檔案圖示 class (可選)
+  fontIcon?: string // font awesome icon 設定 (可選)
+  badgeClass?: string; // 檔案徽章樣式 (可選)
+  isAssociated?: boolean; // 是否已關聯到其他資料 (如新聞、活動等)
+  description?: string; // 檔案描述 (可選)
+}
+
+/**
+ * 用來標示檔案資料模型的實作類別
+ */
+export class CFileDataModel implements CFileDataModel {
+  uid?: string;
+  originalFilename?: string; // 原始檔案名稱
+  name?: string;
+  mimeType?: string; // 檔案 MIME 類型
+  ext?: string;
+  size?: number;
+  url?: string;
+  createdAt?: Date;
+  fileObj?: File;
+  icon?: string;
+  fontIcon?: string // font awesome icon 設定 (可選)
+  badgeClass?: string;
+  isAssociated?: boolean = false; // 是否已關聯到其他資料 (如新聞、活動等)
+  description?: string; // 檔案描述 (可選)
+
+  constructor(data?: Partial<CFileDataModel>) {
+    if (data) {
+      Object.assign(this, data);
+    }
+  }
+
+  init(): this {
+    if (_.isNil(this.name) && !_.isNil(this.originalFilename)) {
+      this.name = this.originalFilename;
+    }
+    if (this.originalFilename) {
+      const parts = _.split(this.originalFilename, '.');
+      if (parts.length > 1) {
+        this.ext = _.last(parts)?.toLowerCase();
+      }
+      // 基於副檔名來決定圖示與徽章樣式
+      switch (this.ext) {
+        case 'jpg':
+        case 'jpeg':
+        case 'png':
+        case 'gif':
+        case 'bmp':
+        case 'webp':
+        case 'svg':
+          this.icon = 'text-warning';
+          this.fontIcon = 'file-image';
+          this.badgeClass = 'bg-warning';
+          break;
+        case 'pdf':
+          this.icon = 'text-danger';
+          this.fontIcon = 'file-pdf';
+          this.badgeClass = 'bg-danger';
+          break;
+        case 'doc':
+        case 'docx':
+          this.icon = 'text-info';
+          this.fontIcon = 'file-word';
+          this.badgeClass = 'bg-info';
+          break;
+        case 'xls':
+        case 'xlsx':
+          this.icon = 'text-success';
+          this.fontIcon = 'file-excel';
+          this.badgeClass = 'bg-success';
+          break;
+        case 'mp4':
+        case 'mov':
+        case 'avi':
+        case 'wmv':
+        case 'webm':
+          this.icon = 'text-primary';
+          this.fontIcon = 'file-video';
+          this.badgeClass = 'bg-primary';
+          break;
+        default:
+          this.icon = 'text-secondary';
+          this.fontIcon = 'file-alt';
+          this.badgeClass = 'bg-secondary';
+          break;
+      }
+      this.isAssociated = true;
+    }
+    return this;
+  }
+}
+
+/**
+ * CPhotoDataModel 介面
+ */
+export class CPhotoDataModel extends CFileDataModel {
+  width?: number; // 圖片寬度
+  height?: number; // 圖片高度
+  loaded?: boolean = false; // 圖片是否已經載入完成
+
+  constructor(data?: Partial<CPhotoDataModel>) {
+    super(data);
+    if (data) {
+      Object.assign(this, data);
+    }
+  }
+}
+
+// ~ ----------------------------------------------------------
+
+export interface FileUploadProgress {
+  uid?: string; // 檔案 ID
+  name?: string; // 檔案名稱
+  progress?: number; // 上傳進度百分比 (0-100)
+  status?: 'ready' | 'uploading' | 'completed' | 'failed'; // 上傳
+  error?: string; // 錯誤訊息 (如果有的話)
+}
+
+export class FileUploadProgress implements FileUploadProgress {
+  uid?: string;
+  name?: string;
+  progress?: number = 0;
+  status?: 'ready' | 'uploading' | 'completed' | 'failed' = 'ready';
+  error?: string;
+
+  constructor(data?: Partial<FileUploadProgress>) {
+    if (data) {
+      Object.assign(this, data);
+    }
+  }
+
+  readyToUpload(): boolean {
+    return this.status === 'ready' || this.status === 'failed';
+  }
+
+  isShowProgress(): boolean {
+    return this.status === 'uploading';
+  }
+
+  isDone(): boolean {
+    return this.status === 'completed' || this.status === 'failed';
+  }
+
+  start() {
+    this.status = 'uploading';
+    this.progress = 0;
+  }
+
+  complete() {
+    this.status = 'completed';
+    this.progress = 100;
+  }
+
+  fail(errorMessage: string) {
+    this.status = 'failed';
+    this.error = errorMessage;
+    this.progress = 0;
+  }
+
+  // ~ ----------------------------------------------------------
+}

package/src/model/CImageViewModel.ts

@@ -0,0 +1,34 @@
+
+export class CImageViewModel {
+
+  onLoad?: (event: Event) => void; // 圖片加載完成
+  onError?: (event: Event | string) => void; // 圖片加載錯
+  placeholderImage = 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/w8AAgMBAp6Ff9cAAAAASUVORK5CYII=';
+
+  constructor(data?: Partial<CImageViewModel>) {
+    if(data) {
+      Object.assign(this, data);
+    }
+  }
+
+  onLoadHandler(event: Event) {
+    // 確保圖片載入完成後添加 loaded 類別
+    const imgElement = event.target as HTMLImageElement;
+    imgElement.classList.add('loaded');
+    // 如果有 onLoad 回調，則調用它
+    this.onLoad?.(event);
+  }
+
+  onErrorHandler(event: Event | string) {
+    const eventTarget = (event as Event).target;
+    if (eventTarget && eventTarget instanceof HTMLImageElement) {
+      // 避免無限迴圈的錯誤觸發
+      if (eventTarget.src !== this.placeholderImage) {
+        eventTarget.src = this.placeholderImage;
+        eventTarget.classList.add('loaded', 'error'); // 添加錯誤類別
+      }
+    }
+    // 如果有 onError 回調，則調用它
+    this.onError?.(event);
+  }
+}