mc-pro-ui/README.md

一个功能强大的 Vue 3 UI 组件库，提供完整的 TypeScript 支持

# mc-pro-ui

一个功能强大的 Vue 3 UI 组件库，提供完整的 TypeScript 支持，基于 Element Plus 构建，包含专业的表格、表单、搜索等组件。

## ✨ 特性

- 🚀 **Vue 3 + TypeScript** - 完全支持 Vue 3 Composition API 和 TypeScript
- 🎨 **Element Plus 集成** - 基于 Element Plus 构建，保持一致的视觉风格
- 📊 **专业表格组件** - ProTable 支持搜索、分页、列设置、拖拽排序等
- 🔍 **智能搜索表单** - SearchForm 支持响应式布局和多种表单控件
- 📝 **高级表单组件** - ProForm 支持动态表单和复杂布局
- 🎯 **响应式网格系统** - Grid 组件支持断点响应式布局
- 🎭 **灵活对话框** - Dialog 组件支持多种配置选项
- 🔧 **开箱即用** - 提供完整的类型定义和示例代码

## 📦 安装

```bash
npm install mc-pro-ui
# 或
yarn add mc-pro-ui
# 或
pnpm add mc-pro-ui
```

## 🔧 使用

### 完整引入

```typescript
import { createApp } from 'vue'
import mcProUi from 'mc-pro-ui'
import 'mc-pro-ui/dist/style.css'

const app = createApp(App)
app.use(mcProUi)
app.mount('#app')
```

### 按需引入

```typescript
import { createApp } from 'vue'
import { ProTable, SearchForm, ProForm, Grid, Dialog } from 'mc-pro-ui'
import 'mc-pro-ui/dist/style.css'

const app = createApp(App)
app.component('ProTable', ProTable)
app.component('SearchForm', SearchForm)
app.component('ProForm', ProForm)
app.component('Grid', Grid)
app.component('Dialog', Dialog)
app.mount('#app')
```

## 🎯 组件使用

### ProTable - 专业表格组件

功能强大的表格组件，支持搜索、分页、列设置、拖拽排序等。

```vue
<template>
  <ProTable
    :columns="columns"
    :request-api="getTableList"
    :pagination="true"
    :tool-button="['refresh', 'setting', 'search']"
    @search="handleSearch"
    @reset="handleReset"
  >
    <!-- 自定义表格头部 -->
    <template #tableHeader="{ selectedList, isSelected }">
      <el-button 
        type="primary" 
        :disabled="!isSelected"
        @click="handleBatchDelete(selectedList)"
      >
        批量删除
      </el-button>
    </template>

    <!-- 自定义操作列 -->
    <template #operation="{ row }">
      <el-button type="primary" @click="handleEdit(row)">编辑</el-button>
      <el-button type="danger" @click="handleDelete(row)">删除</el-button>
    </template>
  </ProTable>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { ProTable } from 'mc-pro-ui'
import type { ColumnProps } from 'mc-pro-ui'

// 表格列配置
const columns: ColumnProps[] = [
  {
    type: 'selection',
    width: 55,
    align: 'center'
  },
  {
    type: 'index',
    label: '序号',
    width: 60,
    align: 'center'
  },
  {
    prop: 'name',
    label: '姓名',
    search: {
      el: 'input',
      props: {
        placeholder: '请输入姓名'
      }
    }
  },
  {
    prop: 'age',
    label: '年龄',
    search: {
      el: 'input-number',
      props: {
        placeholder: '请输入年龄'
      }
    }
  },
  {
    prop: 'status',
    label: '状态',
    search: {
      el: 'select',
      props: {
        placeholder: '请选择状态'
      },
      enum: [
        { label: '启用', value: 1 },
        { label: '禁用', value: 0 }
      ]
    },
    tag: true
  },
  {
    prop: 'operation',
    label: '操作',
    width: 180,
    align: 'center',
    fixed: 'right'
  }
]

// 获取表格数据
const getTableList = async (params: any) => {
  // 模拟 API 请求
  const response = await fetch('/api/users', { params })
  return response.json()
}

const handleSearch = () => {
  console.log('搜索')
}

const handleReset = () => {
  console.log('重置')
}

const handleEdit = (row: any) => {
  console.log('编辑', row)
}

const handleDelete = (row: any) => {
  console.log('删除', row)
}

const handleBatchDelete = (selectedList: any[]) => {
  console.log('批量删除', selectedList)
}
</script>
```

### SearchForm - 智能搜索表单

响应式搜索表单组件，支持多种表单控件和布局配置。

```vue
<template>
  <SearchForm
    :columns="searchColumns"
    :search-param="searchParam"
    :search-col="{ xs: 1, sm: 2, md: 3, lg: 4, xl: 5 }"
    @search="handleSearch"
    @reset="handleReset"
  >
    <template #searchButton>
      <el-button type="primary" @click="handleSearch">搜索</el-button>
      <el-button @click="handleReset">重置</el-button>
    </template>
  </SearchForm>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { SearchForm } from 'mc-pro-ui'
import type { ColumnProps } from 'mc-pro-ui'

const searchParam = ref({
  name: '',
  age: '',
  status: ''
})

const searchColumns: ColumnProps[] = [
  {
    prop: 'name',
    label: '姓名',
    search: {
      el: 'input',
      props: {
        placeholder: '请输入姓名'
      }
    }
  },
  {
    prop: 'age',
    label: '年龄',
    search: {
      el: 'input-number',
      props: {
        placeholder: '请输入年龄'
      }
    }
  },
  {
    prop: 'status',
    label: '状态',
    search: {
      el: 'select',
      props: {
        placeholder: '请选择状态'
      },
      enum: [
        { label: '启用', value: 1 },
        { label: '禁用', value: 0 }
      ]
    }
  }
]

const handleSearch = () => {
  console.log('搜索参数:', searchParam.value)
}

const handleReset = () => {
  searchParam.value = {
    name: '',
    age: '',
    status: ''
  }
}
</script>
```

### ProForm - 高级表单组件

支持动态表单和复杂布局的表单组件。

```vue
<template>
  <ProForm
    :form-json="formConfig"
    :form-col="{ xs: 24, sm: 12, md: 8, lg: 6, xl: 4 }"
  />
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { ProForm } from 'mc-pro-ui'

const formConfig = ref({
  config: {
    labelWidth: '120px',
    labelPosition: 'right'
  },
  fields: {
    name: {
      label: '姓名',
      el: 'input',
      props: {
        placeholder: '请输入姓名'
      }
    },
    age: {
      label: '年龄',
      el: 'input-number',
      props: {
        placeholder: '请输入年龄',
        min: 0,
        max: 150
      }
    },
    gender: {
      label: '性别',
      el: 'radio-group',
      options: [
        { label: '男', value: 'male' },
        { label: '女', value: 'female' }
      ]
    },
    city: {
      label: '城市',
      el: 'select',
      options: [
        { label: '北京', value: 'beijing' },
        { label: '上海', value: 'shanghai' },
        { label: '广州', value: 'guangzhou' }
      ]
    }
  }
})
</script>
```

### Grid - 响应式网格系统

基于 CSS Grid 的响应式布局系统。

```vue
<template>
  <Grid :cols="{ xs: 1, sm: 2, md: 3, lg: 4, xl: 6 }" :gap="[20, 20]">
    <GridItem v-for="i in 12" :key="i" :span="1">
      <div class="grid-item">
        Grid Item {{ i }}
      </div>
    </GridItem>
  </Grid>
</template>

<script setup lang="ts">
import { Grid, GridItem } from 'mc-pro-ui'
</script>

<style scoped>
.grid-item {
  background: #f5f5f5;
  padding: 20px;
  text-align: center;
  border-radius: 4px;
}
</style>
```

### Dialog - 灵活对话框

可配置的对话框组件。

```vue
<template>
  <Dialog
    v-model="dialogVisible"
    title="用户信息"
    width="600px"
    :draggable="true"
    @confirm="handleConfirm"
  >
    <div>对话框内容</div>
  </Dialog>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { Dialog } from 'mc-pro-ui'

const dialogVisible = ref(false)

const handleConfirm = () => {
  console.log('确认')
  dialogVisible.value = false
}
</script>
```

## 🔧 API 配置

### ProTable Props

| 参数 | 说明 | 类型 | 默认值 |
|------|------|------|--------|
| columns | 列配置项 | ColumnProps[] | [] |
| data | 静态表格数据 | any[] | - |
| requestApi | 请求表格数据的 API | Function | - |
| requestAuto | 是否自动执行请求 | boolean | true |
| pagination | 是否需要分页组件 | boolean | true |
| toolButton | 功能按钮配置 | string[] \| boolean | false |
| rowKey | 行数据的 Key | string | 'id' |
| searchCol | 搜索项每列占比配置 | number \| Record<BreakPoint, number> | { xs: 1, sm: 2, md: 3, lg: 4, xl: 5 } |

### SearchForm Props

| 参数 | 说明 | 类型 | 默认值 |
|------|------|------|--------|
| columns | 搜索列配置 | ColumnProps[] | [] |
| searchParam | 搜索参数 | object | {} |
| searchCol | 搜索项每列占比配置 | number \| Record<BreakPoint, number> | { xs: 1, sm: 2, md: 3, lg: 4, xl: 5 } |

### Grid Props

| 参数 | 说明 | 类型 | 默认值 |
|------|------|------|--------|
| cols | 列数配置 | number \| Record<BreakPoint, number> | 12 |
| gap | 间距配置 | number \| [number, number] | 0 |

## 🎨 样式定制

组件库使用 CSS 变量，可以通过覆盖变量来自定义样式：

```css
:root {
  --mc-primary-color: #409eff;
  --mc-success-color: #67c23a;
  --mc-warning-color: #e6a23c;
  --mc-danger-color: #f56c6c;
  --mc-info-color: #909399;
}
```

## 📚 类型定义

完整的 TypeScript 类型定义：

```typescript
import type { 
  ColumnProps, 
  SearchProps, 
  ProTableProps,
  RenderScope,
  HeaderRenderScope 
} from 'mc-pro-ui'
```

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

## 📄 许可证

[MIT License](LICENSE)

## 🔗 相关链接

- [Vue 3](https://vuejs.org/)
- [Element Plus](https://element-plus.org/)
- [TypeScript](https://www.typescriptlang.org/)

## 🛠️ 开发指南

### 本地开发

```bash
# 安装依赖
npm install

# 启动开发服务器
npm run dev

# 类型检查
npm run type-check

# 代码格式化
npm run format

# 代码检查
npm run lint
```

### 构建和发布

```bash
# 构建项目
npm run build

# 发布到 npm（自动构建 + 发布）
npm run publish:lib
```

**注意：** 发布时会自动执行构建，无需手动构建。

### 项目结构

```
npm-pro-ui/
├── packages/           # 组件库源码
│   ├── components/     # 组件
│   ├── hooks/         # 组合式函数
│   ├── types/         # 类型定义
│   ├── utils/         # 工具函数
│   └── index.ts       # 入口文件
├── dist/              # 构建输出
├── vite.config.ts     # Vite 配置
├── package.json       # 项目配置
└── README.md          # 项目文档
```