jtxa-ui

jtxa-ui

基于 Vue 3 + VxeTable + Element Plus + ECharts 的企业级组件库

jtxa-ui 把项目中高频使用的「动态表单、表格（含树表/分组表/大数据增量表）、文件分片上传、ECharts 图表、高级查询构造器、管理树表页面」封装为一套开箱即用的 Vue 3 组件，统一了 VxeTable 与 Element Plus 的注册与样式，帮助业务系统快速搭建数据管理类界面。

• 技术栈：Vue ^3.5 · Vite ^7（library mode）· VxeTable ~4.17.38 / vxe-pc-ui 4.11.34 · Element Plus ^2.13 · ECharts ^6
• 仓库：https://gitlab.cdjti.com/pub/jtxa-ui.git
• 作者：leevan

目录

• jtxa-ui
  • 目录
  • 安装
  • 快速上手
    • 全局注册（推荐）
    • 按需引入
  • 组件总览
  • 组件详细文档
    • 1. Form 动态表单（jt-form）
    • 2. JtUpload 分片上传（jt-upload）
    • 3. Echart 图表（jt-chart）
    • 4. SearchType 高级查询（search-type）
    • 5. ManageTreeTable 管理树表（manage-tree-table）
    • 6. TableBase 基础表格（table-base）
    • 7. TableGroup 分组树表（table-group）
    • 8. TableBigData 大数据增量表（table-big-data）
    • 9. TreeTable 虚拟树表（tree-table）
  • 共享表格属性 publicProps
    • usePublicAPI 暴露方法
  • 渲染器清单（cellRender / editRender）
  • 工具函数
  • 已知问题与注意事项
  • 相关文档
  • 开发

安装

# 使用你项目的包管理器安装本库
npm install jtxa-ui
# 或
pnpm add jtxa-ui

jtxa-ui 将 vue、element-plus、echarts 在构建时 external（外部化），因此消费方需自行提供这些运行时依赖（peer）：

# 必须安装的对等依赖
npm install vue@^3.5 element-plus@^2.13 echarts@^6.0

说明：echarts 当前列在 dependencies 中（安装本库时会自动带入），但构建时被 external 化，请确保项目内 echarts 版本为 ^6 且与库兼容；使用图表组件前需保证 echarts 可被模块解析到。

快速上手

全局注册（推荐）

// main.js
import { createApp } from 'vue'
import App from './App.vue'

import ElementPlus from 'element-plus'
import 'element-plus/dist/index.css'

import jtui from 'jtxa-ui'
import 'jtxa-ui/dist/jtxa-ui.css'

const app = createApp(App)
app.use(ElementPlus) // 先注册 Element Plus
app.use(jtui)        // 再注册 jtxa-ui（内部会注册 VxeTable 与一批 Element Plus 组件、指令）
app.mount('#app')

注册后，下列标签即可在模板中直接使用：<jt-form>、<jt-upload>、<jt-chart>、<search-type>、<table-base>、<table-group>、<table-big-data>、<tree-table>。

按需引入

每个子包都自带 .install 方法，可单独 app.use(...)：

import { Form, TableBase, TreeTable } from 'jtxa-ui'
app.use(Form)
app.use(TableBase)
app.use(TreeTable)

⚠️ manage-tree-table 默认不通过 app.use(jtui) 全局注册，使用它时需要局部引入：

<script setup>
import { ManageTreeTable } from 'jtxa-ui'   // 具名导入（推荐）
</script>
<template>
  <manage-tree-table :axios="axios" :config="config" :mode="1" />
</template>

也可 app.use(ManageTreeTable) 做全局注册（packages/manage-tree-table/index.js 已挂 .install）。

组件总览

其余 packages/ 下 60+ 个 .vue 为内部子组件 / 渲染器 / 看板 / 构建部署件，不对外暴露，请勿直接引用。

组件详细文档

1. Form 动态表单（jt-form）

基于 formConfig 数组动态渲染表单，自动处理校验、级联懒加载与辅助输入。

来源：packages/form/index.vue

Props

formConfig 字段 type 支持：empty / upload / custom / text / input / textarea / iNumber / select / select_r / cascader / date / time / switch / checkbox / radio / autocomplete / htmlarea（富文本）。

Events：switchChange · focus · blur · casChange · cusBtn

rules 字符串语法：rules 为对象，key 是 modelKey，value 是规则字符串数组，由内置 Validate（packages/form/validate.js）转换为 Element Plus 规则：

const rules = {
  name:   ['required', 'phone'],    // 必填 + 手机号
  age:    ['num'],                  // 必须是数字
  email:  ['email'],                // 邮箱格式
  code:   ['idCard'],               // 身份证
  remark: ['range-2-10'],           // 长度 2~10（用 “-” 传参）
  ename:  ['letters'],              // 仅英文字母
  tags:   ['requireSelect'],        // 至少选一个（数组）
}

内置校验类型：required · requiredFocus · range-min-max · len-n · num · email · idCard · phone · letters · requireAll · requireSelect。

Slots：

• upload：当字段 type: 'upload' 时，使用 item.slotName（默认 upload）具名插槽渲染上传区；
• custom：当字段 type: 'custom' 时，使用 item.slotName 具名插槽渲染自定义内容。

暴露方法（模板 ref 可访问）：validateAll()（返回 el-form.validate() Promise）· resetAll() · openAutoInput() · casChange · itemClick · switchChange · focus · blur

真实示例（取自 examples/pages/form-page.vue）：

<jt-form
  id="onDutyPoepleSignIn"
  ref="onDutyPoepleSignIn"
  title="测试表单"
  :model="model"
  :formConfig="formConfig"
  label-width="100px"
  labelPosition="right"
  :rules="rules"
  size="small"
  border
  collapseTags
  :axios="axios"
  :lazyLoadParams="lazyLoadParams"
  @switchChange="switchChange"
  :autoInputConfig="autoInputConfig"
></jt-form>

<script setup>
// 校验与重置
const onDutyPoepleSignIn = ref()
await onDutyPoepleSignIn.value.validateAll()
onDutyPoepleSignIn.value.resetAll()
</script>

2. JtUpload 分片上传（jt-upload）

基于 simple-uploader.js 的分片 / 断点续传上传组件，分片上传成功后再请求合并接口。

来源：packages/upload/JtUpload.vue

Props

Events：success(response) · error(rootFile, file, message, chunk) · added(file) · addeds(files, fileList) · removed(file)

暴露方法：getFiles()（返回 fileList）· goOnUpload()（续传）· clearList()

真实示例（取自 examples/pages/form-page.vue）：

<jt-upload
  :autostart="true"
  target="/jtrequest/upf/telemetry_duty/chunk"
  mergePath="/jtrequest/upf/telemetry_duty/mergeFile"
  :axios="axios"
  :simultaneousUploads="4"
  @success="success"
></jt-upload>

在 jt-form 中以 #upload 插槽内嵌（取自 examples/pages/tree-table-page.vue）：

<jt-form id="test123" :model="model" :formConfig="formConfig">
  <template v-slot:upload>
    <div style="width: 400px">
      <jt-upload :target="'currentPage.props.chunk'" :mergePath="'currentPage.props.mergeFile'" />
    </div>
  </template>
</jt-form>

3. Echart 图表（jt-chart）

ECharts 封装：自动计算 Y 轴最大/最小值与刻度精度、按时间范围计算 X 轴间隔、网格线 / 刻度可视化配置弹窗，localStorage 持久化样式。

来源：packages/echarts/index.vue

Props

Events：无显式声明。

暴露方法：getVM()（返回图表实例）

真实示例（取自 examples/pages/jt-echart.vue，多图表 v-for）：

<jt-chart
  v-for="(item, index) in testData"
  :key="index"
  :ref="(el) => setRef(el)"
  :id="('single_chart' + index)"
  :timeRange="item.timeRange"
  :data="item.echartData"
></jt-chart>

4. SearchType 高级查询（search-type）

动态查询条件构造器，支持分组（并且 / 或者）、多查询类型、级联、复选、树选择；内嵌 jt-form 与 TreeSelect。

来源：packages/Search-Type/index.vue

Props

Events：count · initedData

暴露方法：getData()（返回查询条件数组）

真实示例（取自 examples/pages/search.vue）：

<search-type
  v-if="selpath !== '' && options.length"
  ref="searchTypeRef"
  :selected="selpath"
  :options_type="options"
  :axios="axios"
  :listuri="listuri"
  @initedData="initedData"
  @count="count"
></search-type>

<script setup>
// 取构造好的查询条件
const conditions = searchTypeRef.value.getData()
</script>

5. ManageTreeTable 管理树表（manage-tree-table）

顶层「管理树表」页面组件：渲染筛选栏，按 mode / pageMode 派发到不同 mtt-panel-* 版式（看板 / 树表等），处理根查询与单选切换版式。

来源：packages/manage-tree-table/index.vue

⚠️ 该组件不随 app.use(jtui) 全局注册，需局部引入（见快速上手）。

Props

mode 与面板组件映射：mode（或 pageMode）决定渲染哪种版式，内部按值派发到 mtt-panel-* 子组件：

mode 还可由 config.radioData 中某项 style 字段在运行时切换（见 radioChange）。

Events：getBaseParams

Slots：透传父级所有插槽；向面板透传 #cusComp。

暴露方法：search() · initPage()

真实示例（取自 examples/pages/manage-tree-table-page.vue，局部引入写法）：

<script setup>
import axios from 'axios'
import { ref, nextTick } from 'vue'
import mockData from './mock.js'
import { ManageTreeTable } from 'jtxa-ui'
</script>

<template>
  <manage-tree-table
    v-if="load"
    :axios="newAxios"
    :config="queryConfig"
    :mode="1"
    :buttonWidth="btnWidth"
    :accordion="true"
    btnNumLeft="1"
    btnNumRight="0"
    compPath="/test/workNoticeTreeTable/"
  />
</template>

带业务插槽组件（slotConfig）：

<manage-tree-table
  :axios="axios"
  :config="config"
  :mode="queryStyle"
  :slotConfig="compList"
  @getBaseParams="getBaseParams"
  :comp-path="path"
>
  <template v-for="item in compList" #[item.name]="slotData">
    <component :is="item.component" v-if="slotData.slotData == item.buildFun" v-bind="slotData || {}" />
  </template>
</manage-tree-table>

6. TableBase 基础表格（table-base）

VxeTable 基础封装：工具栏、表尾统计、虚拟滚动、单选 / 多选 / 序号、分组表头、展开行、操作列、单元格 / 编辑渲染。

来源：packages/tables/table-base.vue，通用属性见 publicProps。

额外 Props：footConfig(Object, {filed:[]}) · isFooter(Boolean) · spanMethod(Function) · isSortable(Boolean) · openVirtual(Boolean)

Events：customEvents（载荷类型见 publicProps）

Slots：#expandContent（scoped 插槽，展开行内容）

暴露方法：见 usePublicAPI 方法集（含 exportData / loadData / reloadTreeExpand / removeRow / setCheckboxRow / jtTable() 等）+ setStyle / sortMethod

真实示例（取自 examples/pages/table-ptbg.vue）：

<table-base
  id="tableBase"
  ref="tableBase"
  :data="data"
  @customEvents="customEvents"
  :cellRenderMethods="{ cellRenderMethods }"
  :handlerConfig="handlerConfig"
  isTool
  isFooter
  :footConfig="footConfig"
  :expandConfig="expandConfig"
  :spanMethod="spanMethod"
  :rowStyle="rowStyle"
  :cellStyle="cellStyle"
  :loading="loading"
  :isSeq="true"
  :stripe="true"
  isSortable
  :axios="axios"
  :tableStyle="{ headerBg: 'linear-gradient(#F9FAFB,#F9FAFB)', stripeBg: '#F9FAFB', currentBg: 'rgba(24,144,255,.6)' }"
>
  <template #expandContent="slotProps">{{ slotProps }}</template>
</table-base>

7. TableGroup 分组树表（table-group）

在 publicProps 基础上增加 groupField，使用 XEUtils.groupBy 把行归并到父行下形成分组树表。

来源：packages/tables/table-group.vue

额外 Props：groupField(String, 必填) — 用于分组的字段名。

Events：customEvents · Slots：#expandContent · 暴露方法：usePublicAPI + setStyle

真实示例（取自 examples/pages/gourp-table.vue）：

<table-group
  v-if="data[0]?.DataArray?.length"
  id="tableGroup"
  ref="tableGroup"
  :data="data"
  @customEvents="customEvents"
  :cellRenderMethods="{ cellRenderMethods }"
  :handlerConfig="handlerConfig"
  isTool
  isFooter
  :footConfig="footConfig"
  groupField="name"
></table-group>

8. TableBigData 大数据增量表（table-big-data）

大数据增量加载表，使用 v-vxe-table-infinite-scroll 指令触底加载，支持表尾统计。

来源：packages/tables/table-big-data.vue

额外 Props：footConfig(Object) · isFooter(Boolean) · spanMethod(Function) · load(Function, 触底加载回调) · page(Object, 默认 null)

Events：customEvents · Slots：#expandContent · 暴露方法：usePublicAPI + setStyle

真实示例（取自 examples/pages/big-data.vue）：

<table-big-data
  id="tableBase"
  ref="tableBase"
  :data="data"
  @customEvents="customEvents"
  :cellRenderMethods="{ cellRenderMethods }"
  :handlerConfig="handlerConfig"
  isTool
  :footConfig="footConfig"
  :expandConfig="expandConfig"
  :rowStyle="rowStyle"
  :cellStyle="cellStyle"
  :load="load"
  :loading="loading"
  :page="page"
>
  <template #expandContent="slotProps">{{ slotProps }}</template>
</table-big-data>

9. TreeTable 虚拟树表（tree-table）

懒加载虚拟树表：自动把 {selected, enum, props} 单元格渲染为 radio 按钮组，支持 tag / icon / a 富文本单元格，树节点懒加载。

来源：packages/tables/tree-table.vue

额外 Props（在 publicProps 之上）：

Events：customEvents · Slots：#expandContent · 暴露方法：usePublicAPI + setTreeTempData() + 重写的 cellClickEvent + setStyle

真实示例 — 树模式（取自 examples/pages/jt-tree-page.vue）：

<tree-table
  id="tableBase"
  ref="tableBase"
  :data="data"
  @customEvents="customEvents"
  :cellRenderMethods="{ cellRenderMethods }"
  :handlerConfig="handlerConfig"
  mode="tree"
  isTool
  isAccordion
  :isLazy="true"
  checkbox
  :expandConfig="expandConfig"
  :rowStyle="rowStyle"
  :cellStyle="cellStyle"
  :isSeq="false"
  baseUrl="/api/treetest/"
  :lazyLoadParams="lazyLoadParams"
  :axios="axios"
  :checkboxMethod="checkboxMethod"
>
  <template #expandContent="slotProps">{{ slotProps }}</template>
</tree-table>

真实示例 — 单选模式（取自 examples/pages/tree-table-page.vue）：

<tree-table
  id="tableBase"
  ref="tableBase"
  :data="data"
  radio
  @customEvents="customEvents"
  :cellRenderMethods="{ cellRenderMethods }"
  :handlerConfig="handlerConfig"
  isTool
  :isAccordion="true"
  :isLazy="true"
  :expandConfig="expandConfig"
  baseUrl="/api/test/"
  :lazyLoadParams="lazyLoadParams"
  :axios="axios"
></tree-table>

共享表格属性 publicProps

TableBase / TableGroup / TableBigData / TreeTable 均继承自 packages/tables/publicProps.js：

customEvents 事件载荷类型：radio / checkbox / treeCheckbox / handler / cellClick / treeCellClick / treeTxtClick / keydown-enter

usePublicAPI 暴露方法

四个表格组件统一通过 packages/tables/hooks/usePublicAPI.js 暴露以下方法（模板 ref 调用）：

radioSelectChangeEvent · selectChangeEvent · getEditData · handlerColClick · cellClickEvent · keyEnter · exportTableData · exportData · importTableData · loadData · setCheckboxRow · clearCheckboxRow · toggleCheckboxRow · reloadTreeExpand · removeRow · treeTxtClick · jtTable · reloadParentNode · setRadioRow · reloadParentRow

渲染器清单（cellRender / editRender）

表格列通过 header[].cellRender / header[].editRender 指定渲染器名称，对应 packages/tables/hooks/cell-render/cell-render.js 与 edit-render/edit-render.js 中 VxeUI.renderer.add(...) 的注册名。

单元格渲染器（cellRender）

Select / Input / Number / Rate 共用 CellForm，通过列配置 props（枚举 enum、功能码 funcode、占位 placeholder、最大值 max 等）区分形态。

编辑渲染器（editRender，双击进入编辑态时生效）

工具函数

随默认导出（import jtui from 'jtxa-ui'）一并暴露的工具方法：

• downloadFile(url, name, axios) — 文件下载（基于 file-saver）。也可从 packages/utils/CusMethods.js 引入。

  import { downloadFile } from 'jtxa-ui'
  downloadFile('/api/file/123', 'report.xlsx', axios)
  

packages/utils/utils.js 内常用工具（按需从源码引入，未随包默认导出）：

• deepCopy · uuid · getStorage / setStorage · parseJson · getUrl · stringToBoolean · getJson · extname · getLoading · debounce · keepSignificantFigures · isInput · fomatFloat · isRepeatObj / isRepeatArr · getEffeNum · getMaxMin / convertMaxMin · getDate / formatDate

packages/utils/chartMethods.js：

• getInterval(min, max, total) → { interval, xAxisLabel }（图表轴间隔计算）

packages/utils/jtMessage.js：

• 全局事件总线 on / emit / off（基于 window.JTMessage 单例），用于跨组件通信（如 rootChange、step_submit）。

已知问题与注意事项

1. echarts 未在 peerDependencies 中：构建时被 external 化，请确保消费方已安装 echarts@^6。
2. manage-tree-table 需局部引入：它不参与 app.use(jtui) 的全局注册，使用前请按快速上手局部 import。

相关文档

更详细的按组件文档见 docs/：

• docs/README.md — 总览 / 快速上手
• docs/form.md — jt-form
• docs/upload.md — jt-upload
• docs/echart.md — jt-chart
• docs/search-type.md — search-type
• docs/manage-tree-table.md — manage-tree-table
• docs/tables.md — table-base / table-group / table-big-data / tree-table
• docs/quick-reference.md — 快速参考
• docs/debug-guide.md — 用 examples 调试开发
• docs/local-publish-guide.md — 本地发布与测试

以上文档中的包名已统一为 jtxa-ui（历史名 jtui-vite 已废弃）。

开发

pnpm install

pnpm dev          # 启动 examples 演示站（vite，端口 6222）

pnpm build        # 构建库（vite build -> dist/）

npm run build      # 同上（npm 方式）

npm link          # 本地软链，便于其他项目联调

npm run build -- --watch   # 监听构建

构建产物：dist/jtxa-ui.es.js（ESM）、dist/jtxa-ui.umd.js（UMD，全局变量 jtui）、dist/jtxa-ui.css（样式）。演示站入口为 examples/main.js（直接引用 packages/index 源码联调）。