jtxa-ui 1.0.8 → 1.0.9

package/README.md

@@ -1,15 +1,693 @@
 # jtxa-ui
 
+> 基于 Vue 3 + VxeTable + Element Plus + ECharts 的企业级组件库（v1.0.8，MIT License）。
+
+`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
+
+---
+
+## 目录
+
+- [安装](#安装)
+- [快速上手](#快速上手)
+- [组件总览](#组件总览)
+- [组件详细文档](#组件详细文档)
+  - [Form 动态表单](#1-form-动态表单-jt-form)
+  - [JtUpload 分片上传](#2-jtupload-分片上传-jt-upload)
+  - [Echart 图表](#3-echart-图表-jt-chart)
+  - [SearchType 高级查询](#4-searchtype-高级查询-search-type)
+  - [ManageTreeTable 管理树表](#5-managetreetable-管理树表-manage-tree-table)
+  - [TableBase 基础表格](#6-tablebase-基础表格-table-base)
+  - [TableGroup 分组树表](#7-tablegroup-分组树表-table-group)
+  - [TableBigData 大数据表](#8-tablebigdata-大数据增量表-table-big-data)
+  - [TreeTable 虚拟树表](#9-treetable-虚拟树表-tree-table)
+- [共享表格属性 publicProps](#共享表格属性-publicprops)
+- [工具函数](#工具函数)
+- [已知问题与注意事项](#已知问题与注意事项)
+- [相关文档](#相关文档)
+- [开发](#开发)
+
+---
+
+## 安装
+
+```sh
+# 使用你项目的包管理器安装本库
+npm install jtxa-ui
+# 或
+pnpm add jtxa-ui
+```
+
+`jtxa-ui` 将 `vue`、`element-plus`、`echarts` 在构建时 **external（外部化）**，因此消费方需自行提供这些运行时依赖（peer）：
+
+```sh
+# 必须安装的对等依赖
+npm install vue@^3.5 element-plus@^2.13 echarts@^6.0
+```
+
+> 说明：`echarts` 当前列在 `dependencies` 中（安装本库时会自动带入），但构建时被 external 化，请确保项目内 `echarts` 版本为 `^6` 且与库兼容；使用图表组件前需保证 `echarts` 可被模块解析到。
+
+---
+
+## 快速上手
+
+### 全局注册（推荐）
+
+```js
+// 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(...)`：
+
+```js
+import { Form, TableBase, TreeTable } from 'jtxa-ui'
+app.use(Form)
+app.use(TableBase)
+app.use(TreeTable)
+```
+
+> ⚠️ **`manage-tree-table` 默认不通过 `app.use(jtui)` 全局注册**，使用它时需要局部引入：
+>
+> ```vue
+> <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`）。
+
+---
+
+## 组件总览
+
+| 组件（导出名） | 模板标签 | 底层依赖 | 用途 |
+| --- | --- | --- | --- |
+| `Form` | `<jt-form>` | Element Plus + wangEditor | 基于 `formConfig` 动态生成表单，支持多种控件、inline/descriptions 布局、级联懒加载、辅助输入抽屉 |
+| `JtUpload` | `<jt-upload>` | simple-uploader.js | 分片 / 断点续传文件上传，成功后回调合并接口 |
+| `Echart` | `<jt-chart>` | ECharts | 图表封装，自动刻度、双 Y 轴、X 轴时间间隔、样式持久化 |
+| `SearchType` | `<search-type>` | Element Plus + jt-form | 动态查询条件构造器，支持分组（并且/或者）、级联、复选、树选择 |
+| `ManageTreeTable` | `<manage-tree-table>` | Element Plus + 各面板 | 管理树表页面组件，按 `mode`/`pageMode` 派发不同版式（看板/树表等） |
+| `TableBase` | `<table-base>` | VxeTable | 基础表格：工具栏、表尾统计、虚拟滚动、单选/多选、分组表头、展开行、操作列 |
+| `TableGroup` | `<table-group>` | VxeTable | 分组树表，按 `groupField` 把行归并到父行 |
+| `TableBigData` | `<table-big-data>` | VxeTable | 大数据增量加载表，触底加载 + 表尾统计 |
+| `TreeTable` | `<tree-table>` | VxeTable | 懒加载虚拟树表，单元格自动渲染 radio/复选/富文本，树节点懒加载 |
+
+> 其余 `packages/` 下 60+ 个 `.vue` 为内部子组件 / 渲染器 / 看板 / 构建部署件，**不对外暴露**，请勿直接引用。
+
+---
+
+## 组件详细文档
+
+### 1. Form 动态表单（`jt-form`）
+
+基于 `formConfig` 数组动态渲染表单，自动处理校验、级联懒加载与辅助输入。
+
+**来源**：`packages/form/index.vue`
+
+**Props**
+
+| 属性 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `id` | String / Number | — | **必填**，表单唯一标识 |
+| `model` | Object | — | **必填**，表单数据对象 |
+| `formConfig` | Array | — | **必填**，字段配置数组（见下） |
+| `labelWidth` | String | `'80px'` | 标签宽度 |
+| `inline` | Boolean | `false` | 是否行内布局 |
+| `size` | String | `'default'` | 尺寸 |
+| `labelPosition` | String | `'right'` | 标签位置 |
+| `rules` | Object | `{}` | 校验规则 |
+| `col` | Number | `1` | 每行字段列数 |
+| `border` | Boolean | `false` | 是否显示边框（descriptions 布局） |
+| `collapseTags` | Boolean | `false` | 多选标签折叠 |
+| `axios` | Function | — | 级联懒加载等远程请求方法 |
+| `title` | String | `''` | 表单标题 |
+| `lazyLoadParams` | Object | `null` | 级联懒加载参数 |
+| `autoInputConfig` | Object | `null` | 辅助输入抽屉配置 |
+
+**`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`
+
+**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`）：
+
+```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**
+
+| 属性 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `target` | String | — | **必填**，分片 / 校验地址 |
+| `mergePath` | String | — | **必填**，合并接口地址 |
+| `simultaneousUploads` | Number | `3` | 并发上传数 |
+| `text` | String | `'点击上传'` | 按钮文案 |
+| `accept` | String | `'*/*'` | 接受的文件类型 |
+| `singleFile` | Boolean | `false` | 是否单文件 |
+| `allowDuplicateUploads` | Boolean | `true` | 是否允许重复文件 |
+| `autoStart` | Boolean | `true` | 选择后自动开始 |
+| `singleMode` | Boolean | `false` | 单文件模式 |
+| `axios` | Function | — | 自定义请求方法 |
+
+**Events**：`success`(response) · `error`(rootFile, file, message, chunk) · `added`(file) · `addeds`(files, fileList) · `removed`(file)
+
+**暴露方法**：`getFiles()`（返回 `fileList`）· `goOnUpload()`（续传）· `clearList()`
+
+**真实示例**（取自 `examples/pages/form-page.vue`）：
+
+```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`）：
+
+```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**
+
+| 属性 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `id` | String | — | **必填**，图表容器 id（同页多图需唯一） |
+| `timeRange` | Array | — | 时间范围，用于计算 X 轴间隔 |
+| `data` | Array | — | **必填**，series 数组，每项含 `type/name/data`，支持 `yAxisIndex` 双 Y 轴 |
+| `yMaxAndMinkeepDecimal` | Number | `0` | Y 轴最大/最小值保留小数位 |
+| `maxAndMinLevel` | Number | `0.05` | 最大/最小容差比例 |
+| `customIntrerVal` | Number | — | 自定义 X 轴间隔 |
+| `yLeft` | String | `''` | 左 Y 轴名称 |
+| `yRight` | String | `''` | 右 Y 轴名称 |
+| `isSetting` | Boolean | `true` | 是否显示样式设置弹窗 |
+
+**Events**：无显式声明。
+
+**暴露方法**：`getVM()`（返回图表实例）
+
+**真实示例**（取自 `examples/pages/jt-echart.vue`，多图表 v-for）：
+
+```vue
+<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**
+
+| 属性 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `options_type` | Array | — | 查询类型配置 |
+| `listuri` | String | — | 选项列表接口 |
+| `selected` | String | — | 当前选中的查询路径 |
+| `axios` | Function | — | 请求方法 |
+
+**Events**：`count` · `initedData`
+
+**暴露方法**：`getData()`（返回查询条件数组）
+
+**真实示例**（取自 `examples/pages/search.vue`）：
+
+```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**
+
+| 属性 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `compPath` | String | — | 组件路径前缀 |
+| `axios` | Function | — | 请求方法 |
+| `subTable` | Boolean | `false` | 是否子表 |
+| `rootQueryParams` | Object | `{}` | 根查询参数 |
+| `needRoot` | Boolean | `true` | 是否需要根数据 |
+| `config` | Object / String | `{}` | 查询配置（对象或 url） |
+| `buttonWidth` | Number / String | — | 操作按钮区宽度 |
+| `mode` | Number / String | — | 版式模式（如 0/1/12 等） |
+| `btnNumLeft` | Number / String | `1` | 左侧按钮数量 |
+| `btnNumRight` | Number / String | `1` | 右侧按钮数量 |
+| `accordion` | Boolean | `true` | 手风琴展开 |
+| `headerHeight` | Number / String | `80` | 头部高度 |
+| `isLastLoad` | Boolean | `true` | 是否末次加载 |
+| `slotConfig` | Array | `[]` | 自定义插槽组件配置（传入业务子组件） |
+
+**Events**：`getBaseParams`
+
+**Slots**：透传父级所有插槽；向面板透传 `#cusComp`。
+
+**暴露方法**：`search()` · `initPage()`
+
+**真实示例**（取自 `examples/pages/manage-tree-table-page.vue`，局部引入写法）：
+
+```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`）：
+
+```vue
+<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](#共享表格属性-publicprops)。
+
+**额外 Props**：`footConfig`(Object, `{filed:[]}`) · `isFooter`(Boolean) · `spanMethod`(Function) · `isSortable`(Boolean) · `openVirtual`(Boolean)
+
+**Events**：`customEvents`（载荷类型见 [publicProps](#共享表格属性-publicprops)）
+
+**Slots**：`#expandContent`（scoped 插槽，展开行内容）
+
+**暴露方法**：见 [usePublicAPI 方法集](#usePublicAPI-暴露方法)（含 `exportData` / `loadData` / `reloadTreeExpand` / `removeRow` / `setCheckboxRow` / `jtTable()` 等）+ `setStyle` / `sortMethod`
+
+**真实示例**（取自 `examples/pages/table-ptbg.vue`）：
+
+```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](#共享表格属性-publicprops) 基础上增加 `groupField`，使用 `XEUtils.groupBy` 把行归并到父行下形成分组树表。
+
+**来源**：`packages/tables/table-group.vue`
+
+**额外 Props**：`groupField`(String, **必填**) — 用于分组的字段名。
+
+**Events**：`customEvents` · **Slots**：`#expandContent` · **暴露方法**：usePublicAPI + `setStyle`
+
+**真实示例**（取自 `examples/pages/gourp-table.vue`）：
+
+```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`）：
+
+```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 之上）：
+
+| 属性 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `isLine` | Boolean | `false` | 连接线 |
+| `isAccordion` | Boolean | `false` | 手风琴 |
+| `isLazy` | Boolean | `true` | 懒加载子节点 |
+| `isExpandAllNode` | Boolean | `false` | 默认展开全部 |
+| `mode` | String | `'treeTable'` | 模式（`tree` 等） |
+| `baseUrl` | String | — | **必填**，树节点加载 base url |
+| `axios` | Function | — | 请求方法 |
+| `lazyLoadParams` | Object | `null` | 懒加载参数 |
+
+**Events**：`customEvents` · **Slots**：`#expandContent` · **暴露方法**：usePublicAPI + `setTreeTempData()` + 重写的 `cellClickEvent` + `setStyle`
+
+**真实示例 — 树模式**（取自 `examples/pages/jt-tree-page.vue`）：
+
+```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`）：
+
+```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`：
+
+| 属性 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `id` | String | — | **必填**，表格唯一标识 |
+| `styleStatus` | String | `'1'` | 样式状态 |
+| `size` | String | `'mini'` | 尺寸 |
+| `border` | String | `'full'` | 边框 |
+| `stripe` | Boolean | `true` | 斑马纹 |
+| `loading` | Boolean | `false` | 加载态 |
+| `data` | Object | — | **必填**，表格数据 |
+| `maxHeight` | String / Number | `0` | 最大高度 |
+| `radio` | Boolean | `false` | 开启单选 |
+| `checkbox` | Boolean | `false` | 开启多选 |
+| `cellRenderMethods` | Object | — | 单元格渲染方法 |
+| `handlerConfig` | Object | — | 操作列配置 |
+| `isTool` | Boolean | `false` | 显示工具栏 |
+| `expandConfig` | Object | — | 展开行配置（含 `loadMethod` 懒加载） |
+| `rowStyle` | Function | — | 行样式 |
+| `cellStyle` | Function | — | 单元格样式 |
+| `isSeq` | Boolean | `true` | 显示序号列 |
+| `isWrap` | Boolean | `false` | 自动换行 |
+| `isTextWrap` | Boolean | `false` | 文本换行 |
+| `showBtn` | Function | — | 操作按钮显隐判断 |
+| `checkboxMethod` | Function | — | 多选可选判断 |
+| `axios` | Function | — | 请求方法 |
+| `tableStyle` | Object | — | 表头/斑马/当前行样式 |
+| `autoSize` | Boolean | `false` | 自动列宽 |
+
+**`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`
+
+---
+
+## 工具函数
+
+随默认导出（`import jtui from 'jtxa-ui'`）一并暴露的工具方法：
+
+- **`downloadFile(url, name, axios)`** — 文件下载（基于 file-saver）。也可从 `packages/utils/CusMethods.js` 引入。
+  ```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. **`package.json` 入口字段**：早期 `main` / `module` 指向不存在的 `jtxa-ui-lib.*`，现已修正为 `dist/jtxa-ui.umd.js` / `dist/jtxa-ui.es.js`，与 `exports` 及实际构建产物一致。
+2. **`echarts` 未在 `peerDependencies` 中**：构建时被 external 化，请确保消费方已安装 `echarts@^6`。
+3. **`manage-tree-table` 需局部引入**：它不参与 `app.use(jtui)` 的全局注册，使用前请按[快速上手](#按需引入)局部 `import`。
+4. **`App.vue` 导航含死项**：`examples/App.vue` 中 `menu` 有一项 `more-charts` 在 `cpms` 中不存在（点击会报错），仅影响演示站，不影响库本身。
+5. **示例文件名歧义**：`examples/pages/tree-table-redio.vue` 文件名像 `tree-table`，实际演示的是 `manage-tree-table`（`mode=1`）；`examples/pages/jt-table-ptbg.vue` 标签仍是 `<table-base>`（非 `jt-table-base`）。
+
+---
+
+## 相关文档
+
+更详细的按组件文档见 [`docs/`](./docs)：
+
+- [docs/README.md](./docs/README.md) — 总览 / 快速上手
+- [docs/form.md](./docs/form.md) — `jt-form`
+- [docs/upload.md](./docs/upload.md) — `jt-upload`
+- [docs/echart.md](./docs/echart.md) — `jt-chart`
+- [docs/search-type.md](./docs/search-type.md) — `search-type`
+- [docs/manage-tree-table.md](./docs/manage-tree-table.md) — `manage-tree-table`
+- [docs/tables.md](./docs/tables.md) — `table-base` / `table-group` / `table-big-data` / `tree-table`
+- [docs/quick-reference.md](./docs/quick-reference.md) — 快速参考
+- [docs/debug-guide.md](./docs/debug-guide.md) — 用 examples 调试开发
+- [docs/local-publish-guide.md](./docs/local-publish-guide.md) — 本地发布与测试
+
+> 以上文档中的包名已统一为 `jtxa-ui`（历史名 `jtui-vite` 已废弃）。
+
+---
+
+## 开发
+
 ```sh
 pnpm install
 
-pnpm dev
+pnpm dev          # 启动 examples 演示站（vite，端口 6222）
 
-pnpm build
+pnpm build        # 构建库（vite build -> dist/）
 
-npm run build
+npm run build      # 同上（npm 方式）
 
-npm link
+npm link          # 本地软链，便于其他项目联调
 
-npm run build -- --watch
+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` 源码联调）。