@yetuzi/vue3-query-components 1.0.1 → 1.0.2

package/README.md

@@ -1,15 +1,18 @@
-# Vue3 Query Components
+# @yetuzi/vue3-query-components
 
-基于 Vue 3 + Element Plus 的查询页面组件库，专注于表格查询场景，开箱即用。
+基于 Vue 3 + Element Plus 的企业级查询页面组件库，专注于表格查询场景，开箱即用。
 
 ## ✨ 特性
 
 - 🚀 **开箱即用** - 高度封装的业务组件，减少重复开发
-- 🎨 **统一设计** - 基于 Element Plus 设计语言
+- 🎨 **统一设计** - 基于 Element Plus 设计语言，支持全局配置
 - 🔧 **高度可配置** - 灵活的配置选项，满足不同业务需求
-- 📦 **TypeScript 支持** - 完整的类型定义
+- 📦 **TypeScript 支持** - 完整的类型定义，类型安全
 - 🌳 **Tree Shaking** - 按需引入，减小打包体积
 - 🔥 **热更新** - 支持开发模式热更新
+- 🎯 **业务导向** - 专注于查询、表单、表格等常见业务场景
+- 🔄 **状态管理** - 内置数据请求、分页、表单状态管理
+- 🎨 **插槽支持** - 灵活的插槽系统，支持自定义扩展
 
 ## 📦 安装
 
@@ -29,6 +32,7 @@ pnpm add @yetuzi/vue3-query-components
 import { createApp } from 'vue'
 import Vue3QueryComponents from '@yetuzi/vue3-query-components'
 import '@yetuzi/vue3-query-components/dist/style.css'
+import 'element-plus/theme-chalk/index.css' // 需要安装 Element Plus
 
 const app = createApp(App)
 app.use(Vue3QueryComponents)
@@ -37,129 +41,246 @@ app.use(Vue3QueryComponents)
 ### 2. 按需引入
 
 ```typescript
-import { CommonTable, CommonForm } from '@yetuzi/vue3-query-components'
+import {
+  CommonQueryTable,
+  CommonTable,
+  CommonForm,
+  CommonConfigProvider
+} from '@yetuzi/vue3-query-components'
 import '@yetuzi/vue3-query-components/dist/style.css'
+import 'element-plus/theme-chalk/index.css' // 需要安装 Element Plus
 ```
 
 ### 3. 基础使用
 
-#### 表格组件
+#### 完整查询表格组件（推荐）
+
+`CommonQueryTable` 是一个高度集成的组件，包含表单查询、表格展示、分页功能。
 
 ```vue
 <template>
-  <CommonTable
-    :columns="columns"
-    :data="tableData"
-    :loading="loading"
-    :pagination="pagination"
-    @page-change="handlePageChange"
-  />
+  <CommonQueryTable :fetch="fetchData" :form="formConfig" :columns="tableColumns" />
 </template>
 
 <script setup>
-import { ref } from 'vue'
-import { CommonTable } from '@yetuzi/vue3-query-components'
+import { CommonQueryTable } from '@yetuzi/vue3-query-components'
+
+// 数据请求函数
+const fetchData = async (params) => {
+  const { pageNo, pageSize, ...searchParams } = params
+  const response = await api.getList({
+    page: pageNo,
+    size: pageSize,
+    ...searchParams,
+  })
+  return {
+    list: response.data.list,
+    total: response.data.total,
+  }
+}
 
-const columns = ref([
+// 表单配置
+const formConfig = [
+  {
+    is: 'input', // 组件类型
+    prop: 'name', // 字段名
+    formItem: {
+      label: '姓名', // 表单标签
+    },
+    initialValue: '', // 初始值
+    props: {
+      placeholder: '请输入姓名',
+    },
+  },
+  {
+    is: 'select',
+    prop: 'status',
+    formItem: {
+      label: '状态',
+    },
+    initialValue: 'all',
+    props: {
+      options: [
+        { value: 'all', label: '全部' },
+        { value: 'active', label: '激活' },
+        { value: 'inactive', label: '未激活' },
+      ],
+    },
+  },
+  {
+    is: 'date-picker',
+    prop: 'createTime',
+    formItem: {
+      label: '创建时间',
+    },
+  },
+]
+
+// 表格列配置
+const tableColumns = [
   { prop: 'name', label: '姓名' },
-  { prop: 'age', label: '年龄' },
-  { prop: 'email', label: '邮箱' }
-])
-
-const tableData = ref([
-  { name: '张三', age: 25, email: 'zhangsan@example.com' },
-  { name: '李四', age: 30, email: 'lisi@example.com' }
-])
-
-const loading = ref(false)
-const pagination = ref({
-  current: 1,
-  pageSize: 10,
-  total: 100
-})
-
-function handlePageChange(page) {
-  pagination.value.current = page
-  // 加载数据
-}
+  { prop: 'email', label: '邮箱' },
+  { prop: 'status', label: '状态' },
+  {
+    prop: 'createTime',
+    label: '创建时间',
+    type: 'dateTime', // 自动格式化日期时间
+  },
+]
 </script>
 ```
 
-#### 表单组件
+#### 高级配置示例
 
 ```vue
 <template>
-  <CommonForm
-    :model="formModel"
-    :items="formItems"
-    @submit="handleSubmit"
-    @reset="handleReset"
-  />
+  <CommonConfigProvider
+    :component="{
+      form: {
+        submitText: '查询',
+        resetText: '重置',
+        formItem: {
+          components: {
+            width: '240px',
+          },
+        },
+      },
+      pagination: {
+        defaultPageSize: 20,
+        defaultPageCount: 1,
+      },
+      table: {
+        headerCellStyle: {
+          backgroundColor: '#f5f7fa',
+          color: '#303133',
+        },
+      },
+    }"
+  >
+    <CommonQueryTable
+      v-bind="queryTableConfig"
+      :layouts="['form', 'toolbar', 'table', 'pagination']"
+    >
+      <!-- 自定义工具栏 -->
+      <template #toolbar>
+        <el-button type="primary" @click="handleAdd">新增</el-button>
+        <el-button @click="handleExport">导出</el-button>
+      </template>
+
+      <!-- 自定义表格列 -->
+      <template #table-action="{ row }">
+        <el-button link @click="handleEdit(row)">编辑</el-button>
+        <el-button link type="danger" @click="handleDelete(row)">删除</el-button>
+      </template>
+    </CommonQueryTable>
+  </CommonConfigProvider>
 </template>
 
 <script setup>
-import { ref } from 'vue'
-import { CommonForm } from '@yetuzi/vue3-query-components'
+import { CommonConfigProvider, CommonQueryTable } from '@yetuzi/vue3-query-components'
+
+const queryTableConfig = {
+  fetch: fetchData,
+  form: formConfig,
+  columns: [
+    { prop: 'name', label: '姓名' },
+    { prop: 'status', label: '状态' },
+    { label: '操作', prop: 'action', fixed: 'right', width: 150 },
+  ],
+}
+</script>
+```
 
-const formModel = ref({
-  name: '',
-  email: '',
-  age: null
-})
+## 📚 组件文档
 
-const formItems = ref([
-  {
-    prop: 'name',
-    label: '姓名',
-    type: 'input',
-    rules: [{ required: true, message: '请输入姓名' }]
-  },
-  {
-    prop: 'email',
-    label: '邮箱',
-    type: 'input',
-    rules: [{ type: 'email', message: '请输入正确的邮箱格式' }]
-  },
-  {
-    prop: 'age',
-    label: '年龄',
-    type: 'number'
-  }
-])
+### CommonQueryTable Props
 
-function handleSubmit() {
-  console.log('提交表单:', formModel.value)
-}
+| 参数    | 说明         | 类型                                                                     | 默认值                            |
+| ------- | ------------ | ------------------------------------------------------------------------ | --------------------------------- |
+| fetch   | 数据请求函数 | `(params: ListParam) => Promise<{ list: T[], total: string \| number }>` | -                                 |
+| form    | 表单配置数组 | `CommonFormPropForm[]`                                                   | []                                |
+| columns | 表格列配置   | `CommonTableColumn[]`                                                    | -                                 |
+| layouts | 布局顺序     | `Array<'header'\|'form'\|'toolbar'\|'table'\|'pagination'\|'footer'>`    | `['form', 'table', 'pagination']` |
+
+### 表单组件类型支持
+
+支持以下表单组件类型：
+
+- `input` - 输入框
+- `select` - 下拉选择
+- `date-picker` - 日期选择器
+- `radio` - 单选框组
+- `check-box` - 复选框组
+- `switch` - 开关
 
-function handleReset() {
-  console.log('重置表单')
+### 表单配置项类型
+
+```typescript
+interface FormItemConfig {
+  is: string // 组件类型
+  prop: string // 字段名
+  formItem: {
+    // ElFormItem 配置
+    label: string
+    [key: string]: any
+  }
+  initialValue?: any // 初始值
+  props?: {
+    // 组件属性
+    [key: string]: any
+  }
 }
-</script>
 ```
 
-## 📚 API 文档
+### 表格列配置类型
 
-### CommonTable Props
+```typescript
+interface TableColumn {
+  prop: string                  // 列属性名
+  label: string                 // 列标题
+  type?: 'dateTime'            // 特殊类型：自动格式化日期时间
+  width?: string \| number      // 列宽度
+  fixed?: boolean \| 'left' \| 'right'  // 固定列
+  [key: string]: any           // 其他 ElTableColumn 属性
+}
+```
 
-| 参数 | 说明 | 类型 | 默认值 |
-|------|------|------|--------|
-| columns | 表格列配置 | `Column[]` | - |
-| data | 表格数据 | `any[]` | [] |
-| loading | 加载状态 | `boolean` | false |
-| pagination | 分页配置 | `PaginationConfig` | - |
-| border | 是否显示边框 | `boolean` | true |
-| stripe | 是否显示斑马纹 | `boolean` | true |
+## 🎨 全局配置
 
-### CommonForm Props
+使用 `CommonConfigProvider` 可以全局配置组件样式和行为：
 
-| 参数 | 说明 | 类型 | 默认值 |
-|------|------|------|--------|
-| model | 表单数据对象 | `object` | - |
-| items | 表单项配置 | `FormItem[]` | - |
-| labelWidth | 标签宽度 | `string \| number` | '100px' |
-| inline | 是否行内表单 | `boolean` | false |
-| submitText | 提交按钮文本 | `string` | '提交' |
-| resetText | 重置按钮文本 | `string` | '重置' |
+```vue
+<template>
+  <CommonConfigProvider
+    :component="{
+      placeholder: '暂无数据', // 空值占位
+      pagination: {
+        defaultPageCount: 1, // 默认起始页
+        defaultPageSize: 10, // 默认每页条数
+      },
+      table: {
+        headerCellStyle: {
+          // 表头样式
+          backgroundColor: '#f1f6ff',
+          color: '#000000',
+          height: '48px',
+        },
+      },
+      form: {
+        submitText: '搜索', // 提交按钮文本
+        resetText: '重置', // 重置按钮文本
+        formItem: {
+          components: {
+            width: '200px', // 表单组件宽度
+          },
+        },
+      },
+    }"
+  >
+    <YourApp />
+  </CommonConfigProvider>
+</template>
+```
 
 ## 🛠️ 开发
 
@@ -168,13 +289,14 @@ function handleReset() {
 - Node.js >= 16.0.0
 - Vue 3.5+
 - Element Plus 2.11+
+- TypeScript 5.9+
 
 ### 本地开发
 
 ```bash
 # 克隆项目
 git clone https://gitee.com/yetuzi/vue3-common.git
-cd vue3-common/common
+cd vue3-common/vue3-query-components
 
 # 安装依赖
 npm install
@@ -193,15 +315,36 @@ npm run format
 
 # Lint
 npm run lint
+
+# 测试
+npm test
 ```
 
-### 测试
+### 依赖说明
 
-```bash
-# 运行测试
-npm test
+```json
+{
+  "peerDependencies": {
+    "vue": "^3.5.0",              // Vue 3 - 需要宿主项目安装
+    "element-plus": "^2.11.5"     // Element Plus UI 库 - 需要宿主项目安装
+  },
+  "dependencies": {
+    "dayjs": "^1.11.18",          // 日期处理库
+    "lodash-es": "^4.17.21",      // 工具函数库
+    "vue-hooks-plus": "^2.4.1"    // Vue 组合式 API 工具库
+  }
+}
 ```
 
+## 🎯 使用场景
+
+本组件库特别适用于：
+
+- **企业后台管理系统** - 大量数据查询、展示、分页场景
+- **数据报表页面** - 需要复杂查询条件的数据展示
+- **CRUD 操作页面** - 增删改查的标准业务页面
+- **列表展示页面** - 各种数据列表的展示和筛选
+
 ## 📄 许可证
 
 [MIT](./LICENSE)
@@ -214,9 +357,16 @@ npm test
 
 如有问题，请提交 [Issue](https://gitee.com/yetuzi/vue3-common/issues)
 
-## 🗺️ 路线图
+## 🗺️ 更新日志
+
+### v1.0.1 (2024-12-10)
+
+- 📝 更新 README.md 包名引用
+- ✨ 完善文档和使用示例
+- 🔧 优化组件配置系统
+
+### v1.0.0
 
-- [ ] 更多业务组件（抽屉、模态框等）
-- [ ] 国际化支持
-- [ ] 主题定制功能
-- [ ] 单元测试覆盖
+- 🎉 初始版本发布
+- ✨ 包含完整的查询表格组件体系
+- 📦 支持全局配置和主题定制