c-admin-kit 1.0.0

package/dist/types.d.ts

@@ -0,0 +1,282 @@
+import { Ref, VNode } from 'vue';
+/** 通用记录类型 */
+export type AnyRecord = Record<string, any>;
+/** API 函数类型 */
+export type ApiFn<P = AnyRecord, R = any> = (params: P) => Promise<R>;
+/** 路由跳转位置 */
+export interface NavigateLocation {
+    path: string;
+    query?: AnyRecord;
+}
+export interface StatusMapItem {
+    text: string;
+    type: 'success' | 'danger' | 'warning' | 'info' | '';
+}
+export interface TableColumn {
+    /** 列类型 */
+    type?: 'selection' | 'index' | 'drag' | 'status';
+    /** 字段名 */
+    prop?: string;
+    /** 列标题 */
+    label?: string;
+    /** 列宽 */
+    width?: number | string;
+    /** 最小列宽 */
+    minWidth?: number | string;
+    /** 对齐方式 */
+    align?: 'left' | 'center' | 'right';
+    /** 固定列 */
+    fixed?: boolean | 'left' | 'right';
+    /** 是否可排序 */
+    sortable?: boolean | 'custom';
+    /** 是否显示溢出提示 */
+    showOverflowTooltip?: boolean;
+    /** 插槽名 */
+    slot?: string;
+    /** 头部插槽名 */
+    headerSlot?: string;
+    /** 自定义渲染 */
+    render?: (row: AnyRecord, column: AnyRecord, index: number) => VNode;
+    /** 格式化函数 */
+    formatter?: (row: AnyRecord, column: AnyRecord, cellValue: any, index: number) => string;
+    /** 状态映射 */
+    statusMap?: Record<string | number, StatusMapItem>;
+    /** Tag 效果 */
+    effect?: 'dark' | 'light' | 'plain';
+    /** Tag 尺寸 */
+    size?: 'large' | 'default' | 'small';
+    /** 内部标识 key */
+    _key?: string;
+    [key: string]: any;
+}
+export interface SearchFieldBase {
+    prop: string;
+    label: string;
+    component?: string;
+    type?: string;
+    placeholder?: string;
+    required?: boolean;
+    visible?: boolean | ((form: AnyRecord) => boolean);
+    defaultValue?: any;
+    multiple?: boolean;
+    slotName?: string;
+    props?: AnyRecord;
+    [key: string]: any;
+}
+export interface DateRangeConfig {
+    startField: string;
+    endField: string;
+    format: (date: any) => string;
+}
+export interface RelationConfig {
+    dependOn: string;
+    getOptions: ((parentValue: any, form?: AnyRecord) => any[] | Promise<any[]>) | Record<string, any[]>;
+}
+export interface SearchField extends SearchFieldBase {
+    options?: Array<{
+        label: string;
+        value: any;
+        disabled?: boolean;
+    }>;
+    dateRange?: DateRangeConfig;
+    relation?: RelationConfig;
+    defaultOptions?: Array<{
+        label: string;
+        value: any;
+    }>;
+    returnAllIds?: boolean;
+    fileIds?: string[];
+}
+export interface UseListPageOptions {
+    apiList?: ApiFn;
+    apiChangeState?: ApiFn;
+    apiDelete?: ApiFn & {
+        batch?: ApiFn<{
+            ids: any[];
+        }>;
+    };
+    apiBatchDelete?: ApiFn;
+    apiExport?: ApiFn;
+    addPath?: string;
+    editPath?: string;
+    navigate?: (location: NavigateLocation) => void;
+    exportFileName?: string;
+    stateKey?: string;
+    idKey?: string;
+    activeValue?: any;
+    inactiveValue?: any;
+    statusMap?: Record<string | number, string>;
+    deleteConfirmText?: string;
+    deleteSuccessText?: string;
+    deleteErrorText?: string;
+    openDialog?: (data?: any) => void;
+}
+export interface UseListPageReturn {
+    tableRef: Ref<any>;
+    searchParams: Ref<AnyRecord>;
+    handleSearch: (params?: AnyRecord) => void;
+    handleReset: () => void;
+    changeState: (row: AnyRecord, callback?: (row: AnyRecord) => void) => Promise<void>;
+    handleDelete: (row: AnyRecord, callback?: (row: AnyRecord) => void) => Promise<void>;
+    handleBatchDelete: (rows: AnyRecord[], callback?: (rows: AnyRecord[]) => void) => Promise<void>;
+    handleDialog: (data?: any) => void;
+    exportExcel: () => Promise<void>;
+    handleAdd: (query?: AnyRecord) => void;
+    handleEdit: (row: AnyRecord, query?: AnyRecord) => void;
+    handleView: (row: AnyRecord, detailPath: string, query?: AnyRecord) => void;
+    refresh: () => void;
+    apiList?: ApiFn;
+}
+export interface UseFormOptions<T extends AnyRecord = AnyRecord> {
+    initFormData?: T | (() => T);
+    rules?: AnyRecord;
+    onSuccess?: (result: any) => void;
+    onError?: (error: any) => void;
+    transform?: (formData: T) => any;
+}
+export interface UseFormReturn<T extends AnyRecord = AnyRecord> {
+    formRef: Ref<any>;
+    formData: T;
+    loading: Ref<boolean>;
+    rules: AnyRecord;
+    submit: (apiCall: ApiFn, successMessage?: string, customTransform?: (formData: T) => any, skipValidate?: boolean) => Promise<any>;
+    validate: () => Promise<boolean>;
+    validateField: (field: string, callback?: (...args: any[]) => void) => void;
+    reset: () => void;
+    clearValidate: (props?: string | string[]) => void;
+    setFormData: (data: Partial<T>) => void;
+    resetFormData: () => void;
+}
+export type ConfirmType = 'success' | 'warning' | 'info' | 'error';
+export interface UseConfirmActionOptions {
+    onSuccess?: (result: any) => void;
+    onError?: (error: any) => void;
+    confirmTitle?: string;
+    confirmButtonText?: string;
+    cancelButtonText?: string;
+    confirmType?: ConfirmType;
+}
+export interface UseConfirmActionReturn {
+    execute: (params: AnyRecord) => Promise<any>;
+    loading: Ref<boolean>;
+}
+export interface UseConfirmSubmitOptions {
+    title?: string;
+    message?: string;
+    confirmButtonText?: string;
+    cancelButtonText?: string;
+    type?: ConfirmType;
+    successMessage?: string;
+    cancelMessage?: string;
+    errorMessage?: string;
+    showCancelMessage?: boolean;
+    messageBoxOptions?: AnyRecord;
+}
+export interface UseDownloadOptions {
+    filename?: string;
+    fileExtension?: string;
+    mimeType?: string;
+    timeout?: number;
+    loadingMessage?: string;
+    successMessage?: string;
+}
+export interface UseDownloadReturn {
+    downloading: Ref<boolean>;
+    download: (params?: AnyRecord) => Promise<void>;
+}
+export interface UseDialogOptions {
+    width?: string;
+    title?: string;
+    beforeClose?: (done: () => void) => void;
+}
+export interface UseDialogReturn {
+    visible: Ref<boolean>;
+    dialogTitle: Ref<string>;
+    dialogData: AnyRecord;
+    width: string;
+    open: (data?: AnyRecord, customTitle?: string) => void;
+    close: () => void;
+    handleClose: (done: () => void) => void;
+}
+export interface TableColumnConfigProps {
+    columns?: TableColumn[];
+    tableKey?: string;
+    getColumnConfigApi?: ApiFn | null;
+    saveColumnConfigApi?: ApiFn | null;
+}
+export interface UseTableColumnConfigReturn {
+    computedColumns: import('vue').ComputedRef<TableColumn[]>;
+    settingColumns: import('vue').ComputedRef<TableColumn[]>;
+    visibleColKeys: Ref<string[]>;
+    tempVisibleColKeys: Ref<string[]>;
+    popoverRef: Ref<any>;
+    savingColumns: Ref<boolean>;
+    initTableConfig: () => Promise<void>;
+    handlePopoverShow: () => void;
+    handleCancelSettings: () => void;
+    handleConfirmSettings: () => Promise<void>;
+}
+export interface DateRangeFieldConfig {
+    prop?: string;
+    label?: string;
+    startField?: string;
+    endField?: string;
+    format?: string;
+    props?: AnyRecord;
+    [key: string]: any;
+}
+export interface InputFieldConfig {
+    prop: string;
+    label: string;
+    placeholder?: string;
+    maxlength?: number;
+    props?: AnyRecord;
+    [key: string]: any;
+}
+export interface SelectFieldConfig {
+    prop: string;
+    label: string;
+    options?: Array<{
+        label: string;
+        value: any;
+    }>;
+    multiple?: boolean;
+    props?: AnyRecord;
+    [key: string]: any;
+}
+export interface CascadeSelectFieldConfig extends SelectFieldConfig {
+    dependOn: string;
+    getOptions: (parentValue: any) => Promise<any[]>;
+    defaultOptions?: Array<{
+        label: string;
+        value: any;
+    }>;
+}
+export interface CascaderFieldConfig {
+    prop: string;
+    label: string;
+    options?: any[];
+    labelKey?: string;
+    valueKey?: string;
+    checkStrictly?: boolean;
+    returnAllIds?: boolean;
+    props?: AnyRecord;
+    [key: string]: any;
+}
+export interface NumberFieldConfig {
+    prop: string;
+    label: string;
+    min?: number;
+    max?: number;
+    step?: number;
+    props?: AnyRecord;
+    [key: string]: any;
+}
+export interface SwitchFieldConfig {
+    prop: string;
+    label: string;
+    activeValue?: any;
+    inactiveValue?: any;
+    props?: AnyRecord;
+    [key: string]: any;
+}

package/dist/utils/index.d.ts

@@ -0,0 +1,4 @@
+export * from './searchFieldFactory';
+export * from './validate';
+export * from './scroll-to';
+export * from './treeManager';

package/dist/utils/scroll-to.d.ts

@@ -0,0 +1,7 @@
+/**
+ * 平滑滚动到指定位置
+ * @param to 目标位置
+ * @param duration 滚动时长(ms)
+ * @param callback 完成回调
+ */
+export declare function scrollTo(to: number, duration?: number, callback?: () => void): void;

package/dist/utils/searchFieldFactory.d.ts

@@ -0,0 +1,34 @@
+import { AnyRecord, DateRangeFieldConfig, InputFieldConfig, SelectFieldConfig, CascadeSelectFieldConfig, CascaderFieldConfig, NumberFieldConfig, SwitchFieldConfig } from '../types';
+/**
+ * 通用标准日期格式常量
+ */
+export declare const DATE_FORMAT: {
+    readonly DATE: "YYYY-MM-DD";
+    readonly DATETIME: "YYYY-MM-DD HH:mm:ss";
+    readonly TIME: "HH:mm:ss";
+    readonly MONTH: "YYYY-MM";
+    readonly YEAR: "YYYY";
+    readonly DATE_CN: "YYYY年MM月DD日";
+    readonly DATETIME_CN: "YYYY年MM月DD日 HH:mm:ss";
+};
+export declare const SearchFieldFactory: {
+    dateRange(config?: DateRangeFieldConfig): AnyRecord;
+    input(config?: InputFieldConfig): AnyRecord | null;
+    select(config?: SelectFieldConfig): AnyRecord | null;
+    cascadeSelect(config?: CascadeSelectFieldConfig): AnyRecord | null;
+    cascader(config?: CascaderFieldConfig): AnyRecord | null;
+    number(config?: NumberFieldConfig): AnyRecord | null;
+    date(config?: AnyRecord): AnyRecord | null;
+    switch(config?: SwitchFieldConfig): AnyRecord | null;
+};
+export declare const CommonSearchFields: {
+    updateTimeRange(config?: DateRangeFieldConfig): AnyRecord;
+    createTimeRange(config?: Partial<DateRangeFieldConfig>): AnyRecord;
+    status(options: Array<{
+        label: string;
+        value: any;
+    }>, config?: Partial<SelectFieldConfig>): AnyRecord | null;
+    keyword(config?: Partial<InputFieldConfig>): AnyRecord | null;
+    name(config?: Partial<InputFieldConfig>): AnyRecord | null;
+    category(options: any[], config?: Partial<CascaderFieldConfig>): AnyRecord | null;
+};

package/dist/utils/treeManager.d.ts

@@ -0,0 +1,64 @@
+/**
+ * 通用树结构处理工具
+ */
+/**
+ * 递归从树中查找目标节点
+ * @param tree 树数组
+ * @param predicate 匹配函数
+ * @param childrenKey 子节点字段名，默认 'children'
+ * @returns 找到的节点对象
+ */
+export declare function findTreeNode<T extends Record<string, any>>(tree: T[] | undefined, predicate: (node: T) => boolean, childrenKey?: string): T | null;
+/**
+ * 获取从根节点到目标节点的完整祖先路径 (仅值列表，如 [1, 10, 102])
+ * @param tree 树结构
+ * @param targetValue 目标节点标识
+ * @param keyField 匹配键名，如 'id'
+ * @param childrenKey 子节点字段名
+ * @returns 包含从根到目标节点的所有路径标识
+ */
+export declare function findNodePath<T extends Record<string, any>>(tree: T[] | undefined, targetValue: any, keyField?: string, childrenKey?: string): any[];
+/**
+ * 获取从根节点到目标节点的完整祖先节点对象列表 (包含目标节点自身)
+ * @param tree 树结构
+ * @param predicate 匹配条件或目标节点键值
+ * @param childrenKey 子节点字段名
+ * @returns 祖先节点对象数组，根节点在前
+ */
+export declare function findParentNodes<T extends Record<string, any>>(tree: T[] | undefined, predicate: ((node: T) => boolean) | any, childrenKey?: string, keyField?: string): T[];
+/**
+ * 树结构扁平化
+ * @param tree 树数组
+ * @param childrenKey 子节点字段名
+ * @returns 扁平化后的数组
+ */
+export declare function flattenTree<T extends Record<string, any>>(tree?: T[], childrenKey?: string): T[];
+/** 树转列表别名 */
+export declare const treeToList: typeof flattenTree;
+/**
+ * 扁平列表转树结构 (时间复杂度 O(n) 的高效 Map 算法)
+ * @param list 扁平列表
+ * @param options 配置项 { id: 'id', pid: 'parentId', children: 'children', rootPid: [0, null, undefined, ''] }
+ * @returns 构造完成的树数组
+ */
+export declare function listToTree<T extends Record<string, any>>(list?: T[], options?: {
+    id?: string;
+    pid?: string;
+    children?: string;
+    rootPid?: any[];
+}): T[];
+/**
+ * 过滤树结构，保留满足条件的节点及其父链路
+ * @param tree 树数组
+ * @param predicate 过滤条件
+ * @param childrenKey 子节点字段名
+ * @returns 过滤后的新树结构
+ */
+export declare function filterTree<T extends Record<string, any>>(tree: T[] | undefined, predicate: (node: T) => boolean, childrenKey?: string): T[];
+/**
+ * 树结构映射/转换 (类似于数组的 map)
+ * @param tree 树数组
+ * @param mapper 节点转换器
+ * @param childrenKey 子节点字段名
+ */
+export declare function mapTree<T extends Record<string, any>, R extends Record<string, any>>(tree: T[] | undefined, mapper: (node: T) => R, childrenKey?: string): R[];

package/dist/utils/validate.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 路径匹配器
+ */
+export declare function isPathMatch(pattern: string, path: string): boolean;
+/**
+ * 判断value字符串是否为空
+ */
+export declare function isEmpty(value: unknown): boolean;
+/**
+ * 判断url是否是http或https
+ */
+export declare function isHttp(url: string): boolean;
+/**
+ * 判断path是否为外链
+ */
+export declare function isExternal(path: string): boolean;
+/**
+ * 验证合法 URL
+ */
+export declare function validURL(url: string): boolean;
+/**
+ * 验证邮箱
+ */
+export declare function validEmail(email: string): boolean;
+/**
+ * 验证手机号
+ */
+export declare function validPhone(phone: string): boolean;
+export declare function isString(str: unknown): str is string;
+export declare function isArray(arg: unknown): arg is any[];

package/package.json

@@ -0,0 +1,86 @@
+{
+  "name": "c-admin-kit",
+  "version": "1.0.0",
+  "description": "基于 Vue 3 + Element Plus 的中后台企业级高阶通用组件与 Hooks 套件（强制使用 c- 前缀）",
+  "type": "module",
+  "main": "./dist/c-admin-kit.umd.cjs",
+  "module": "./dist/c-admin-kit.js",
+  "types": "./dist/index.d.ts",
+  "style": "./dist/c-admin-kit.css",
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/c-admin-kit.js",
+      "require": "./dist/c-admin-kit.umd.cjs"
+    },
+    "./dist/c-admin-kit.css": "./dist/c-admin-kit.css",
+    "./components": {
+      "types": "./dist/components/index.d.ts",
+      "import": "./src/components/index.ts"
+    },
+    "./composables": {
+      "types": "./dist/composables/index.d.ts",
+      "import": "./src/composables/index.ts"
+    },
+    "./hooks": {
+      "types": "./dist/composables/index.d.ts",
+      "import": "./src/composables/index.ts"
+    },
+    "./utils": {
+      "types": "./dist/utils/index.d.ts",
+      "import": "./src/utils/index.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "keywords": [
+    "vue3",
+    "element-plus",
+    "components",
+    "table",
+    "search-box",
+    "crud",
+    "admin",
+    "hooks"
+  ],
+  "author": "wllcyg",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wllcyg/admin-kit.git"
+  },
+  "homepage": "https://github.com/wllcyg/admin-kit#readme",
+  "bugs": {
+    "url": "https://github.com/wllcyg/admin-kit/issues"
+  },
+  "peerDependencies": {
+    "@element-plus/icons-vue": "^2.0.0",
+    "dayjs": "^1.11.0",
+    "element-plus": "^2.3.0",
+    "sortablejs": "^1.15.0",
+    "vue": "^3.3.0"
+  },
+  "devDependencies": {
+    "@element-plus/icons-vue": "^2.3.2",
+    "@types/node": "^26.6.2",
+    "@types/sortablejs": "^1.15.9",
+    "@vitejs/plugin-vue": "^5.0.0",
+    "dayjs": "^1.11.23",
+    "element-plus": "^2.14.6",
+    "sortablejs": "^1.15.7",
+    "typescript": "^5.7.3",
+    "vite": "^5.0.0 || ^6.0.0",
+    "vite-plugin-dts": "^5.1.1",
+    "vue-tsc": "^3.3.11"
+  },
+  "scripts": {
+    "build": "vue-tsc --noEmit && vite build",
+    "typecheck": "vue-tsc --noEmit"
+  }
+}

package/src/components/AsyncButton/index.vue

@@ -0,0 +1,58 @@
+<template>
+  <el-button
+    v-bind="$attrs"
+    :loading="isLoading"
+    :disabled="isDisabled"
+    @click="handleClick"
+  >
+    <slot />
+  </el-button>
+</template>
+
+<script setup lang="ts">
+import { ref, computed, type PropType } from 'vue'
+
+defineOptions({ name: 'CAsyncButton' })
+
+const props = defineProps({
+  /** 接收一个可能是异步的点击处理函数，返回 Promise 时自动开启 loading */
+  onClick: {
+    type: Function as PropType<(event: MouseEvent) => any>,
+    default: null
+  },
+  /** 手动强制 loading，优先级最高 */
+  loading: {
+    type: Boolean,
+    default: false
+  },
+  disabled: {
+    type: Boolean,
+    default: false
+  }
+})
+
+// 内部自动 loading 状态
+const innerLoading = ref(false)
+
+// 实际 loading：外部手动传入 OR 内部自动触发
+const isLoading = computed(() => props.loading || innerLoading.value)
+
+// loading 期间同时禁用按钮，防止重复点击
+const isDisabled = computed(() => props.disabled || isLoading.value)
+
+async function handleClick(event: MouseEvent) {
+  if (!props.onClick || isDisabled.value) return
+
+  const result = props.onClick(event)
+
+  // 自动检测是否为 Promise 或 Thenable 对象，是则开启 loading
+  if (result && typeof (result as any).then === 'function') {
+    innerLoading.value = true
+    try {
+      await result
+    } finally {
+      innerLoading.value = false
+    }
+  }
+}
+</script>