C-Admin-Kit

c-admin-kit 是一套专为企业级中后台打造的高阶通用组件与 Hooks 套件。基于 Vue 3 + Element Plus + TypeScript 构建，提供成熟的标准 CRUD 流程封装、配置化高级表格、多条件搜索工厂、异步防重按钮、平滑拖拽分栏及常用树形数据工具函数。

🌐 在线预览与交互演练场：https://admin-kit.cheatppf.xyz
📌 团队规范约束：为彻底避免多工程复用时的组件同名冲突，所有组件统一且固定强制使用 c- / C 前缀（如 <c-simple-table>、<c-search-box>），开箱即用，代码风格统一。

✨ 核心特性

• 🛡️ 100% TypeScript：源码全量 TS 编写，严格类型定义，类型提示精确到组件 Props、Emits、Slots 及 Hook 泛型。
• ⚡ 轻量纯净：以 peerDependencies 消费宿主环境的 vue、element-plus，打包体积仅几十 KB，无多余冗余包，完美继承宿主主题变量。
• 🎯 开箱即用：自带企业级增删改查最佳实践，配合 useListPage 与 SearchFieldFactory，10 余行代码即可完成完整页面。
• 🌲 Tree-Shaking：支持全量安装与细粒度子路径按需导入，生产构建零多余冗余代码。

📥 安装

在您的 Vue 3 + Element Plus 工程中执行：

# 推荐使用 pnpm
pnpm add c-admin-kit

# 或者 npm / yarn
npm install c-admin-kit
yarn add c-admin-kit

⚠️ 前置依赖：请确保项目已安装 vue (>= 3.3.0) 与 element-plus (>= 2.3.0)。

🚀 快速上手

1. 全局完整引入 (main.ts / main.js)

import { createApp } from 'vue'
import ElementPlus from 'element-plus'
import 'element-plus/dist/index.css'

import CAdminKit from 'c-admin-kit'
import 'c-admin-kit/dist/c-admin-kit.css'

import App from './App.vue'

const app = createApp(App)
app.use(ElementPlus)
app.use(CAdminKit) // 自动全局注册所有 c- 开头组件
app.mount('#app')

2. 按需局部引入 (推荐)

组件与 Hooks 均支持解构引入或子路径导入：

<template>
  <c-search-box :fields="searchFields" @search="handleSearch" @reset="handleReset" />
  <c-simple-table ref="tableRef" :api="getUserListApi" :columns="columns" auto-height />
</template>

<script setup lang="ts">
import { CSearchBox, CSimpleTable, SearchFieldFactory, useListPage } from 'c-admin-kit'
import 'c-admin-kit/dist/c-admin-kit.css'

// 亦支持按子路径引用：
// import { CSimpleTable } from 'c-admin-kit/components'
// import { useListPage } from 'c-admin-kit/composables'
// import { SearchFieldFactory } from 'c-admin-kit/utils'
</script>

典型用法：标准 CRUD 页面

结合 SearchFieldFactory、useListPage、CSearchBox 与 CSimpleTable 快速构建后台列表页：

<template>
  <div class="page-container">
    <!-- 1. 结构化搜索栏 -->
    <c-search-box
      :fields="searchFields"
      @search="handleSearch"
      @reset="handleReset"
    />

    <!-- 2. 高阶自适应表格 -->
    <c-simple-table
      ref="tableRef"
      :api="getUserListApi"
      :columns="columns"
      table-key="user_management_table"
      auto-height
    >
      <!-- 头部操作区 -->
      <template #headerLeft>
        <el-button type="primary" @click="handleAdd">新增用户</el-button>
        <el-button type="danger" @click="handleBatchDelete">批量删除</el-button>
      </template>

      <!-- 操作列插槽 -->
      <template #actions="{ row }">
        <el-button link type="primary" @click="handleEdit(row)">编辑</el-button>
        <el-button link type="danger" @click="handleDelete(row)">删除</el-button>
      </template>
    </c-simple-table>
  </div>
</template>

<script setup lang="ts">
import { computed } from 'vue'
import {
  CSearchBox,
  CSimpleTable,
  SearchFieldFactory,
  useListPage,
  type TableColumn
} from 'c-admin-kit'
import {
  getUserListApi,
  deleteUserApi,
  batchDeleteUserApi,
  changeUserStatusApi
} from '@/api/user'

// 1. 标准流程控制 Hook (集成搜索联动、分页维护、单条/批量删除、状态切换、详情/新增路由)
const {
  tableRef,
  handleSearch,
  handleReset,
  handleDelete,
  handleBatchDelete,
  handleAdd,
  handleEdit
} = useListPage({
  apiList: getUserListApi,
  apiDelete: deleteUserApi,
  apiBatchDelete: batchDeleteUserApi,
  apiChangeState: changeUserStatusApi,
  addPath: '/user/add',
  editPath: '/user/edit'
})

// 2. 搜索字段快速配置工厂 (支持 input、select、dateRange、cascader、级联联动等)
const searchFields = computed(() => [
  SearchFieldFactory.input({ prop: 'keyword', label: '关键词' }),
  SearchFieldFactory.select({
    prop: 'status',
    label: '状态',
    options: [
      { label: '启用', value: 1 },
      { label: '停用', value: 0 }
    ]
  }),
  SearchFieldFactory.dateRange({ prop: 'createTime', label: '创建时间' })
])

// 3. 表格列配置 (原生支持 user.name 深度路径取值、空值 '-' 占位、拖拽排序、自定义列持久化)
const columns: TableColumn[] = [
  { type: 'selection' },
  { type: 'index', label: '序号' },
  { prop: 'username', label: '用户名' },
  { prop: 'department.name', label: '所属部门' }, // 支持嵌套深度字段
  { prop: 'status', label: '状态', type: 'status' },
  { prop: 'createTime', label: '创建时间' },
  { label: '操作', slot: 'actions', width: 150, fixed: 'right' }
]
</script>

🧩 组件清单 (Components)

| 组件名 | 标签名称 | 功能特性 | | :--- | :--- | :--- | | CSimpleTable | <c-simple-table> | 高阶企业级表格：集成拖拽排序、列自定义显隐（本地缓存/API持久化）、动态视口全屏自适应高度、嵌套属性链式取值（dept.name）、空单元格占位、分页联动。 | | CSearchBox | <c-search-box> | 配置化多条件搜索栏：响应式栅格自适应、一键展开/收起、级联下拉异步联动、回车快捷搜索、自定义插槽扩展。 | | CAsyncButton | <c-async-button> | 异步防重按钮：自动感知 Promise / Thenable 异步任务并开启 loading，阻断连续点击，结束自动恢复。 | | CCollapsibleContainer | <c-collapsible-container> | 左右双栏拖拽折叠布局：支持鼠标拖拽分隔线缩放面板宽度（消除了微动效冲突，拖拽丝滑），支持一键折叠收起。 | | CCustomDrawer | <c-custom-drawer> | 标准化企业级抽屉：统一底部确定/取消操作栏，内置确定按钮 confirmLoading 状态与 computed 双向绑定。 | | CImagePreview | <c-image-preview> | 缩略图与大图预览：支持单图 URL、逗号分隔多图字符串及数组入参，内置安全容错清洗与缩略图悬浮动效。 | | CDiff | <c-diff> | 文本代码 Diff 视图：纯前端实现基于编辑距离与相似度的字符级与行级差异可视化高亮。 | | CSelectWithAll | <c-select-with-all> | 全选下拉选择器：支持一键全选/全不选、半选状态判断及防抖远程搜索。 | | CSelectWithPage| <c-select-with-page>| 大数据分页下拉：支持自定义键值字段、关键词远程搜索与海量选项分页加载。 |

🛠️ 组合式函数 (Composables / Hooks)

1. useListPage (标准列表页流程控制)

管理列表搜索、刷新、分页、状态切换、单条/批量删除及路由跳转：

const {
  tableRef,
  searchParams,
  handleSearch,
  handleReset,
  handleDelete,
  handleBatchDelete,
  changeState,
  exportExcel
} = useListPage({
  apiList: getListApi,
  apiDelete: deleteApi,
  apiBatchDelete: batchDeleteApi, // 可选独立批量删除接口
  apiChangeState: updateStatusApi,
  apiExport: exportApi
})

2. useForm (表单状态与提交流程)

封装表单数据响应式模型、自动校验拦截与提交状态：

const { formRef, formData, loading, submit, reset, setFormData } = useForm({
  initFormData: { name: '', roleId: null }
})

// 提交时自动触发 form.validate()，校验失败自动提示并阻断，成功触发 loading 并调用 API
await submit(async (data) => await saveApi(data), '保存成功')

3. useDownload (安全文件导出与下载)

安全导出二进制文件，导出 downloading 响应式状态，自动从响应头提取文件名：

const { download, downloading } = useDownload(exportApi, {
  filename: '用户报表'
})

// 外部按钮可直接绑定 loading
// <el-button :loading="downloading" @click="download({ deptId: 1 })">导出</el-button>

4. useConfirmAction & useConfirmSubmit (操作二次确认)

消除重复的 ElMessageBox.confirm 模板代码：

const handleRemove = useConfirmSubmit(
  async (id) => await deleteApi(id),
  () => tableRef.value.refresh(),
  { message: '确定要永久删除该记录吗？' }
)

5. useDialog (弹窗显隐与上下文传递)

优雅管理模态弹窗的开启、关闭与行数据传递：

const { visible, dialogData, openDialog, closeDialog } = useDialog()

🧰 实用工具库 (Utils)

1. SearchFieldFactory (搜索字段工厂)

规范化、声明式生成搜索栏配置：

import { SearchFieldFactory, CommonSearchFields } from 'c-admin-kit'

const fields = [
  SearchFieldFactory.input({ prop: 'title', label: '标题' }),
  SearchFieldFactory.select({ prop: 'status', label: '状态', options: [...] }),
  SearchFieldFactory.dateRange({ prop: 'createTime', label: '创建时间' }),
  SearchFieldFactory.cascader({ prop: 'deptId', label: '部门', options: [...] }),
  // 常用预设快捷字段
  CommonSearchFields.keyword(),
  CommonSearchFields.status([...])
]

2. treeManager (高性能树结构处理)

import {
  listToTree,
  treeToList,
  findTreeNode,
  findParentNodes,
  filterTree,
  mapTree
} from 'c-admin-kit'

// 1. 扁平数组一键转树 (时间复杂度 O(n) Hash Map 算法)
const tree = listToTree(flatList, { id: 'id', pid: 'parentId', children: 'children' })

// 2. 根据节点 ID 查找包含自身和所有上级父节点的完整链条
const parentNodes = findParentNodes(tree, targetId)

// 3. 树结构过滤（保留命中节点及其祖先链路）
const filteredTree = filterTree(tree, (node) => node.name.includes('技术部'))

🎮 Playground 交互演练台

🔗 线上演示地址：https://admin-kit.cheatppf.xyz

本项目包含同仓物理隔离的独立演练工程 playground/，100% 消费并运行 NPM 官方已发布的真实 c-admin-kit 远端包与产物，包含 6 大核心场景 Demo（CRUD 页面、左右拖拽容器、文本代码比对、抽屉组件、增强选择器、树算法测试台）：

# 启动本地演练场（真实加载 npm 已发布的 c-admin-kit）
pnpm run dev:playground

# 打包纯静态 SPA 站点（输出至 playground/dist/）
pnpm run build:playground

# 本地快速预览打包产物
pnpm run preview:playground

🚀 部署至 Cloudflare Pages 步骤：

1. 登录 Cloudflare 控制台，进入 Workers & Pages -> Create application -> Pages -> Connect to Git；
2. 选择本仓库，配置构建设置：
   • Root directory: playground
   • Framework preset: Vite
   • Build command: pnpm run build
   • Build output directory: dist
3. 点击 Save and Deploy，即可自动从 NPM 官方拉取最新发布的 c-admin-kit 并部署为全球 CDN 静态网页。

📄 授权协议

MIT License © 2026 wllcyg