@yetuzi/vue3-query-components

@yetuzi/vue3-query-components

✨ 特性

• 🚀 一体化查询 - CommonQueryTable 集成表单、表格、分页，一个组件即可构建完整的查询页面，支持灵活的布局配置
• 📋 类型安全 - 完整的 TypeScript 泛型支持，列类型、表单项类型自动推导，提供精准的类型提示和校验
• 🎨 高度可定制 - 响应式全局配置系统，支持自定义组件、插槽和样式扩展，满足各种业务场景需求
• 🧩 丰富组件 - 提供 CommonTable（多种列类型）、CommonForm（7种表单项）及完整的基础组件体系
• ⚡️ 开箱即用 - 基于 Element Plus 封装，API 设计一致，学习成本低，大幅提升开发效率
• 🛠️ 实用工具 - 内置 useResettable 等实用 hooks，提供可重置的响应式数据管理能力

📦 安装

npm install @yetuzi/vue3-query-components
# 或
yarn add @yetuzi/vue3-query-components
# 或
pnpm add @yetuzi/vue3-query-components

🚀 快速开始

安装依赖

npm install @yetuzi/vue3-query-components

::: tip 注意 本组件库依赖 Element Plus，但不需要手动安装 Element Plus，它作为 peer dependency 会在你的项目中自动解析。 :::

导入样式

// 导入组件库样式（已包含所需的 Element Plus 样式）
import '@yetuzi/vue3-query-components/dist/index.css'

按需引入组件

import {
  CommonQueryTable,
  CommonTable,
  CommonForm,
  CommonConfigProvider,
} from '@yetuzi/vue3-query-components'

4. 基础使用

完整查询表格组件（推荐）

CommonQueryTable 是一个高度集成的组件，包含表单查询、表格展示、分页功能。

<template>
  <CommonQueryTable :fetch="fetchData" :form="formConfig" :columns="tableColumns" />
</template>

<script setup>
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 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: 'email', label: '邮箱' },
  { prop: 'status', label: '状态' },
  {
    prop: 'createTime',
    label: '创建时间',
    type: 'dateTime', // 自动格式化日期时间
  },
]
</script>

高级配置示例

<template>
  <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 { 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>

📚 组件列表

核心组件

基础组件

Hooks

📚 API 文档

CommonQueryTable Props

表单组件类型支持

CommonForm 支持以下 7 种内置表单项类型：

表格列类型支持

CommonTable 支持多种特殊列类型：

表单配置项类型

interface FormItemConfig {
  is: string // 组件类型
  prop: string // 字段名
  formItem: {
    // ElFormItem 配置
    label: string
    [key: string]: any
  }
  initialValue?: any // 初始值
  props?: {
    // 组件属性
    [key: string]: any
  }
}

表格列配置类型

interface TableColumn {
  prop: string                  // 列属性名
  label: string                 // 列标题
  type?: 'dateTime'            // 特殊类型：自动格式化日期时间
  width?: string \| number      // 列宽度
  fixed?: boolean \| 'left' \| 'right'  // 固定列
  [key: string]: https://github.com/yetuzi-open/vue3-query-components/blob/HEAD/any           // 其他 ElTableColumn 属性
}

🎨 全局配置

使用 CommonConfigProvider 可以全局配置组件样式和行为：

<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>

🛠️ 开发

环境要求

• Node.js >= 16.0.0
• Vue 3.5+
• Element Plus 2.11+
• TypeScript 5.9+

依赖说明

Peer Dependencies（需要宿主项目安装）

{
  "peerDependencies": {
    "vue": "^3.5.0",
    "element-plus": "^2.11.5"
  }
}

::: tip 关于 Element Plus 组件库的 CSS 文件已包含所需的 Element Plus 组件样式，你只需要确保项目中安装了 Element Plus 即可，不需要单独导入 Element Plus 的样式。 :::

Dependencies（随组件库一起安装）

{
  "dependencies": {
    "dayjs": "^1.11.18",
    "lodash-es": "^4.17.21",
    "vue-hooks-plus": "^2.4.1"
  }
}

构建产物

组件库构建后生成以下文件：

dist/
├── index.js       # ES Module 格式的组件代码
├── index.d.ts     # TypeScript 类型声明文件
├── index.css      # 组件库样式（包含 Element Plus 组件样式）
└── index.js.map   # Source Map 文件

重要说明：

• 组件库采用 ES Module 格式输出
• CSS 文件已包含所有所需的 Element Plus 组件样式（约 129KB，gzip 后约 17KB）
• Vue 和 Element Plus JS 模块被外部化，不会打包进组件库（减小体积）

🎯 使用场景

本组件库特别适用于：

• 企业后台管理系统 - 大量数据查询、展示、分页场景
• 数据报表页面 - 需要复杂查询条件的数据展示
• CRUD 操作页面 - 增删改查的标准业务页面
• 列表展示页面 - 各种数据列表的展示和筛选

📄 许可证

MIT

📞 支持与反馈

如有问题或建议，请提交 Issue：

• GitHub Issues
• Gitee Issues

🗺️ 更新日志

查看详细的更新日志：CHANGELOG.md

Made with ❤️ by yetuzi