c-admin-kit 1.0.0

package/src/types.ts

@@ -0,0 +1,344 @@
+import type { Component, 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
+}
+
+// ============================================================
+// Table Column 类型
+// ============================================================
+
+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
+}
+
+// ============================================================
+// Search Field 类型
+// ============================================================
+
+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[]
+}
+
+// ============================================================
+// useListPage 类型
+// ============================================================
+
+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
+}
+
+// ============================================================
+// useForm 类型
+// ============================================================
+
+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
+}
+
+// ============================================================
+// useConfirmAction 类型
+// ============================================================
+
+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>
+}
+
+// ============================================================
+// useConfirmSubmit 类型
+// ============================================================
+
+export interface UseConfirmSubmitOptions {
+  title?: string
+  message?: string
+  confirmButtonText?: string
+  cancelButtonText?: string
+  type?: ConfirmType
+  successMessage?: string
+  cancelMessage?: string
+  errorMessage?: string
+  showCancelMessage?: boolean
+  messageBoxOptions?: AnyRecord
+}
+
+// ============================================================
+// useDownload 类型
+// ============================================================
+
+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>
+}
+
+// ============================================================
+// useDialog 类型
+// ============================================================
+
+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
+}
+
+// ============================================================
+// useTableColumnConfig 类型
+// ============================================================
+
+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>
+}
+
+// ============================================================
+// SearchFieldFactory 类型
+// ============================================================
+
+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/src/utils/index.ts

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

package/src/utils/scroll-to.ts

@@ -0,0 +1,60 @@
+/**
+ * 缓动平滑滚动函数
+ */
+function easeInOutQuad(t: number, b: number, c: number, d: number): number {
+  t /= d / 2
+  if (t < 1) {
+    return c / 2 * t * t + b
+  }
+  t--
+  return -c / 2 * (t * (t - 2) - 1) + b
+}
+
+const requestAnimFrame = (function() {
+  if (typeof window === 'undefined') return (_cb: FrameRequestCallback) => 0
+  return window.requestAnimationFrame || 
+         (window as any).webkitRequestAnimationFrame || 
+         (window as any).mozRequestAnimationFrame || 
+         function(callback: FrameRequestCallback) { return window.setTimeout(callback, 1000 / 60) }
+})()
+
+function move(amount: number): void {
+  if (typeof document === 'undefined') return
+  document.documentElement.scrollTop = amount
+  if (document.body.parentNode) {
+    ;(document.body.parentNode as HTMLElement).scrollTop = amount
+  }
+  document.body.scrollTop = amount
+}
+
+function position(): number {
+  if (typeof document === 'undefined') return 0
+  return document.documentElement.scrollTop || ((document.body.parentNode as HTMLElement)?.scrollTop) || document.body.scrollTop || 0
+}
+
+/**
+ * 平滑滚动到指定位置
+ * @param to 目标位置
+ * @param duration 滚动时长(ms)
+ * @param callback 完成回调
+ */
+export function scrollTo(to: number, duration: number = 500, callback?: () => void): void {
+  const start = position()
+  const change = to - start
+  const increment = 20
+  let currentTime = 0
+
+  const animateScroll = function() {
+    currentTime += increment
+    const val = easeInOutQuad(currentTime, start, change, duration)
+    move(val)
+    if (currentTime < duration) {
+      requestAnimFrame(animateScroll)
+    } else {
+      if (typeof callback === 'function') {
+        callback()
+      }
+    }
+  }
+  animateScroll()
+}

package/src/utils/searchFieldFactory.ts

@@ -0,0 +1,302 @@
+/**
+ * 搜索字段配置工厂函数
+ * 配合 CSearchBox 使用，用于快速生成规范的表单字段配置
+ */
+import dayjs from "dayjs"
+import type {
+  AnyRecord,
+  DateRangeFieldConfig,
+  InputFieldConfig,
+  SelectFieldConfig,
+  CascadeSelectFieldConfig,
+  CascaderFieldConfig,
+  NumberFieldConfig,
+  SwitchFieldConfig,
+} from '../types'
+
+/**
+ * 通用标准日期格式常量
+ */
+export const DATE_FORMAT = {
+  DATE: "YYYY-MM-DD",
+  DATETIME: "YYYY-MM-DD HH:mm:ss",
+  TIME: "HH:mm:ss",
+  MONTH: "YYYY-MM",
+  YEAR: "YYYY",
+  DATE_CN: "YYYY年MM月DD日",
+  DATETIME_CN: "YYYY年MM月DD日 HH:mm:ss",
+} as const
+
+// 通用基础字段创建函数：自动透传所有剩余参数
+const createField = (baseConfig: AnyRecord, config: AnyRecord = {}): AnyRecord => {
+  const { ...extra } = config
+  return {
+    ...baseConfig,
+    ...extra,
+  }
+}
+
+export const SearchFieldFactory = {
+  dateRange(config: DateRangeFieldConfig = {} as DateRangeFieldConfig): AnyRecord {
+    const {
+      prop = "updateTime",
+      label = "更新时间",
+      startField = "updateStartTime",
+      endField = "updateEndTime",
+      format = DATE_FORMAT.DATETIME,
+      props = {},
+    } = config
+
+    const base: AnyRecord = {
+      prop,
+      label,
+      component: "el-date-picker",
+      dateRange: {
+        startField,
+        endField,
+        format: (date: any) => (date ? dayjs(date).format(format) : ""),
+      },
+      props: {
+        type: "datetimerange",
+        rangeSeparator: "至",
+        startPlaceholder: "开始日期",
+        endPlaceholder: "结束日期",
+        valueFormat: DATE_FORMAT.DATETIME,
+        clearable: true,
+        defaultTime: [
+          new Date(2000, 1, 1, 0, 0, 0),
+          new Date(2000, 1, 1, 23, 59, 59),
+        ],
+        ...props,
+      },
+    }
+
+    return createField(base, config)
+  },
+
+  input(config: InputFieldConfig = {} as InputFieldConfig): AnyRecord | null {
+    const { prop, label, placeholder, maxlength, props = {} } = config
+
+    if (!prop || !label) {
+      console.error("input 字段配置缺少必填参数 prop 或 label:", config)
+      return null
+    }
+
+    const base: AnyRecord = {
+      label,
+      prop,
+      component: "el-input",
+      props: {
+        placeholder: placeholder || `请输入${label}`,
+        clearable: true,
+        maxlength,
+        showWordLimit: !!maxlength,
+        ...props,
+      },
+    }
+
+    return createField(base, config)
+  },
+
+  select(config: SelectFieldConfig = {} as SelectFieldConfig): AnyRecord | null {
+    const { prop, label, options = [], multiple = false, props = {} } = config
+
+    if (!prop || !label) {
+      console.error("select 字段配置缺少必填参数 prop 或 label:", config)
+      return null
+    }
+
+    const base: AnyRecord = {
+      label,
+      prop,
+      component: "el-select",
+      options,
+      props: {
+        placeholder: `请选择${label}`,
+        clearable: true,
+        multiple,
+        collapseTags: multiple,
+        collapseTagsTooltip: multiple,
+        filterable: true,
+        ...props,
+      },
+    }
+
+    return createField(base, config)
+  },
+
+  cascadeSelect(config: CascadeSelectFieldConfig = {} as CascadeSelectFieldConfig): AnyRecord | null {
+    const {
+      prop,
+      label,
+      dependOn,
+      getOptions,
+      defaultOptions = [],
+      multiple = false,
+      props = {},
+    } = config
+
+    if (!prop || !label || !dependOn || !getOptions) {
+      console.error("cascadeSelect 配置不完整:", config)
+      return null
+    }
+
+    const base: AnyRecord = {
+      label,
+      prop,
+      component: "el-select",
+      options: [],
+      relation: { dependOn, getOptions },
+      defaultOptions,
+      props: {
+        placeholder: `请选择${label}`,
+        clearable: true,
+        multiple,
+        collapseTags: multiple,
+        collapseTagsTooltip: multiple,
+        ...props,
+      },
+    }
+
+    return createField(base, config)
+  },
+
+  cascader(config: CascaderFieldConfig = {} as CascaderFieldConfig): AnyRecord | null {
+    const {
+      prop,
+      label,
+      options = [],
+      labelKey = "name",
+      valueKey = "id",
+      checkStrictly = true,
+      returnAllIds = true,
+      props = {},
+    } = config
+
+    if (!prop || !label) {
+      console.error("cascader 字段配置缺少必填参数 prop 或 label:", config)
+      return null
+    }
+
+    const base: AnyRecord = {
+      label,
+      prop,
+      component: "el-cascader",
+      returnAllIds,
+      props: {
+        options,
+        placeholder: `请选择${label}`,
+        clearable: true,
+        props: {
+          label: labelKey,
+          value: valueKey,
+          children: "children",
+          checkStrictly,
+        },
+        ...props,
+      },
+    }
+
+    return createField(base, config)
+  },
+
+  number(config: NumberFieldConfig = {} as NumberFieldConfig): AnyRecord | null {
+    const { prop, label, min, max, step = 1, props = {} } = config
+
+    if (!prop || !label) {
+      console.error("number 字段配置缺少必填参数 prop 或 label:", config)
+      return null
+    }
+
+    const base: AnyRecord = {
+      label,
+      prop,
+      component: "el-input-number",
+      props: {
+        placeholder: `请输入${label}`,
+        min,
+        max,
+        step,
+        controlsPosition: "right",
+        style: { width: "100%" },
+        ...props,
+      },
+    }
+
+    return createField(base, config)
+  },
+
+  date(config: AnyRecord = {}): AnyRecord | null {
+    const { prop, label, format = DATE_FORMAT.DATE, props = {} } = config
+
+    if (!prop || !label) {
+      console.error("date 字段配置缺少必填参数 prop 或 label:", config)
+      return null
+    }
+
+    const base: AnyRecord = {
+      prop,
+      label,
+      component: "el-date-picker",
+      props: {
+        type: "date",
+        placeholder: `请选择${label}`,
+        valueFormat: format,
+        clearable: true,
+        ...props,
+      },
+    }
+
+    return createField(base, config)
+  },
+
+  switch(config: SwitchFieldConfig = {} as SwitchFieldConfig): AnyRecord | null {
+    const {
+      prop,
+      label,
+      activeValue = 1,
+      inactiveValue = 0,
+      props = {},
+    } = config
+
+    if (!prop || !label) {
+      console.error("switch 字段配置缺少必填参数 prop 或 label:", config)
+      return null
+    }
+
+    const base: AnyRecord = {
+      label,
+      prop,
+      component: "el-switch",
+      props: {
+        activeValue,
+        inactiveValue,
+        ...props,
+      },
+    }
+
+    return createField(base, config)
+  },
+}
+
+// 常见预设字段快捷方式
+export const CommonSearchFields = {
+  updateTimeRange(config: DateRangeFieldConfig = {} as DateRangeFieldConfig) {
+    return SearchFieldFactory.dateRange({ ...config })
+  },
+  createTimeRange(config: Partial<DateRangeFieldConfig> = {}) {
+    return SearchFieldFactory.dateRange(Object.assign({ prop: "createTime", label: "创建时间" }, config) as DateRangeFieldConfig)
+  },
+  status(options: Array<{ label: string; value: any }>, config: Partial<SelectFieldConfig> = {}) {
+    return SearchFieldFactory.select(Object.assign({ prop: "state", label: "状态" }, config, { options }) as SelectFieldConfig)
+  },
+  keyword(config: Partial<InputFieldConfig> = {}) {
+    return SearchFieldFactory.input(Object.assign({ prop: "keyword", label: "关键词" }, config) as InputFieldConfig)
+  },
+  name(config: Partial<InputFieldConfig> = {}) {
+    return SearchFieldFactory.input(Object.assign({ prop: "name", label: "名称" }, config) as InputFieldConfig)
+  },
+  category(options: any[], config: Partial<CascaderFieldConfig> = {}) {
+    return SearchFieldFactory.cascader(Object.assign({ prop: "categoryId", label: "目录" }, config, { options }) as CascaderFieldConfig)
+  },
+}