c-admin-kit 1.0.0

package/src/composables/useForm.ts

@@ -0,0 +1,114 @@
+import { ref, reactive } from "vue"
+import { ElMessage } from "element-plus"
+import type { UseFormOptions, UseFormReturn, AnyRecord, ApiFn } from '../types'
+
+/**
+ * 表单状态与提交封装 Hook
+ */
+export function useForm<T extends AnyRecord = AnyRecord>(options: UseFormOptions<T> = {}): UseFormReturn<T> {
+  const {
+    initFormData = {} as T,
+    rules = {},
+    onSuccess,
+    onError,
+    transform,
+  } = options
+
+  const formRef = ref<any>(null)
+  const getInitialData = (): T => (typeof initFormData === "function" ? initFormData() : initFormData)
+  const formData = reactive<T>({ ...getInitialData() }) as T
+  const loading = ref(false)
+
+  // 提交表单 (skipValidate 可控制是否跳过校验)
+  const submit = async (
+    apiCall: ApiFn,
+    successMessage: string = "操作成功",
+    customTransform?: (formData: T) => any,
+    skipValidate: boolean = false,
+  ): Promise<any> => {
+    if (!formRef.value && !skipValidate) return
+
+    try {
+      if (!skipValidate) {
+        const valid = await validate()
+        if (!valid) {
+          ElMessage.warning("请检查表单填写是否正确")
+          return
+        }
+      }
+      loading.value = true
+
+      const transformFn = customTransform || transform
+      const submitData = transformFn ? transformFn(formData) : formData
+
+      const result = await apiCall(submitData)
+
+      if (successMessage) {
+        ElMessage.success(successMessage)
+      }
+      onSuccess?.(result)
+
+      return result
+    } catch (error) {
+      console.error("useForm submit error:", error)
+      onError?.(error)
+      throw error
+    } finally {
+      loading.value = false
+    }
+  }
+
+  // 手动验证表单
+  const validate = async (): Promise<boolean> => {
+    if (!formRef.value) return false
+    try {
+      await formRef.value.validate()
+      return true
+    } catch {
+      return false
+    }
+  }
+
+  // 验证指定字段
+  const validateField = (field: string, callback?: (...args: any[]) => void): void => {
+    if (!formRef.value) return
+    formRef.value.validateField(field, callback)
+  }
+
+  // 重置表单
+  const reset = (): void => {
+    formRef.value?.resetFields()
+  }
+
+  // 清空验证
+  const clearValidate = (props?: string | string[]): void => {
+    formRef.value?.clearValidate(props)
+  }
+
+  // 设置表单数据
+  const setFormData = (data: Partial<T>): void => {
+    Object.assign(formData, data)
+  }
+
+  // 重置为初始数据
+  const resetFormData = (): void => {
+    Object.keys(formData).forEach((key) => {
+      delete (formData as any)[key]
+    })
+    Object.assign(formData, getInitialData())
+  }
+
+  return {
+    formRef,
+    formData,
+    loading,
+    rules,
+    submit,
+    validate,
+    validateField,
+    reset,
+    clearValidate,
+    setFormData,
+    resetFormData,
+  }
+}

package/src/composables/useListPage.ts

@@ -0,0 +1,243 @@
+import { ref } from "vue"
+import { ElMessage, ElMessageBox } from "element-plus"
+import type { UseListPageOptions, UseListPageReturn, AnyRecord, NavigateLocation } from '../types'
+
+/**
+ * 列表页标准 CRUD 流程组合式函数
+ */
+export function useListPage(options: UseListPageOptions = {}): UseListPageReturn {
+  const {
+    apiList,
+    apiChangeState,
+    apiDelete,
+    apiBatchDelete,
+    apiExport,
+    addPath,
+    editPath,
+    navigate,
+    exportFileName = "数据导出",
+    stateKey = "state",
+    idKey = "id",
+    activeValue = 1,
+    inactiveValue = 0,
+    statusMap = { 0: '启用', 1: '停用' },
+    deleteConfirmText = "确定要删除该数据吗？删除后将无法恢复！",
+    deleteSuccessText = "删除成功",
+    deleteErrorText = "删除失败",
+    openDialog,
+  } = options
+
+  const tableRef = ref<any>(null)
+  const searchParams = ref<AnyRecord>({})
+
+  // 路由跳转适配
+  const doNavigate = (location: NavigateLocation): void => {
+    if (typeof navigate === 'function') {
+      navigate(location)
+    } else {
+      console.warn("useListPage: 未提供 navigate 函数，如需路由跳转请在 options 中传入 navigate: (loc) => router.push(loc)")
+    }
+  }
+
+  // 搜索处理
+  const handleSearch = (params?: AnyRecord): void => {
+    searchParams.value = params || {}
+    tableRef.value?.search?.(searchParams.value)
+  }
+
+  // 重置搜索
+  const handleReset = (): void => {
+    searchParams.value = {}
+    tableRef.value?.reset?.()
+  }
+
+  // 状态切换
+  const changeState = async (row: AnyRecord, callback?: (row: AnyRecord) => void): Promise<void> => {
+    if (!apiChangeState) {
+      console.warn("useListPage: 未提供 apiChangeState 接口")
+      return
+    }
+
+    try {
+      const currentState = row[stateKey]
+      const nextState = currentState === activeValue ? inactiveValue : activeValue
+      const action = statusMap[nextState] || '更新'
+      
+      await ElMessageBox.confirm(`确定要${action}该数据吗？`, "提示", {
+        type: "warning",
+      })
+
+      await apiChangeState({
+        [idKey]: row[idKey],
+        [stateKey]: nextState,
+      })
+
+      ElMessage.success(`${action}成功`)
+      tableRef.value?.refresh?.()
+      callback?.(row)
+    } catch (error) {
+      if (error !== "cancel" && error !== "close") {
+        ElMessage.error("操作失败")
+      }
+    }
+  }
+
+  // 删除 - 单条
+  const handleDelete = async (row: AnyRecord, callback?: (row: AnyRecord) => void): Promise<void> => {
+    if (!apiDelete) {
+      console.warn("useListPage: 未提供 apiDelete 接口")
+      return
+    }
+
+    try {
+      await ElMessageBox.confirm(deleteConfirmText, "警告", {
+        confirmButtonText: "确定",
+        cancelButtonText: "取消",
+        type: "error",
+        distinguishCancelAndClose: true,
+      })
+
+      await apiDelete({ [idKey]: row[idKey] })
+
+      ElMessage.success(deleteSuccessText)
+      tableRef.value?.refresh?.()
+      callback?.(row)
+    } catch (error) {
+      if (error !== "cancel" && error !== "close") {
+        ElMessage.error(deleteErrorText)
+      }
+    }
+  }
+
+  // 批量删除
+  const handleBatchDelete = async (rows: AnyRecord[], callback?: (rows: AnyRecord[]) => void): Promise<void> => {
+    if (!apiDelete) {
+      console.warn("useListPage: 未提供 apiDelete 接口")
+      return
+    }
+
+    if (!rows || rows.length === 0) {
+      ElMessage.warning("请选择要删除的数据")
+      return
+    }
+
+    try {
+      await ElMessageBox.confirm(
+        `确定要删除选中的 ${rows.length} 条数据吗？删除后将无法恢复！`,
+        "警告",
+        {
+          confirmButtonText: "确定",
+          cancelButtonText: "取消",
+          type: "error",
+          distinguishCancelAndClose: true,
+        },
+      )
+
+      const ids = rows.map((row) => row[idKey])
+
+      if (apiBatchDelete) {
+        await apiBatchDelete({ ids })
+      } else if (apiDelete.batch) {
+        await apiDelete.batch({ ids })
+      } else {
+        await Promise.all(ids.map((id) => apiDelete({ [idKey]: id })))
+      }
+
+      ElMessage.success(`成功删除 ${rows.length} 条数据`)
+      tableRef.value?.refresh?.()
+      callback?.(rows)
+    } catch (error) {
+      if (error !== "cancel" && error !== "close") {
+        ElMessage.error("删除失败")
+      }
+    }
+  }
+
+  // 导出
+  const exportExcel = async (): Promise<void> => {
+    if (!apiExport) {
+      console.warn("useListPage: 未提供 apiExport 接口")
+      return
+    }
+
+    try {
+      const res = await apiExport(searchParams.value)
+      const data = res?.data || res
+      const blob = data instanceof Blob ? data : new Blob([data], {
+        type: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+      })
+      const url = window.URL.createObjectURL(blob)
+      const link = document.createElement("a")
+      link.href = url
+      link.download = `${exportFileName}_${Date.now()}.xlsx`
+      document.body.appendChild(link)
+      link.click()
+      document.body.removeChild(link)
+      window.URL.revokeObjectURL(url)
+      ElMessage.success("导出成功")
+    } catch (error) {
+      ElMessage.error("导出失败")
+    }
+  }
+
+  // 新增
+  const handleAdd = (query: AnyRecord = {}): void => {
+    if (!addPath) {
+      console.warn("useListPage: 未提供 addPath")
+      return
+    }
+    doNavigate({ path: addPath, query })
+  }
+
+  const handleDialog = (data?: any): void => {
+    if (typeof openDialog === "function") {
+      openDialog(data)
+    }
+  }
+
+  // 编辑
+  const handleEdit = (row: AnyRecord, query: AnyRecord = {}): void => {
+    if (!editPath) {
+      console.warn("useListPage: 未提供 editPath")
+      return
+    }
+    doNavigate({
+      path: editPath,
+      query: { id: row[idKey], ...query },
+    })
+  }
+
+  // 查看详情
+  const handleView = (row: AnyRecord, detailPath: string, query: AnyRecord = {}): void => {
+    if (!detailPath) {
+      console.warn("useListPage: 未提供 detailPath")
+      return
+    }
+    doNavigate({
+      path: detailPath,
+      query: { id: row[idKey], ...query },
+    })
+  }
+
+  // 刷新表格
+  const refresh = (): void => {
+    tableRef.value?.refresh?.()
+  }
+
+  return {
+    tableRef,
+    searchParams,
+    handleSearch,
+    handleReset,
+    changeState,
+    handleDelete,
+    handleBatchDelete,
+    handleDialog,
+    exportExcel,
+    handleAdd,
+    handleEdit,
+    handleView,
+    refresh,
+    apiList,
+  }
+}

package/src/env.d.ts

@@ -0,0 +1,7 @@
+/// <reference types="vite/client" />
+
+declare module '*.vue' {
+  import type { DefineComponent } from 'vue'
+  const component: DefineComponent<Record<string, unknown>, Record<string, unknown>, unknown>
+  export default component
+}

package/src/index.ts

@@ -0,0 +1,44 @@
+import type { App, Component } from 'vue'
+import { components } from './components/index'
+
+// 导出所有组件
+export * from './components/index'
+
+// 导出所有组合式函数 (Hooks)
+export * from './composables/index'
+
+// 导出所有通用工具类
+export * from './utils/index'
+
+// 导出类型定义
+export type * from './types'
+
+/**
+ * 将 PascalCase 转换为 kebab-case
+ * 例如: CSimpleTable -> c-simple-table
+ */
+function toKebabCase(str: string): string {
+  return str.replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase()
+}
+
+/**
+ * 全局安装插件
+ * 规范：固定强制使用 C / c- 前缀，不支持自定义前缀，确保各项目命名一致性
+ */
+const install = (app: App): void => {
+  components.forEach((component: Component) => {
+    if (component.name) {
+      // 注册 PascalCase 形式，例如 CSimpleTable
+      app.component(component.name, component)
+      // 注册 kebab-case 形式，例如 c-simple-table
+      const kebabName = toKebabCase(component.name)
+      if (kebabName !== component.name) {
+        app.component(kebabName, component)
+      }
+    }
+  })
+}
+
+export default {
+  install,
+}