ch3chi-commons-vue 1.2.0 → 1.8.1

package/src/components/CTableDefine.ts

@@ -0,0 +1,566 @@
+import {h, VNode} from 'vue';
+import _ from 'lodash';
+import {lodashExTools as eTool} from "../utils/CToolUtils";
+import dayjs from 'dayjs';
+import {v4 as uuidv4} from 'uuid';
+import CRowCheckBox from "./CRowCheckBox.vue";
+import {CheckableModel} from "../model/BaseFormDataModel";
+import CRowTextInput from "./CRowTextInput.vue";
+
+
+/**
+ * CTableColumnType 定義了表格欄位的類型
+ * - RowNumber: 行號類型
+ * - Text: 文字類型
+ * - Date: 日期類型
+ * - DateTime: 日期時間類型
+ * - Action: 操作類型
+ */
+export enum CTableColumnType {
+  RowNumber = 'rowNumber', // 行號類型
+  Text = 'text', // 文字類型
+  TextInput = 'textInput', // 文字輸入類型(可手動切換?)
+  Date = 'date', // 日期類型
+  DateRange = 'dateRange', // 日期範圍類型
+  DateTime = 'datetime', // 日期時間類型
+  Action = "action", // 操作類型
+  Checkbox = 'checkbox', // 複選框類型
+}
+
+/**
+ * CTableColumnActionType 定義了表格欄位的操作類型
+ */
+export enum CTableColumnActionType {
+  Edit = 'edit', // 編輯操作
+  Delete = 'delete', // 刪除操作
+  Review = 'review', // 審核操作
+  Vote = 'vote', // 投票操作
+  Check = 'check', // 勾選操作
+}
+
+/**
+ * CTableColumnActionParam 定義了表格欄位操作的參數
+ */
+export interface CTableColumnActionParam {
+  actionType: CTableColumnActionType, // 操作類型
+  rowData: Record<string, any>; // 當前行的數據
+  event?: Event; // 事件對象
+}
+
+export interface CTableColumnActionMeta {
+  actionType: CTableColumnActionType,
+  text?: string; // 按鈕顯示文字
+  cls?: string; // 按鈕樣式類名
+  icon?: string; // 按鈕圖示類名
+  onClick?: (p: CTableColumnActionParam) => void; // 點擊
+  emit?: (event: string, ...args: any[]) => void; // vue 事件發射器
+  permission?: string | string[]; // 權限字串
+}
+
+/**
+ * CTableColumnDefine 定義了表格欄位的屬性和行為
+ */
+export interface CTableColumnDefine {
+  id?: string; // 欄位唯一識別符 用在 vue key
+  type: CTableColumnType; // 欄位類型
+  idName?: string; // 欄位鍵名
+  dataName?: string; // 資料鍵名
+  dataNameList?: string[]; // 資料鍵名列表，僅在 type 為 DateRange 時有效
+  text: string; // 欄位顯示文字
+  defaultText?: string; // 默認欄位顯示文字
+  sortConfig?: {
+    sortable?: boolean; // 是否可排序
+    key?: string | string[]; // 排序鍵名
+    direction?: 'asc' | 'desc'; // 預設排序方向
+  } | undefined,
+  width?: string; // 欄位寬度, 例如 '150px' 或 '20%'，可選
+  outerWrapperCls?: string; // 外層容器 class 名稱，可選
+  align?: 'left' | 'center' | 'right'; // th 欄位對齊方式，可選
+  dataAlign?: 'left' | 'center' | 'right'; // td 資料對齊方式，可選
+  formatPattern?: string; // 格式化模式，例如日期格式 yyyy-MM-dd，使用 dayjs，可選
+  actionList?: CTableColumnActionMeta[] // 操作類型，僅在 type 為 Action 時有效，可選
+  actionFilter?: (action: CTableColumnActionMeta, dataItem?: any) => boolean; // 權限過濾函式
+  customRender?: (rowData: Record<string, any>) => string | HTMLElement | VNode; // 自定義
+  useHtml?: boolean; // 是否使用 HTML 渲染，預設為 false
+  useVNode?: boolean; // 是否使用 VNode 渲染，預設為 false
+  vNodeAttrs?: Record<string, any>; // VNode 屬性
+}
+
+
+/**
+ * CTableColumn 類別定義了表格欄位的屬性和行為
+ */
+export class CTableColumn implements CTableColumnDefine {
+  id?: string;
+  type: CTableColumnType = CTableColumnType.Text; // 欄位類型，默認為文字類型
+  idName?: string;
+  dataName?: string;
+  dataNameList?: string[]; // 資料鍵名列表，僅在 type 為 DateRange 時有效
+  text: string = ''; // 欄位顯示文字
+  defaultText?: string = ''; // 默認欄位顯示文字
+  sortConfig?: {
+    sortable?: boolean;
+    key?: string | string[];
+    direction?: 'asc' | 'desc';
+  };
+  width?: string;
+  outerWrapperCls?: string;
+  align?: 'left' | 'center' | 'right' = 'left'; // th 欄位對齊方式
+  dataAlign?: 'left' | 'center' | 'right' = 'left'; // td 資料對齊方式
+  formatPattern?: string;
+  actionList?: CTableColumnActionMeta[];
+  actionFilter?: (action: CTableColumnActionMeta, dataItem?: any) => boolean;
+  defaultRender?: (rowData: Record<string, any>) => string | HTMLElement | VNode; // 默認渲染函數
+  customRender?: (rowData: Record<string, any>) => string | HTMLElement | VNode;
+  useHtml: boolean = false;
+  useVNode: boolean = false;
+  vNodeAttrs?: Record<string, any>; // VNode 屬性
+
+  constructor(define: CTableColumnDefine) {
+    Object.assign(this, define);
+    if (_.isNil(this.id) || _.isEmpty(this.id)) {
+      // 如果沒有提供 id，則生成一個唯一的 id
+      this.id = uuidv4();
+    }
+    // Ensure sortConfig exists and provide backward compatibility for legacy top-level props
+    if (!this.sortConfig) {
+      this.sortConfig = { sortable: false };
+    }
+
+    this.defaultRender = this.makeDefaultRender();
+  }
+
+  // ~ ----------------------------------------------------------
+
+  static defaultIconMap: Record<CTableColumnActionType, string> = {
+    [CTableColumnActionType.Edit]: 'edit',
+    [CTableColumnActionType.Delete]: 'trash-alt',
+    [CTableColumnActionType.Review]: 'magnifying-glass',
+    [CTableColumnActionType.Vote]: 'magnifying-glass',
+    [CTableColumnActionType.Check]: '',
+  };
+
+  static defaultBtnClassMap: Record<CTableColumnActionType, string> = {
+    [CTableColumnActionType.Edit]: 'btn btn-link',
+    [CTableColumnActionType.Delete]: 'btn btn-default text-danger',
+    [CTableColumnActionType.Review]: 'btn btn-link',
+    [CTableColumnActionType.Vote]: 'btn btn-outline-primary',
+    [CTableColumnActionType.Check]: '',
+  };
+
+  // 允許使用者覆寫預設值
+  static configure(config: {
+    iconMap?: Partial<Record<CTableColumnActionType, string>>;
+    btnClassMap?: Partial<Record<CTableColumnActionType, string>>;
+  }) {
+    if (config.iconMap) {
+      this.defaultIconMap = { ...this.defaultIconMap, ...config.iconMap };
+    }
+    if (config.btnClassMap) {
+      this.defaultBtnClassMap = { ...this.defaultBtnClassMap, ...config.btnClassMap };
+    }
+  }
+
+  // ~ ----------------------------------------------------------
+
+  /**
+   * 渲染欄位內容
+   * @param rowData 當前行的數據
+   */
+  render(rowData: Record<string, any>): string | HTMLElement | VNode {
+    if (this.customRender) {
+      return this.customRender(rowData);
+    }
+
+    if (this.defaultRender) {
+      return this.defaultRender(rowData);
+    }
+
+    // 如果沒有自定義渲染，則返回該欄位的值
+    const value = eTool.getVal(rowData, this.dataName, '');
+    return String(value); // 返回字符串形式的值
+  }
+
+  /**
+   * 生成 th 的 class 名稱
+   */
+  thClass(): string {
+    // 根據欄位對齊方式生成 th 的 class 名稱
+    let cls = 'c-table-column';
+    if (this.align) {
+      cls += ` text-${this.align}`;
+    }
+    // 如果欄位可排序，添加 sortable 類名
+    if (this.sortConfig?.sortable) {
+      cls += ' c-sortable';
+    }
+    return cls;
+  }
+
+  /**
+   * 生成 td 的 class 名稱
+   */
+  tdClass(): string {
+    // 根據欄位對齊方式生成 td 的 class 名稱
+    let cls = 'c-table-column';
+    if (this.dataAlign) {
+      cls += ` text-${this.dataAlign}`;
+    }
+    return cls;
+  }
+
+  /**
+   * 處理欄位操作
+   * @private
+   */
+  private handleAction = new Proxy(
+    (actionMeta: CTableColumnActionMeta, rowData: Record<string, any>, event?: Event) => {
+      // 這裡可以根據 actionType 做不同處理
+      // 執行 callback 函數
+      actionMeta.onClick?.({
+        actionType: actionMeta.actionType,
+        rowData: rowData,
+        event: event
+      });
+      // fire action event 'table-action'
+      actionMeta.emit?.('table-action', actionMeta.actionType, rowData, event);
+    }, {});
+
+  // ~ ----------------------------------------------------------
+
+  /**
+   * 生成默認渲染函數
+   * @private
+   */
+  private makeDefaultRender(): (rowData: Record<string, any>) => string | HTMLElement | VNode {
+    // 根據欄位類型生成默認渲染函數
+    switch (this.type) {
+      case CTableColumnType.RowNumber:
+        return (rowData) => {
+          // 返回行號
+          const rowNumber = rowData['__rowNumber'] || 0; // 假設行號存儲在 rowData 中
+          return String(rowNumber || ''); // 行號從 1 開始
+        };
+      case CTableColumnType.Text:
+        return (rowData) => {
+          const value = eTool.getVal(rowData, this.dataName, this.defaultText);
+          // 轉換 newline 為 <br> 標籤
+          let newlineConverted = value;
+          if (this.useHtml && !_.isNil(value)) {
+            newlineConverted = String(value).replace(/\n/g, '<br/>');
+          }
+          return String(newlineConverted || '');
+        };
+
+      case CTableColumnType.Date:
+        if (!this.formatPattern) {
+          this.formatPattern = 'YYYY-MM-DD';
+        }
+        return (rowData) => {
+          const value = eTool.getVal(rowData, this.dataName, '');
+          if (_.isNil(value)) {
+            return '';
+          }
+          const dateObj = dayjs(value);
+          if (!dateObj.isValid()) {
+            return '';
+          }
+          return dateObj.format(this.formatPattern);
+        };
+      case CTableColumnType.DateTime:
+        if (!this.formatPattern) {
+          this.formatPattern = 'YYYY-MM-DD HH:mm'; // 默認日期時間格式
+        }
+        return (rowData) => {
+          const value = eTool.getVal(rowData, this.dataName);
+          // 使用 dayjs 格式化日期
+          if (_.isNil(value)) {
+            return '';
+          }
+          const dateObj = dayjs(value);
+          if (!dateObj.isValid()) {
+            return '';
+          }
+          return dateObj.format(this.formatPattern);
+        };
+      case CTableColumnType.DateRange:
+        if (!this.dataNameList || this.dataNameList.length !== 2) {
+          throw new Error('DateRange type requires dataNameList with exactly two items.');
+        }
+        if (!this.formatPattern) {
+          this.formatPattern = 'YYYY-MM-DD'; // 默認日期格式
+        }
+        return (rowData) => {
+          const startValue = eTool.getVal(rowData, this.dataNameList?.[0]);
+          const endValue = eTool.getVal(rowData, this.dataNameList?.[1]);
+          if (_.isNil(startValue) && _.isNil(endValue)) {
+            return '';
+          }
+          const showText = [];
+          if (!_.isNil(startValue)) {
+            showText.push(dayjs(startValue).format(this.formatPattern));
+          }
+          if (!_.isNil(endValue)) {
+            showText.push(dayjs(endValue).format(this.formatPattern));
+          }
+          return showText.join(' ~ ');
+        };
+      case CTableColumnType.Action:
+        this.useVNode = true;
+        return (rowData) => {
+          // 根據 action 集合中的操作類型生成按鈕 回傳使用 VNode
+          if (_.isNil(this.actionList) || _.isEmpty(this.actionList)) {
+            return '';
+          }
+          // 如果有 actionFilter，則過濾 actionList
+          let useActionList = this.actionList;
+          if (this.actionFilter) {
+            useActionList = this.actionList.filter(actionMetaItem => {
+              return this.actionFilter!(actionMetaItem, rowData);
+            });
+          }
+          // 生成按鈕 VNode 列表
+          const btnNodeList = useActionList.map(actionMetaItem => {
+            const {cls: buttonCls, fontIcon, text} = this.buildActionButtonMeta(actionMetaItem);
+            const fontIconNode = h('i', {'class': fontIcon});
+            const textNode = h('span', {}, text);
+            // 使用 h 函數創建按鈕 VNode
+            return h('button', {
+              class: `${buttonCls} c-btn-${actionMetaItem.actionType}`,
+              onClick: (event: Event) => {
+                event.preventDefault();
+                event.stopPropagation();
+                this.handleAction(actionMetaItem, rowData);
+                return false;
+              }
+            }, [fontIconNode, textNode]);
+          });
+          // text 對齊class
+          let alignCls = '';
+          if (this.dataAlign === 'center') {
+            alignCls = 'justify-content-center';
+          } else if (this.dataAlign === 'right') {
+            alignCls = 'justify-content-end';
+          }
+          const clsArr = ['gap-1', alignCls];
+          // 返回包含所有按鈕的容器 VNode
+          return h('div', {
+            class: clsArr.join(' '),
+          }, btnNodeList);
+        }
+      case CTableColumnType.TextInput:
+        this.useVNode = true;
+        return (rowData) => {
+          // 返回輸入框 VNode
+          return h(CRowTextInput, {
+            rowData: rowData,
+            dataName: this.dataName ?? '',
+            'onUpdate:textInput': (val: string) => {
+              // 更新行數據中的對應屬性
+              if(this.dataName) {
+                _.set(rowData, this.dataName, val);
+              }
+            }
+          })
+        };
+      case CTableColumnType.Checkbox:
+        this.useVNode = true;
+        return (rowData) => {
+          // 處理 vNodeAttrs 的 readModeFunc
+          if(_.isFunction(this.vNodeAttrs?.readModeFunc)) {
+            this.vNodeAttrs.readMode = this.vNodeAttrs.readModeFunc(rowData);
+          }
+          // 返回複選框 VNode
+          return h(CRowCheckBox, {
+            ...(this.vNodeAttrs ?? {}),
+            align: this.dataAlign,
+            rowData: rowData,
+            'onUpdate:checked': (val: boolean, event: Event) => {
+              // 更新行數據中的 checked 屬性
+              (rowData as CheckableModel).checked = val;
+              // actionList 找出相對應的 actionMeta 並執行 handleAction
+              const actionMeta = this.actionList?.find(a => a.actionType === CTableColumnActionType.Check);
+              if(actionMeta) {
+                this.handleAction(actionMeta, rowData, event);
+              }
+            }
+          })
+        };
+
+      default:
+        return (rowData) => '';
+    }
+  }
+
+  /**
+   * 根據操作類型生成按鈕的樣式和文字
+   * @param actionType 操作類型
+   * @returns {cls: string, text: string} 按鈕的樣式和文字
+   * @private
+   */
+  private buildActionButtonMeta(actionMeta: CTableColumnActionMeta): { cls: string, fontIcon:string, text: string } {
+    const text = _.get(actionMeta, 'text', '');
+    const useClassName = _.get(actionMeta, 'cls', CTableColumn.defaultBtnClassMap[actionMeta.actionType] || '');
+    const useIcon = _.get(actionMeta, 'icon', CTableColumn.defaultIconMap[actionMeta.actionType] || '');
+
+    return {
+      cls: useClassName,
+      fontIcon: useIcon,
+      text: text,
+    }
+  }
+
+
+  // ~ ----------------------------------------------------------
+}
+
+/**
+ * 分頁樣式配置介面
+ */
+export interface PaginationStyleConfig {
+  backgroundColor: string; // 背景顏色
+  textColor: string; // 文字顏色
+  borderColor: string; // 邊框顏色
+  hoverBackgroundColor: string; // hover 背景顏色
+  hoverTextColor: string; // hover 文字顏色
+  hoverBorderColor: string; // hover 邊框顏色
+  activeBackgroundColor: string; // active 背景顏色
+  activeTextColor: string; // active 文字顏色
+  activeBorderColor: string; // active 邊框顏色
+  previousIcon: string; // 上一頁圖示
+  nextIcon: string; // 下一頁圖示
+  firstIcon: string; // 第一頁圖示
+  lastIcon: string; // 最後一頁圖示
+  ellipsisIcon: string; // 省略號圖示
+}
+
+export interface TableStyleConfig {
+  sortIconNone?: string; // 無指定排序圖示
+  sortIconAsc?: string; // 升序圖示
+  sortIconDesc?: string; // 降序圖示
+  scrollbarThumbColor?: string; // scrollbar thumb 顏色
+  scrollbarTrackColor?: string; // scrollbar track 顏色
+  scrollbarThumbHoverColor?: string; // scrollbar thumb hover 顏色
+  scrollbarHeight?: string; // scrollbar 高度
+}
+
+/**
+ * CTableConfig 類別用於配置表格的全域設定 包含以下
+ * - 分頁樣式設定
+ * - 每頁顯示選項
+ */
+export class CTableConfig {
+
+  private static tableStyleConfig: TableStyleConfig = {
+    sortIconNone: 'sort',
+    sortIconAsc: 'sort-up',
+    sortIconDesc: 'sort-down',
+    scrollbarThumbColor: '#E4B445',
+    scrollbarTrackColor: '#f1f1f1',
+    scrollbarThumbHoverColor: '#d4a33c',
+    scrollbarHeight: '8px',
+  };
+
+  static getTableStyleConfig(): TableStyleConfig {
+    return { ...CTableConfig.tableStyleConfig };
+  }
+
+  static setTableStyleConfig(config: Partial<TableStyleConfig>): void {
+    CTableConfig.tableStyleConfig = {
+      ...CTableConfig.tableStyleConfig,
+      ...config
+    };
+  }
+
+  // 預設分頁顏色樣式
+  private static defaultPaginationStyle: PaginationStyleConfig = {
+    backgroundColor: '#fff',
+    textColor: '#2e2e2e',
+    borderColor: '#E4B445',
+    hoverBackgroundColor: '#E4B445',
+    hoverTextColor: '#fff',
+    hoverBorderColor: '#d4a33c',
+    activeBackgroundColor: '#E4B445',
+    activeTextColor: '#fff',
+    activeBorderColor: '#E4B445',
+    previousIcon: 'angle-left',
+    nextIcon: 'ellipsis',
+    firstIcon: 'angle-double-left',
+    lastIcon: 'angle-double-right',
+    ellipsisIcon: 'angle-right',
+  };
+
+  // 當前使用的分頁樣式
+  private static currentPaginationStyle: PaginationStyleConfig = { ...CTableConfig.defaultPaginationStyle };
+
+  /**
+   * 設定全域分頁樣式
+   * @param config 分頁樣式配置
+   */
+  static setPaginationStyle(config: Partial<PaginationStyleConfig>): void {
+    CTableConfig.currentPaginationStyle = {
+      ...CTableConfig.currentPaginationStyle,
+      ...config
+    };
+  }
+
+  /**
+   * 取得當前分頁樣式
+   */
+  static getPaginationStyle(): PaginationStyleConfig {
+    return { ...CTableConfig.currentPaginationStyle };
+  }
+
+  /**
+   * 重置分頁樣式為預設值
+   */
+  static resetPaginationStyle(): void {
+    CTableConfig.currentPaginationStyle = { ...CTableConfig.defaultPaginationStyle };
+  }
+
+  /**
+   * 產生分頁樣式的 CSS 變數物件
+   */
+  static getPaginationStyleVars(): Record<string, string> {
+    const style = CTableConfig.currentPaginationStyle;
+    return {
+      '--c-pagination-bg-color': style.backgroundColor,
+      '--c-pagination-text-color': style.textColor,
+      '--c-pagination-border-color': style.borderColor,
+      '--c-pagination-hover-bg-color': style.hoverBackgroundColor,
+      '--c-pagination-hover-text-color': style.hoverTextColor,
+      '--c-pagination-hover-border-color': style.hoverBorderColor,
+      '--c-pagination-active-bg-color': style.activeBackgroundColor,
+      '--c-pagination-active-text-color': style.activeTextColor,
+      '--c-pagination-active-border-color': style.activeBorderColor,
+    };
+  }
+
+  /**
+   * 產生表格樣式的 CSS 變數物件
+   */
+  static getTableStyleVars(): Record<string, string> {
+    const style = CTableConfig.tableStyleConfig;
+    return {
+      '--c-scrollbar-thumb-color': style.scrollbarThumbColor || '#E4B445',
+      '--c-scrollbar-track-color': style.scrollbarTrackColor || '#f1f1f1',
+      '--c-scrollbar-thumb-hover-color': style.scrollbarThumbHoverColor || '#d4a33c',
+      '--c-scrollbar-height': style.scrollbarHeight || '8px',
+    };
+  }
+
+  /**
+   * 預設每頁顯示選項
+   */
+  static pageSizeOptions = [10, 20, 50, 100];
+
+}
+
+// 防止 Vite/rollup tree-shake 掉 type export
+export const __CTableDefine__ = null as unknown as
+  CTableColumnType &
+  CTableColumnActionType &
+  CTableColumnActionParam &
+  CTableColumnActionMeta & CTableColumnDefine &
+  PaginationStyleConfig;
+

package/src/components/CTableTD.vue

@@ -0,0 +1,28 @@
+<script setup lang="ts">
+import {CTableColumn,} from "../components/CTableDefine";
+
+export interface CTableTDProps {
+  columnItem: CTableColumn;
+  dataItem: Record<string, any>;
+}
+
+const props = defineProps<CTableTDProps>();
+const renderResult = props.columnItem.render(props.dataItem)
+
+</script>
+
+<template>
+  <template v-if="props.columnItem.useHtml">
+    <div :class="props.columnItem.outerWrapperCls" v-html="renderResult"></div>
+  </template>
+  <template v-else-if="columnItem.useVNode">
+    <component :is="renderResult"/>
+  </template>
+  <template v-else>
+    <div :class="props.columnItem.outerWrapperCls">{{ renderResult }}</div>
+  </template>
+</template>
+
+<style scoped>
+
+</style>

package/src/components/HasPermission.vue

@@ -0,0 +1,28 @@
+<script setup lang="ts">
+import { inject } from 'vue';
+import { SESSION_STORE_KEY } from '../auth/keys';
+
+const props = defineProps<{
+  need: string | string[];
+}>();
+
+// 注入由主專案提供的 sessionStore
+const sessionStore = inject(SESSION_STORE_KEY);
+
+// 檢查權限的邏輯
+const hasPermission = () => {
+  if (!sessionStore) {
+    console.warn('[commons-vue] HasPermission: sessionStore not provided.');
+    return false;
+  }
+  return sessionStore.hasPermission(props.need);
+};
+</script>
+
+<template>
+  <slot v-if="hasPermission()" />
+</template>
+
+<style scoped>
+
+</style>