JV-ComponentsV3

简介

JV-ComponentsV3 是一个功能强大的组件库，旨在帮助开发者快速搭建前端项目。该组件库包含了一系列常用的组件，如表格、表单元素、文件上传等，能够显著提高开发效率。

组件列表

| 组件名 | 描述 | | --- | --- | | JvTable.vue | 表格组件，用于展示和处理数据。支持排序、筛选、分页等功能。 | | formItem.vue | 表单元素组件，用于构建表单。 | | uplaodFile.vue | 文件上传组件，支持多文件上传、进度显示等功能。 |

项目管理页面详细使用文档

智能表格组件（jvTable）

核心配置对象（tableCfg）

const tableCfg = {
  queryParams: { pageSize: 10 },       // 分页默认参数（pageSize: 每页条数）
  tableSelection: false,              // 是否启用多选列（false: 禁用）
  tableIndex: true,                   // 是否显示行号列（true: 显示）
  actionList: [ /* 操作按钮配置 */ ],  // 表格操作列配置
  searchList: [ /* 搜索表单配置 */ ],  // 顶部搜索栏配置
  searchFn: getList,                  // 搜索/分页触发时的回调函数
  tableList: [ /* 表格列配置 */ ]      // 表格列定义
}

操作按钮（actionTable）

当前配置「新增」按钮，点击触发抽屉表单弹出逻辑：

actionList: [
  { 
    name: "新增",          // 按钮显示名称
    fn: () => {             // 点击回调函数
      drawerDialogSearchToggle.value = true;  // 控制抽屉显示
    }
  }
]

搜索表单（searchList）

支持8个搜索条件，分为基础搜索（默认显示）和扩展搜索（折叠显示）：

| 字段名称 | 类型 | 说明 | 扩展字段 | |----------------|------------|----------------------------------------------------------------------|----------| | 排序方式 | select | 数据源：sys_normal_disable（需全局注册） | 否 | | 年度 | date | 日期类型：year（仅选择年份），显示格式：YYYY年度 | 否 | | 承担部门 | select | 数据源：sys_normal_disable | 否 | | 项目名称 | input | 支持关键词搜索（提示："项目名称、编号关键词"） | 否 | | 业务号 | input | 默认折叠的扩展搜索字段 | 是 | | 下达时间 | date | 默认折叠的扩展搜索字段（日期类型） | 是 | | 项目类型 | select | 默认折叠的扩展搜索字段（数据源：sys_normal_disable） | 是 | | 项目性质 | select | 默认折叠的扩展搜索字段（数据源：sys_normal_disable） | 是 |

表格列（tableList）

与后端数据字段一一映射的展示列配置：

tableList: [
  { label: "项目业号", prop: "createBy" },  // label: 表头名称, prop: 数据字段名
  { label: "承担部门", prop: "postCode" },
  { label: "项目负责人", prop: "status" },
  { label: "委托单位", prop: "createTime" },
  { label: "合同金额(元)", prop: "postId" }
]

抽屉式新增表单（el-drawer）

表单控制

通过drawerDialogSearchToggle响应式变量控制显隐（true: 显示，false: 隐藏）。

表单字段配置（formList）

支持7种字段类型，覆盖输入、选择、日期、文件上传等常见场景：

4.2.1 通用配置项

| 参数名 | 类型 | 说明 | 是否必填 | |--------------|------------|----------------------------------------------------------------------|----------| | name | String | 字段显示名称（如"项目业务号"） | 是 | | type | String | 字段类型（input/select/date/radio/uplaodFile） | 是 | | key | String | 绑定到form对象的属性名（如"accountId"） | 是 | | list | String | 下拉/单选的数据源（需全局注册，如"sys_yes_no"） | 否（select/radio必填） |

文件上传特殊配置

{ 
  name: "请上传公文附件",
  type: "uplaodFile",
  isRow: true,               // 是否占满整行（true: 宽屏显示）
  limit: 9,                  // 最大上传文件数（9个）
  tips: "单个文件上传不能超过10M",  // 提示文案
  filebaseUrl: import.meta.env.VITE_APP_BASE_API,  // 文件访问基础URL
  axiosCfg: {               // 上传请求配置
    url: "/common/upload",  // 上传接口地址
    headers: {              // 请求头（携带认证token）
      'Authorization': 'Bearer ' + getToken()
    },
    resFn: (res) => {       // 响应处理函数（需返回{url: 文件地址}）
      return { url: res.fileName }
    }
  }
}

表单提交

点击「提交」按钮触发submit方法，当前实现为打印表单数据，实际使用需补充接口调用逻辑：

function submit() {
  // 实际使用建议添加：
  // 1. 表单验证（通过$refs.formListRef.validate）
  // 2. 调用接口提交数据（proxy.$req("/api/submit", { method: "POST", data: form.value })）
  // 3. 关闭抽屉并刷新表格数据（drawerDialogSearchToggle.value = false; getList()）
  console.log("提交的表单数据：", form.value)
}

核心方法详解

getList(p, reset) - 数据加载函数

功能：获取表格数据并处理分页 参数：

• p（Object）：当前搜索参数（包含分页信息pageNum/pageSize）
• reset（Boolean）：是否重置分页（true: 重置为第1页）

实现逻辑：

function getList(p, reset) {
  // 1. 处理分页参数
  let p2 = { ...p };
  if (!reset) Object.assign(p2);  // 非重置时保留当前分页

  // 2. 调用后端接口（示例使用模拟数据，实际需替换）
  return new Promise((resolve) => {
    proxy.$req("/system/post/list", { method: "GET", params: p2 })
      .then(res => {
        // 3. 模拟数据扩展（实际删除此逻辑）
        resolve({ list: res.rows.concat(res.rows), total: res.total });
      });
  });
}

接口对接注意事项

• 后端接口需返回标准分页结构：{ rows: 数据列表, total: 总条数 }
• 搜索参数p会自动包含searchList中所有字段的当前值
• 分页参数通过queryParams.pageSize控制每页条数

常见问题排查

统计卡片数值不更新

• 检查dataList中对应val值是否被正确修改（需通过dataList.value[index].val = newVal触发响应式更新）
• 确认count-to组件是否正确引入（需在全局或当前页面注册）

搜索条件未生效

• 检查searchList中key是否与后端接口参数名一致
• 确认searchFn是否正确传递参数（可通过console.log(p)打印参数验证）

文件上传失败

• 检查axiosCfg.url是否与后端上传接口地址一致
• 确认Authorization头是否正确携带（可通过浏览器开发者工具查看请求头）
• 检查后端返回格式是否符合resFn要求（需包含fileName字段）

扩展开发建议

1. 表单验证：在submit方法中添加$refs.formListRef.validate进行表单校验
2. 批量操作：可扩展actionTable添加「编辑」「删除」按钮，实现数据全生命周期管理
3. 导出功能：在searchList中添加「导出」按钮，调用后端导出接口生成Excel文件
4. 权限控制：根据用户角色动态显示/隐藏操作按钮（通过v-if结合权限判断）

贡献指南

1. Fork 本仓库
2. 创建你的特性分支 (git checkout -b feature/AmazingFeature)
3. 提交你的更改 (git commit -m 'Add some AmazingFeature')
4. 将更改推送到特性分支 (git push origin feature/AmazingFeature)
5. 打开一个 Pull Request

许可证

本项目采用 MIT 许可证。