@jnrs/vue-core 1.2.16 → 1.2.18

package/AGENTIC.md

@@ -0,0 +1,924 @@
+# @jnrs/vue-core API 文档
+
+## ✨ 介绍
+
+巨能前端工程化开发，Vue 专用核心功能包。提供 Pinia store、Vue composables、Vue Router、全局指令、插件和公共 Vue 组件。
+
+## 📦 模块总览
+
+| 模块路径                     | 说明                     |
+| ---------------------------- | ------------------------ |
+| `@jnrs/vue-core`             | 主模块，包含基础类型定义 |
+| `@jnrs/vue-core/pinia`       | Pinia 状态管理模块       |
+| `@jnrs/vue-core/router`      | Vue Router 路由模块      |
+| `@jnrs/vue-core/components`  | Vue 组件库               |
+| `@jnrs/vue-core/composables` | Vue 组合式 API           |
+| `@jnrs/vue-core/constants`   | 常量定义                 |
+| `@jnrs/vue-core/lib`         | 工具库                   |
+| `@jnrs/vue-core/locales`     | 国际化配置               |
+| `@jnrs/vue-core/utils`       | 工具函数                 |
+
+---
+
+## 📋 API 详情
+
+### @jnrs/vue-core 主模块
+
+#### 类型 (Types)
+
+##### IMenuItem
+
+菜单项接口定义
+
+| 属性名    | 类型          | 必填 | 说明       |
+| --------- | ------------- | ---- | ---------- |
+| meta      | `RouteMeta`   | ✓    | 路由元信息 |
+| path      | `string`      | ✓    | 路径       |
+| name      | `string`      | -    | 名称       |
+| component | `string`      | -    | 组件路径   |
+| redirect  | `string`      | -    | 重定向路径 |
+| children  | `IMenuItem[]` | -    | 子菜单项   |
+
+##### ElSize
+
+Element Plus 尺寸类型
+
+```typescript
+type ElSize = '' | 'large' | 'default' | 'small'
+```
+
+##### ElButtonType
+
+Element Plus 按钮类型
+
+```typescript
+type ElButtonType = 'default' | 'primary' | 'success' | 'info' | 'warning' | 'text' | 'danger'
+```
+
+##### IAttachment
+
+文件信息类型
+
+| 属性名         | 类型     | 必填 | 说明                               |
+| -------------- | -------- | ---- | ---------------------------------- |
+| id             | `number` | ✓    | 数据 id                            |
+| documentId     | `number` | ✓    | 文件 id                            |
+| fileName       | `string` | ✓    | 文件名                             |
+| uniqueFileName | `string` | ✓    | 文件名唯一标识（用于文件获取 API） |
+| fileType       | `string` | ✓    | MIME 类型                          |
+| fileSize       | `number` | ✓    | 文件大小（单位：字节）             |
+
+##### IPagination
+
+分页类型
+
+| 属性名   | 类型     | 必填 | 说明     |
+| -------- | -------- | ---- | -------- |
+| pageNo   | `number` | ✓    | 当前页码 |
+| pageSize | `number` | ✓    | 每页大小 |
+
+##### IPageData<T>
+
+分页列表数据（泛型 T）
+
+继承自 `IPagination`
+
+| 属性名 | 类型     | 必填 | 说明     |
+| ------ | -------- | ---- | -------- |
+| list   | `T[]`    | ✓    | 数据列表 |
+| count  | `number` | ✓    | 数据总数 |
+
+**使用示例：**
+
+```typescript
+import type { IPageData, IAttachment } from '@jnrs/vue-core'
+
+interface UserData {
+  id: number
+  name: string
+}
+
+const userData: IPageData<UserData> = {
+  pageNo: 1,
+  pageSize: 20,
+  list: [{ id: 1, name: '张三' }],
+  count: 100
+}
+```
+
+---
+
+### @jnrs/vue-core/pinia 模块
+
+#### Store: useSystemStore
+
+系统仓库，管理主题、菜单折叠、全屏等系统级状态。
+
+**返回值：**
+
+| 属性/方法          | 类型                             | 说明                                       |
+| ------------------ | -------------------------------- | ------------------------------------------ |
+| theme              | `Ref<Theme>`                     | 主题配置（国际化、主题模式、自定义强调色） |
+| computedThemeMode  | `ComputedRef<'light' \| 'dark'>` | 计算后的主题模式（考虑 auto 模式）         |
+| menuCollapse       | `Ref<boolean>`                   | 菜单是否折叠                               |
+| documentFullscreen | `Ref<boolean>`                   | 文档是否全屏                               |
+| toggleCollapse     | `() => void`                     | 折叠菜单切换                               |
+| toggleFullScreen   | `() => Promise<void>`            | 全屏切换                                   |
+| setLocale          | `(value: unknown) => void`       | 设置语言                                   |
+| setMode            | `(value: unknown) => void`       | 设置主题模式                               |
+| setPrimaryColor    | `(value: unknown) => void`       | 设置主题色                                 |
+
+**Theme 类型：**
+
+```typescript
+type Theme = {
+  locale: ILocale // 语言：'zhCn' | 'en'
+  mode: IThemeMode // 主题模式：'light' | 'dark' | 'auto'
+  primaryColor: string // 自定义强调色
+}
+```
+
+**使用示例：**
+
+```typescript
+import { useSystemStore } from '@jnrs/vue-core/pinia'
+
+const systemStore = useSystemStore()
+
+// 切换菜单折叠
+systemStore.toggleCollapse()
+
+// 切换全屏
+await systemStore.toggleFullScreen()
+
+// 设置主题
+systemStore.setMode('dark')
+systemStore.setLocale('en')
+systemStore.setPrimaryColor('#409EFF')
+
+// 访问当前主题
+console.log(systemStore.theme.value.locale)
+console.log(systemStore.computedThemeMode.value)
+```
+
+**特性：**
+
+- 自动持久化 `theme` 和 `menuCollapse` 状态
+- 支持自动主题模式（根据系统偏好切换）
+- 动态设置 CSS 变量 `--jnrs-color-primary`
+
+---
+
+#### Store: useMenuStore
+
+菜单仓库，管理动态菜单和路由。
+
+**返回值：**
+
+| 属性/方法            | 类型                                         | 说明                   |
+| -------------------- | -------------------------------------------- | ---------------------- |
+| hasFetchedAsyncMenus | `Ref<boolean>`                               | 菜单是否已获取         |
+| menus                | `Ref<IMenuItem[]>`                           | 菜单项列表             |
+| asyncSetMenus        | `(res: IMenuItem[]) => Promise<IMenuItem[]>` | 设置菜单信息并生成路由 |
+| clearMenu            | `() => void`                                 | 清除菜单信息           |
+
+**使用示例：**
+
+```typescript
+import { useMenuStore } from '@jnrs/vue-core/pinia'
+
+const menuStore = useMenuStore()
+
+// 设置菜单（会自动生成路由）
+const menus = await menuStore.asyncSetMenus([
+  {
+    path: '/dashboard',
+    name: 'Dashboard',
+    component: '/dashboard/index',
+    meta: { title: '仪表盘' }
+  }
+])
+
+// 清除菜单（如退出登录时）
+menuStore.clearMenu()
+
+// 访问菜单列表
+console.log(menuStore.menus.value)
+```
+
+**特性：**
+
+- 自动为菜单项生成 UUID
+- 自动调用 `asyncGenerateRoute` 生成动态路由
+- `hasFetchedAsyncMenus` 不持久化，每次刷新页面需重新获取菜单
+
+---
+
+### @jnrs/vue-core/router 模块
+
+#### 类型导出
+
+从 `vue-router` 重新导出的类型：
+
+- `RouteMeta` - 路由元信息类型
+- `RouteLocationNormalizedGeneric` - 标准化路由位置类型
+- `RouteLocationNormalizedLoadedGeneric` - 已加载的标准化路由位置类型
+
+##### FileModules
+
+文件模块类型（Vite import.meta.glob 返回的类型）
+
+```typescript
+type FileModules = Record<string, () => Promise<unknown>>
+```
+
+#### 函数导出
+
+从 `vue-router` 重新导出的函数：
+
+- `useRouter` - 原生 vue-router 函数
+- `useRoute` - 原生 vue-router 函数
+
+##### createVueRouter
+
+创建 vue-router 实例
+
+**参数：**
+
+| 参数名           | 类型                                               | 必填 | 说明                                          |
+| ---------------- | -------------------------------------------------- | ---- | --------------------------------------------- |
+| options          | `RouterOptions`                                    | ✓    | 路由配置项                                    |
+| fileModules      | `FileModules`                                      | ✓    | 文件模块（通过 import.meta.glob 导入）        |
+| layoutName       | `string`                                           | -    | 布局组件名称                                  |
+| globalComponent  | `Promise<unknown>`                                 | -    | 全局 Layout 组件（meta.global=true 时需传入） |
+| handleBeforeEach | `(to, from) => Promise<void \| boolean \| string>` | -    | 路由前置守卫处理函数                          |
+
+**返回值：** `Router` - router 实例
+
+**使用示例：**
+
+```typescript
+import { createVueRouter } from '@jnrs/vue-core/router'
+
+const fileModules = import.meta.glob('/src/views/**/*.vue')
+
+const router = createVueRouter({
+  options: {
+    history: createWebHistory(),
+    routes: [{ path: '/', redirect: '/dashboard' }]
+  },
+  fileModules,
+  layoutName: 'Layout',
+  globalComponent: import('@/layouts/GlobalLayout.vue'),
+  handleBeforeEach: async (to, from) => {
+    // 路由守卫逻辑
+    const token = localStorage.getItem('token')
+    if (!token && to.meta.requiresAuth) {
+      return '/login'
+    }
+  }
+})
+```
+
+##### asyncGenerateRoute
+
+设置动态路由，生成路由记录
+
+**参数：**
+
+| 参数名 | 类型          | 必填 | 说明                       |
+| ------ | ------------- | ---- | -------------------------- |
+| menus  | `IMenuItem[]` | ✓    | 菜单项数组                 |
+| parent | `IMenuItem`   | -    | 父级菜单项（内部递归使用） |
+
+**返回值：** `Promise<void>`
+
+**说明：**
+
+- 根据菜单项自动生成路由记录
+- 支持目录结构（无 component 字段）
+- 支持重定向（redirect 字段）
+- 支持全局路由（meta.global = true）
+- 自动添加 fullPathTitle 到 meta
+
+##### handleRouter
+
+路由跳转或替换
+
+**参数：**
+
+| 参数名 | 类型                  | 必填 | 说明                  |
+| ------ | --------------------- | ---- | --------------------- |
+| to     | `RouteLocationRaw`    | ✓    | 路由跳转参数          |
+| type   | `'push' \| 'replace'` | -    | 跳转方式，默认 'push' |
+
+**返回值：** `Promise<boolean \| void>`
+
+**使用示例：**
+
+```typescript
+import { handleRouter } from '@jnrs/vue-core/router'
+
+// push 跳转
+await handleRouter({ name: 'dashboard' })
+
+// replace 跳转
+await handleRouter({ path: '/user/profile' }, 'replace')
+```
+
+**特性：**
+
+- 自动捕获路由跳转错误
+- 失败时跳转到 404 页面
+- 输出警告日志
+
+##### getRoutes
+
+获取已注册路由
+
+**返回值：** `IMenuItem[]` - 已注册的路由列表
+
+**使用示例：**
+
+```typescript
+import { getRoutes } from '@jnrs/vue-core/router'
+
+const routes = getRoutes()
+console.log(routes)
+```
+
+---
+
+### @jnrs/vue-core/components 模块
+
+#### JnTable
+
+表格组件，基于 Element Plus Table 封装，支持序号列、选择列、鼠标框选等功能。
+
+**Props：**
+
+| 属性名              | 类型                             | 默认值                       | 说明                                                                                        |
+| ------------------- | -------------------------------- | ---------------------------- | ------------------------------------------------------------------------------------------- |
+| data                | `Record<string, any>[]`          | —                            | 表数据                                                                                      |
+| rowKey              | `string`                         | `'id'`                       | 行数据的 Key，在使用 reserve-selection 功能与显示树形数据时必填。支持多层访问：user.info.id |
+| showScrollbar       | `boolean`                        | `false`                      | 总是显示横向滚动条                                                                          |
+| height              | `string \| number`               | `'100%'`                     | 表格高度                                                                                    |
+| autoHeight          | `boolean`                        | `false`                      | 表格高度是否自动计算                                                                        |
+| autoHeightOptions   | `UseReactivityTableHeighOptions` | `{}`                         | 表格高度自动计算配置项                                                                      |
+| showIndexColumn     | `boolean`                        | `false`                      | 是否显示序号列                                                                              |
+| showSelectionColumn | `boolean`                        | `false`                      | 是否显示选择列                                                                              |
+| showMouseSelection  | `boolean`                        | `false`                      | 是否开启鼠标框选                                                                            |
+| pagination          | `IPagination`                    | `{ pageNo: 0, pageSize: 0 }` | 当前页码和每页大小（用于序号计算）                                                          |
+
+**使用示例：**
+
+```vue
+<template>
+  <JnTable
+    :data="tableData"
+    :pagination="{ pageNo: 1, pageSize: 20 }"
+    show-index-column
+    show-selection-column
+    show-mouse-selection
+  >
+    <el-table-column prop="name" label="姓名" />
+    <el-table-column prop="age" label="年龄" />
+  </JnTable>
+</template>
+```
+
+---
+
+#### JnSelectTemplate
+
+选择组件通用模板，支持下拉选择、弹窗多选等功能。
+
+**Props：**
+
+| 属性名                | 类型                                                                       | 默认值                       | 说明                                       |
+| --------------------- | -------------------------------------------------------------------------- | ---------------------------- | ------------------------------------------ |
+| listApi               | `Function`                                                                 | —                            | 列表接口（必填）                           |
+| tableName             | `string`                                                                   | `''`                         | 列表名称                                   |
+| tableWidth            | `string`                                                                   | `'60%'`                      | 列表宽度                                   |
+| listParams            | `Record<string, unknown>`                                                  | `{}`                         | 列表查询参数                               |
+| listParamsHandle      | `(params) => params`                                                       | `(params) => params`         | 列表查询参数前置处理函数                   |
+| listParamsHandleAfter | `(params) => params`                                                       | `(params) => params`         | 列表查询参数后置处理函数                   |
+| keyValue              | `{ name: string; id: string; [key: string]: string }`                      | `{ name: 'name', id: 'id' }` | 真实数据匹配的键值对名                     |
+| optionSecondaryField  | `string`                                                                   | —                            | keyValue 的拓展字段，用于 el-option 中显示 |
+| modelValue            | `Record<string, unknown> \| Record<string, unknown>[] \| number \| string` | —                            | 双向绑定值（支持多种类型）                 |
+| width                 | `string`                                                                   | `'100%'`                     | 宽度                                       |
+| simpleValue           | `boolean`                                                                  | `true`                       | 简单数据类型，仅返回 keyValue.id           |
+| showAllTips           | `boolean`                                                                  | `false`                      | option 组件是否显示 [全部]                 |
+| onlyOption            | `boolean`                                                                  | `false`                      | 仅显示选择器                               |
+| onlyButton            | `boolean`                                                                  | `false`                      | 仅显示选择按钮                             |
+| filterable            | `boolean`                                                                  | `true`                       | 是否可筛选                                 |
+| clearable             | `boolean`                                                                  | `true`                       | 是否可清空                                 |
+| buttonDialogText      | `string`                                                                   | `'更多'`                     | 按钮文字                                   |
+| size                  | `ElSize`                                                                   | `'default'`                  | 按钮大小                                   |
+| plain                 | `boolean`                                                                  | `true`                       | 按钮 plain                                 |
+| formRef               | `FormInstance`                                                             | `null`                       | 父级组件的表单对象                         |
+| validateFieldName     | `string`                                                                   | `''`                         | 父级表单验证的字段名                       |
+| limit                 | `number`                                                                   | `1`                          | 可选择的数量                               |
+| queryForm             | `Record<string, unknown>`                                                  | —                            | 表单查询参数                               |
+| initialParams         | `Record<string, unknown>`                                                  | —                            | 初始查询参数                               |
+| remoteFilterKey       | `string`                                                                   | `'name'`                     | 下拉框查询参数远程过滤参数的 key 值        |
+
+**使用示例：**
+
+```vue
+<template>
+  <JnSelectTemplate
+    v-model="selectedUser"
+    :list-api="getUserList"
+    table-name="用户选择"
+    :key-value="{ name: 'userName', id: 'userId' }"
+    :limit="1"
+  />
+</template>
+
+<script setup>
+import { ref } from 'vue'
+import { getUserList } from '@/api/user'
+
+const selectedUser = ref(null)
+</script>
+```
+
+---
+
+#### JnPdfView
+
+PDF 文件预览组件
+
+**Props：**
+
+| 属性名       | 类型          | 默认值  | 说明                                              |
+| ------------ | ------------- | ------- | ------------------------------------------------- |
+| fileList     | `IFileItem[]` | `[]`    | 文件列表                                          |
+| showFileName | `boolean`     | `true`  | 是否显示文件名                                    |
+| isPdf        | `boolean`     | `false` | 是否是 pdf 文件（pdf 文件直接预览，其他文件下载） |
+| windowWidth  | `number`      | `800`   | 预览窗口宽度                                      |
+| windowHeight | `number`      | `600`   | 预览窗口高度                                      |
+
+**使用示例：**
+
+```vue
+<template>
+  <JnPdfView :file-list="[{ src: '/path/to/file.pdf', fileName: '文档.pdf' }]" :is-pdf="true" />
+</template>
+```
+
+---
+
+#### JnPagination
+
+分页组件
+
+**Props：**
+
+| 属性名     | 类型            | 默认值                        | 说明         |
+| ---------- | --------------- | ----------------------------- | ------------ |
+| modelValue | `IPagination`   | `{ pageNo: 1, pageSize: 20 }` | 分页模型值   |
+| total      | `number`        | `0`                           | 总条数       |
+| size       | `ComponentSize` | `'small'`                     | 按钮尺寸     |
+| background | `boolean`       | `true`                        | 是否带背景色 |
+| marginTop  | `string`        | `'10px'`                      | 上边距       |
+
+**Events：**
+
+- `update:modelValue` - 分页变化时触发
+
+**使用示例：**
+
+```vue
+<template>
+  <JnPagination v-model="pagination" :total="100" @update:modelValue="handlePageChange" />
+</template>
+
+<script setup>
+import { ref } from 'vue'
+
+const pagination = ref({ pageNo: 1, pageSize: 20 })
+
+const handlePageChange = (newPagination) => {
+  console.log('页码变化', newPagination)
+}
+</script>
+```
+
+---
+
+#### JnImportAndExport
+
+导入 & 导出组件，依赖 JnFileUpload 文件上传组件
+
+**Props：**
+
+| 属性名                      | 类型                                               | 默认值                               | 说明                              |
+| --------------------------- | -------------------------------------------------- | ------------------------------------ | --------------------------------- |
+| importTemplateApi           | `() => Promise<Blob>`                              | —                                    | 下载导入模板文件的 api 函数       |
+| importApi                   | `(data: FormData) => Promise<IFullResponse>`       | —                                    | 数据导入 api 函数                 |
+| importFieldName             | `string`                                           | `'file'`                             | 数据导入的字段名                  |
+| importParams                | `Record<string, unknown>`                          | —                                    | 导入的参数                        |
+| fileUploadConfig            | `{ accept: string; limit: number }`                | `{ accept: '.xls,.xlsx', limit: 1 }` | 导入的文件上传配置                |
+| importBtnName               | `string`                                           | `'导入'`                             | 导入的按钮名称                    |
+| importDisabled              | `boolean`                                          | `false`                              | 是否禁用导入按钮                  |
+| exportApi                   | `(data: Record<string, unknown>) => Promise<Blob>` | —                                    | 数据导出的 api 函数               |
+| exportParams                | `Record<string, unknown>`                          | —                                    | 导出的参数                        |
+| exportDynamicParamsConfig   | `{ label: string; prop: string }`                  | —                                    | 导出操作时，MessageBox 的参数配置 |
+| messageBoxInputPattern      | `RegExp`                                           | `/^\S+(?:\s+\S+)*$/`                 | MessageBox 中输入框的校验表达式   |
+| messageBoxInputErrorMessage | `string`                                           | `'请输入参数'`                       | 校验未通过时的提示文本            |
+| exportBtnName               | `string`                                           | `'导出'`                             | 导出的按钮名称                    |
+| exportDisabled              | `boolean`                                          | `false`                              | 是否禁用导出按钮                  |
+| size                        | `ElSize`                                           | `'default'`                          | 按钮尺寸                          |
+| buttonType                  | `ElButtonType`                                     | `'primary'`                          | 按钮类型                          |
+| plain                       | `boolean`                                          | `true`                               | 是否为朴素按钮                    |
+| text                        | `boolean`                                          | `false`                              | 是否为文字按钮                    |
+| icon                        | `boolean`                                          | `true`                               | 是否显示图标                      |
+
+**使用示例：**
+
+```vue
+<template>
+  <JnImportAndExport
+    :import-template-api="downloadTemplate"
+    :import-api="importData"
+    :export-api="exportData"
+    :export-params="{ type: 'excel' }"
+  />
+</template>
+
+<script setup>
+import { downloadTemplate, importData, exportData } from '@/api/data'
+</script>
+```
+
+---
+
+#### JnImageView
+
+图片预览组件
+
+**Props：**
+
+| 属性名         | 类型          | 默认值    | 说明             |
+| -------------- | ------------- | --------- | ---------------- |
+| src            | `string`      | `''`      | 图片源地址       |
+| previewSrcList | `IFileItem[]` | `[]`      | 开启图片预览功能 |
+| preview        | `boolean`     | `false`   | 是否开启预览功能 |
+| height         | `string`      | —         | 图片高度         |
+| maxHeight      | `string`      | `'200px'` | 图片最大高度     |
+
+**使用示例：**
+
+```vue
+<template>
+  <JnImageView src="/path/to/image.jpg" :preview="true" :preview-src-list="imageList" />
+</template>
+```
+
+---
+
+#### JnFileUpload
+
+通用上传 & 回显组件
+
+**Props：**
+
+| 属性名            | 类型                                    | 默认值    | 说明                            |
+| ----------------- | --------------------------------------- | --------- | ------------------------------- |
+| modelValue        | `MixedUploadFile[]`                     | —         | 绑定的模型值（文件列表）        |
+| uploadName        | `string`                                | `'file'`  | 上传的文件字段名                |
+| drag              | `boolean`                               | `false`   | 是否启用拖拽上传                |
+| disabled          | `boolean`                               | `false`   | 是否禁用                        |
+| showFileList      | `boolean`                               | `true`    | 是否显示已上传文件列表          |
+| accept            | `string`                                | `''`      | 接受的文件类型（如 .xls,.xlsx） |
+| fileSizeMb        | `number`                                | `100`     | 单个文件大小限制（单位：MB）    |
+| limit             | `number`                                | `0`       | 最大上传文件数量，0 表示不限制  |
+| size              | `'' \| 'small' \| 'default' \| 'large'` | `'small'` | Element Plus 组件的尺寸         |
+| formRef           | `FormInstance`                          | —         | 父级组件的表单引用              |
+| validateFieldName | `string`                                | `''`      | 父级表单中用于校验的字段名      |
+| downloadFileFn    | `(data: IAttachment) => void`           | —         | 文件下载的函数                  |
+| autoUploadApi     | `(data: File) => void`                  | —         | 自动上传文件的 api 函数         |
+
+**使用示例：**
+
+```vue
+<template>
+  <JnFileUpload
+    v-model="fileList"
+    :auto-upload-api="uploadFile"
+    :download-file-fn="downloadFile"
+    accept=".jpg,.png"
+    :limit="5"
+  />
+</template>
+
+<script setup>
+import { ref } from 'vue'
+import { uploadFile, downloadFile } from '@/api/file'
+
+const fileList = ref([])
+</script>
+```
+
+---
+
+#### JnDialog
+
+表格编辑对话框组件
+
+**Props：**
+
+| 属性名 | 类型               | 默认值  | 说明         |
+| ------ | ------------------ | ------- | ------------ |
+| title  | `string`           | `''`    | 对话框的标题 |
+| width  | `string \| number` | `'50%'` | 对话框的宽度 |
+
+**Slots：**
+
+- `default` - 对话框内容
+
+**使用示例：**
+
+```vue
+<template>
+  <JnDialog v-model="dialogVisible" title="编辑">
+    <el-form>
+      <!-- 表单内容 -->
+    </el-form>
+  </JnDialog>
+</template>
+
+<script setup>
+import { ref } from 'vue'
+
+const dialogVisible = ref(false)
+</script>
+```
+
+---
+
+#### JnDatetime
+
+显示时间格式化组件，第一行是日期，第二行是时间
+
+**Props：**
+
+| 属性名 | 类型     | 默认值 | 说明                              |
+| ------ | -------- | ------ | --------------------------------- |
+| value  | `string` | `''`   | 时间字符串（支持 ISO 或空格分隔） |
+| color  | `string` | `''`   | 文字颜色                          |
+
+**使用示例：**
+
+```vue
+<template>
+  <JnDatetime value="2024-01-01 12:00:00" color="#409EFF" />
+</template>
+```
+
+---
+
+#### GlobalSetting
+
+全局设置组件（用于系统设置面板）
+
+**说明：** 该组件通常用于系统设置页面，提供语言、主题、主题色等配置的 UI 界面。
+
+---
+
+### @jnrs/vue-core/composables 模块
+
+#### useMouseSelection
+
+鼠标框选表格进行多选
+
+**参数：**
+
+| 参数名         | 类型                            | 默认值            | 说明           |
+| -------------- | ------------------------------- | ----------------- | -------------- |
+| containerClass | `string`                        | `'jn_table'`      | 表格或容器类名 |
+| rowClass       | `string`                        | `'el-table__row'` | 表格行类名     |
+| callback       | `(rows: HTMLElement[]) => void` | `handleSelection` | 框选后的回调   |
+
+**返回值：**
+
+| 返回值          | 类型                          | 说明                 |
+| --------------- | ----------------------------- | -------------------- |
+| handleMouseDown | `(event: MouseEvent) => void` | 鼠标按下事件处理函数 |
+
+**使用示例：**
+
+```vue
+<template>
+  <el-table class="jn_table" @mousedown="handleMouseDown" @selection-change="handleSelectionChange">
+    <!-- 表格列 -->
+  </el-table>
+</template>
+
+<script setup>
+import { useMouseSelection } from '@jnrs/vue-core/composables'
+
+const { handleMouseDown } = useMouseSelection({
+  containerClass: 'jn_table',
+  callback: (rows) => {
+    console.log('框选的行', rows)
+  }
+})
+
+const handleSelectionChange = (selection) => {
+  console.log('选中项', selection)
+}
+</script>
+```
+
+---
+
+#### useReactivityTableHeight
+
+响应式根据视口动态计算表格高度
+
+**参数：**
+
+| 参数名    | 类型     | 默认值       | 说明     |
+| --------- | -------- | ------------ | -------- |
+| className | `string` | `'el-table'` | 表格类名 |
+| bottomGap | `number` | `77`         | 底部间隔 |
+
+**返回值：**
+
+| 返回值    | 类型          | 说明         |
+| --------- | ------------- | ------------ |
+| maxHeight | `Ref<number>` | 表格最大高度 |
+
+**UseReactivityTableHeightOptions 类型：**
+
+```typescript
+interface UseReactivityTableHeightOptions {
+  className?: string // 表格类名
+  bottomGap?: number // 底部间隔
+}
+```
+
+**使用示例：**
+
+```vue
+<template>
+  <el-table :max-height="maxHeight">
+    <!-- 表格内容 -->
+  </el-table>
+</template>
+
+<script setup>
+import { useReactivityTableHeight } from '@jnrs/vue-core/composables'
+
+const { maxHeight } = useReactivityTableHeight({
+  className: 'my-table',
+  bottomGap: 100
+})
+</script>
+```
+
+**特性：**
+
+- 自动监听窗口 resize 事件
+- 防抖处理（300ms）
+- 支持 keep-alive 缓存组件
+
+---
+
+#### useWebSocket
+
+WebSocket 封装（支持心跳机制）
+
+**参数：**
+
+| 参数名                    | 类型                     | 默认值  | 说明               |
+| ------------------------- | ------------------------ | ------- | ------------------ |
+| url                       | `string`                 | —       | WebSocket 地址     |
+| connectionTimeoutDuration | `number`                 | `60000` | 网络超时时间（ms） |
+| token                     | `string`                 | —       | 认证信息           |
+| heartbeat                 | `boolean`                | `false` | 是否启用心跳       |
+| heartbeatInterval         | `number`                 | `30000` | 心跳间隔（ms）     |
+| heartbeatTimeout          | `number`                 | `10000` | 心跳超时时间（ms） |
+| showLog                   | `boolean`                | `false` | 是否打印控制台信息 |
+| showMessage               | `boolean`                | `true`  | 是否显示消息弹框   |
+| onOpen                    | `() => void`             | —       | 连接成功回调       |
+| onMessage                 | `(data) => void`         | —       | 收到消息回调       |
+| onClose                   | `() => void`             | —       | 连接关闭回调       |
+| onError                   | `(error: Event) => void` | —       | 连接错误回调       |
+
+**返回值：**
+
+| 返回值         | 类型                      | 说明           |
+| -------------- | ------------------------- | -------------- |
+| ws             | `Ref<WebSocket \| null>`  | WebSocket 实例 |
+| isLoading      | `Ref<boolean>`            | 是否正在加载中 |
+| isConnected    | `Ref<boolean>`            | 是否已连接     |
+| wsStateInfo    | `Ref<string>`             | 连接状态信息   |
+| sendMessage    | `(data: unknown) => void` | 发送消息函数   |
+| closeWebSocket | `() => void`              | 关闭连接函数   |
+
+**使用示例：**
+
+```vue
+<script setup>
+import { useWebSocket } from '@jnrs/vue-core/composables'
+
+const { ws, isConnected, sendMessage, closeWebSocket } = useWebSocket({
+  url: 'ws://localhost:8080/ws',
+  token: 'your-token',
+  heartbeat: true,
+  heartbeatInterval: 30000,
+  onOpen: () => {
+    console.log('WebSocket 连接成功')
+  },
+  onMessage: (data) => {
+    console.log('收到消息', data)
+  },
+  onClose: () => {
+    console.log('WebSocket 连接关闭')
+  },
+  onError: (error) => {
+    console.error('WebSocket 错误', error)
+  }
+})
+
+// 发送消息
+sendMessage({ type: 'chat', content: 'Hello' })
+
+// 关闭连接
+closeWebSocket()
+</script>
+```
+
+**特性：**
+
+- 自动重连机制
+- 心跳检测（前端发送 `{type: 'ping'}`，后端需返回 `{type: 'pong'}`）
+- 连接超时处理
+- 支持组件激活/停用时自动管理连接
+- 自动清理资源
+
+---
+
+## 🔍 完整使用示例
+
+```typescript
+// 导入类型
+import type { IPageData, IAttachment, IMenuItem } from '@jnrs/vue-core'
+
+// 导入 Pinia Store
+import { useSystemStore, useMenuStore } from '@jnrs/vue-core/pinia'
+
+// 导入 Router
+import { useRouter, handleRouter, createVueRouter } from '@jnrs/vue-core/router'
+
+// 导入 Composables
+import { useMouseSelection, useReactivityTableHeight, useWebSocket } from '@jnrs/vue-core/composables'
+
+// 使用 System Store
+const systemStore = useSystemStore()
+systemStore.toggleCollapse()
+systemStore.setMode('dark')
+
+// 使用 Menu Store
+const menuStore = useMenuStore()
+await menuStore.asyncSetMenus(menus)
+
+// 使用 Router
+const router = useRouter()
+await handleRouter({ name: 'dashboard' })
+
+// 创建路由实例
+const fileModules = import.meta.glob('/src/views/**/*.vue')
+const router = createVueRouter({
+  options: { history: createWebHistory() },
+  fileModules,
+  layoutName: 'layout'
+})
+
+// 使用 Composables
+const { handleMouseDown } = useMouseSelection()
+const { maxHeight } = useReactivityTableHeight()
+const { sendMessage } = useWebSocket({ url: 'ws://localhost:8080' })
+```
+
+---
+
+## 📝 注意事项
+
+1. **路由生成**：使用 `asyncGenerateRoute` 时，确保 `fileModules` 正确配置，组件路径必须以 `/` 开头且不能包含 `..`
+2. **菜单持久化**：`hasFetchedAsyncMenus` 不持久化，每次刷新页面需重新获取菜单
+3. **主题切换**：`useSystemStore` 会自动应用主题到 HTML 元素，支持 light/dark/auto 模式
+4. **WebSocket 心跳**：启用心跳时，后端必须响应 `{type: 'pong'}` 消息
+5. **表格高度**：`useReactivityTableHeight` 会自动监听窗口变化，建议配合 JnTable 的 `autoHeight` 属性使用
+6. **鼠标框选**：`useMouseSelection` 需要在表格上绑定 `@mousedown` 事件
+7. **类型安全**：所有导出均提供完整的 TypeScript 类型定义
+
+---
+
+## 📄 License
+
+UNLICENSED

package/README.md

@@ -1,7 +1,9 @@
 # @jnrs/vue-core
 
 ## ✨ 介绍
+
 巨能前端工程化开发，Vue 专用核心功能包。
+
 - Pinia store
 - Vue composables
 - Vue Router
@@ -10,14 +12,17 @@
 - 公共 Vue 组件
 
 ## 💻 技术栈
+
 TypeScript、Vue3 生态
 
 ## 🧩 安装教程
+
 ```shell
 pnpm add @jnrs/vue-core
 ```
 
 ## 🔍 使用示例
+
 ```typescript
 import type { IPageData } from '@jnrs/vue-core'
 import { useRouter, useRoute } from '@jnrs/vue-core/router'
@@ -26,232 +31,4 @@ import { useSystemStore } from '@jnrs/vue-core/pinia'
 
 ## 📋 API
 
-#### @jnrs/vue-core 模块
-接口
-
-- ElSize（Element 尺寸类型）
-```
-类型定义：字面量联合类型
-可选值：'' | 'large' | 'default' | 'small'
-```
-
-- ElButtonType（Element 按钮类型）
-```
-类型定义：字面量联合类型
-可选值：'default' | 'primary' | 'success' | 'info' | 'warning' | 'text' | 'danger'
-```
- 
-- IMenuItem 菜单项
-
-| 属性名 | 描述 | 类型 | 
-|--------|------|------|
-| meta | 路由元信息 | `RouteMeta` |
-| path | 路径 | `string` |
-| name | 名称（可选） | `string` |
-| component | 组件路径（可选） | `string` |
-| redirect | 重定向路径（可选） | `string` |
-| children | 子菜单项（可选） | `IMenuItem[]` |
-
-- Attachment（文件信息）
-
-| 属性名 | 描述 | 类型 | 
-|--------|------|------|
-| id | 数据 id | `number` |
-| documentId | 文件 id | `number` |
-| fileName | 文件名 | `string` |
-| uniqueFileName | 文件名唯一标识（用于文件获取 API） | `string` |
-| fileType | MIME 类型 | `string` |
-| fileSize | 文件大小（单位：字节） | `number` |
-
-- Pagination（分页）
-
-| 属性名 | 描述 | 类型 | 
-|--------|------|------|
-| pageNo | 当前页码 | `number` |
-| pageSize | 每页大小 | `number` |
-
-- IPageData<T>（分页列表数据）继承自 IPagination
-
-| 属性名 | 描述 | 类型 | 
-|--------|------|------|
-| list | 数据列表 | `T[]` |
-| count | 数据总数 | `number` |
-
-
-#### @jnrs/vue-core/pinia 模块
-函数
-``` typescript
-/**
- * useSystemStore 系统仓库
- * @returns theme 主题（国际化、主题、自定义强调色）
- * @returns menuCollapse 菜单是否折叠
- * @returns documentFullscreen 文档是否全屏
- * @methods toggleCollapse 折叠菜单切换
- * @methods toggleFullScreen 全屏切换
- * @methods setTheme 设置主题
- */
-```
-``` typescript
-/**
- * useMenuStore 菜单仓库
- * @returns hasFetchedAsyncMenus 菜单是否已获取
- * @returns menus 菜单项
- * @methods asyncSetMenus 设置菜单信息
- * @methods asyncClearMenu 清除菜单信息
- */
-```
-  
-#### @jnrs/vue-core/router 模块
-接口
-  - RouteMeta
-  - RouteLocationNormalizedGeneric
-  - RouteLocationNormalizedLoadedGeneric
-  - FileModules
-
-函数
-  - useRouter 原生 vue-router 函数
-  - useRoute 原生 vue-router 函数
-  - handleRouter 路由跳转或替换
-  - getRoutes 获取已注册路由
-  - createVueRouter 创建 vue-router 实例
-  - asyncGenerateRoute 设置动态路由，生成路由记录
-
-#### @jnrs/vue-core/components 模块
-Vue 组件
-  - JnTable	表格组件
-
-| 属性名 | 描述 | 类型 | 默认值 |
-|--------|------|------|--------|
-| data | 表数据 | `Record<string, any>[]` | — |
-| rowKey | 行数据的 Key，在使用 reserve-selection 功能与显示树形数据时，该属性是必填的。支持多层访问：user.info.id | `string` | `'id'` |
-| showScrollbar | 总是显示横向滚动条 | `boolean` | `false` |
-| height | 表格高度，默认为 100% | `string \| number` | `'100%'` |
-| autoHeight | 表格高度是否自动计算 | `boolean` | `false` |
-| autoHeightOptions | 表格高度自动计算配置项 | `UseReactivityTableHeighOptions` | `{}` |
-| showIndexColumn | 是否显示序号列 | `boolean` | `false` |
-| showSelectionColumn | 是否显示选择列 | `boolean` | `false` |
-| showMouseSelection | 是否开启鼠标框选 | `boolean` | `false` |
-| pagination | 当前页码和每页大小（用于序号计算） | `IPagination` | `{ pageNo: 0, pageSize: 0 }` |
-
-  - JnSelectTemplate	选择组件通用模板
-
-| 属性名 | 描述 | 类型 | 默认值 |
-|--------|------|------|--------|
-| listApi | 列表接口（必填） | `Function` | — |
-| tableName | 列表名称 | `string` | `''` |
-| tableWidth | 列表宽度 | `string` | `'60%'` |
-| listParams | 列表查询参数 | `Record<string, unknown>` | `{}` |
-| listParamsHandle | 列表查询参数前置处理函数 | `(params: Record<string, unknown>) => Record<string, unknown>` | `(params) => params` |
-| listParamsHandleAfter | 列表查询参数后置处理函数 | `(params: Record<string, unknown>) => Record<string, unknown>` | `(params) => params` |
-| keyValue | 真实数据匹配的键值对名，后续取值赋值都用 keyValue.name 和 keyValue.id | `{ name: string; id: string; [key: string]: string }` | `{ name: 'name', id: 'id' }` |
-| optionSecondaryField | keyValue 的拓展字段，用于 el-option 中显示，使用时必须在 keyValue 中定义 | `string` | — |
-| modelValue | 双向绑定值（支持多种类型） | `Record<string, unknown> \| Record<string, unknown>[] \| number \| string` | — |
-| width | 宽度 | `string` | `'100%'` |
-| simpleValue | 简单数据类型，仅返回 keyValue.id | `boolean` | `true` |
-| showAllTips | option 组件是否显示 [全部] | `boolean` | `false` |
-| onlyOption | 仅显示选择器 | `boolean` | `false` |
-| onlyButton | 仅显示选择按钮 | `boolean` | `false` |
-| filterable | 是否可筛选 | `boolean` | `true` |
-| clearable | 是否可清空 | `boolean` | `true` |
-| buttonDialogText | 按钮文字 | `string` | `'更多'` |
-| size | 按钮大小 | `ElSize` | `'default'` |
-| plain | 按钮 plain | `boolean` | `true` |
-| formRef | 父级组件的表单对象 | `FormInstance` | `null` |
-| validateFieldName | 父级表单验证的字段名（使用时必须同时传递 formRef） | `string` | `''` |
-| limit | 可选择的数量 | `number` | `1` |
-| queryForm | 表单查询参数 | `Record<string, unknown>` | — |
-| initialParams | 初始查询参数 | `Record<string, unknown>` | — |
-| remoteFilterKey | 下拉框查询参数远程过滤参数的 key 值 | `string` | `'name'` |
-
-  - JnPdfView	PDF 文件预览组件
-
-| 属性名 | 描述 | 类型 | 默认值 |
-|--------|------|------|--------|
-| fileList | 文件列表 | `IFileItem[]` | `[]` |
-| showFileName | 是否显示文件名 | `boolean` | `true` |
-| isPdf | 是否是 pdf 文件（pdf 文件直接预览，其他文件下载） | `boolean` | `false` |
-| windowWidth | 预览窗口宽度 | `number` | `800` |
-| windowHeight | 预览窗口高度 | `number` | `600` |
-
-  - JnPagination	分页组件
-
-| 属性名 | 描述 | 类型 | 默认值 |
-|--------|------|------|--------|
-| modelValue | 分页模型值 | `IPagination` | `{ pageNo: 1, pageSize: 20 }` |
-| total | 总条数 | `number` | `0` |
-| size | 按钮尺寸 | `ComponentSize` | `'small'` |
-| background | 是否带背景色 | `boolean` | `true` |
-| marginTop | 上边距 | `string` | `'10px'` |
-
-  - JnImportAndExport	导入 & 导出，此组件依赖 JnFileUpload 文件上传组件
-
-| 属性名 | 描述 | 类型 | 默认值 |
-|--------|------|------|--------|
-| importTemplateApi | 下载导入模板文件的 api 函数 | `() => Promise<Blob>` | — |
-| importApi | 数据导入 api 函数 | `(data: FormData) => Promise<IFullResponse>` | — |
-| importFieldName | 数据导入的字段名 | `string` | `'file'` |
-| importParams | 导入的参数 | `Record<string, unknown>` | — |
-| fileUploadConfig | 导入的文件上传配置 | `{ accept: string; limit: number }` | `{ accept: '.xls,.xlsx', limit: 1 }` |
-| importBtnName | 导入的按钮名称 | `string` | `'导入'` |
-| importDisabled | 是否禁用导入按钮 | `boolean` | `false` |
-| exportApi | 数据导出的 api 函数 | `(data: Record<string, unknown>) => Promise<Blob>` | — |
-| exportParams | 导出的参数 | `Record<string, unknown>` | — |
-| exportDynamicParamsConfig | 导出操作时，MessageBox 的参数配置 | `{ label: string; prop: string }` | — |
-| messageBoxInputPattern | MessageBox 中输入框的校验表达式（正则） | `RegExp` | `/^\S+(?:\s+\S+)* $ /` |
-| messageBoxInputErrorMessage | 校验未通过时的提示文本 | `string` | `'请输入参数'` |
-| exportBtnName | 导出的按钮名称 | `string` | `'导出'` |
-| exportDisabled | 是否禁用导出按钮 | `boolean` | `false` |
-| size | 按钮尺寸 | `ElSize` | `'default'` |
-| buttonType | 按钮类型 | `ElButtonType` | `'primary'` |
-| plain | 是否为朴素按钮 | `boolean` | `true` |
-| text | 是否为文字按钮 | `boolean` | `false` |
-| icon | 是否显示图标 | `boolean` | `true` |
-
-  - JnImageView	图片预览组件
-
-| 属性名 | 描述 | 类型 | 默认值 |
-|--------|------|------|--------|
-| src | 图片源地址，同原生属性一致 | `string` | `''` |
-| previewSrcList | 开启图片预览功能 | `IFileItem[]` | `[]` |
-| preview | 是否开启预览功能 | `boolean` | `false` |
-| height | 图片高度 | `string` | — |
-| maxHeight | 图片最大高度 | `string` | `'200px'` |
-
-  - JnFileUpload	通用上传 & 回显组件
-
-| 属性名 | 描述 | 类型 | 默认值 |
-|--------|------|------|--------|
-| modelValue | 绑定的模型值（文件列表） | `MixedUploadFile[]` | — |
-| uploadName | 上传的文件字段名 | `string` | `'file'` |
-| drag | 是否启用拖拽上传 | `boolean` | `false` |
-| disabled | 是否禁用 | `boolean` | `false` |
-| showFileList | 是否显示已上传文件列表 | `boolean` | `true` |
-| accept | 接受的文件类型（如 .xls,.xlsx） | `string` | `''` |
-| fileSizeMb | 单个文件大小限制（单位：MB） | `number` | `100` |
-| limit | 最大上传文件数量，0 表示不限制 | `number` | `0` |
-| size | Element Plus 组件的尺寸 | `'' \| 'small' \| 'default' \| 'large'` | `'small'` |
-| formRef | 父级组件的表单引用 | `FormInstance` | — |
-| validateFieldName | 父级表单中用于校验的字段名 | `string` | `''` |
-| downloadFileFn | 文件下载的函数 | `(data: IAttachment) => void` | — |
-| autoUploadApi | 自动上传文件的 api 函数 | `(data: File) => void` | — |
-
-  - JnDialog	表格编辑组件
-
-| 属性名 | 描述 | 类型 | 默认值 |
-|--------|------|------|--------|
-| title | 对话框的标题 | `string` | `''` |
-| width | 对话框的宽度 | `string \| number` | `'50%'` |
-
-  - JnDatetime	显示时间格式化，第一行是日期，第二行是时间
-
-| 属性名 | 描述 | 类型 | 默认值 |
-|--------|------|------|--------|
-| value | 时间字符串（支持 ISO 或空格分隔） | `string` | `''` |
-| color | 文字颜色 | `string` | `''` |
-
-
-#### @jnrs/vue-core/composables 模块
-Vue 组合式 API
-  - useMouseSelection 鼠标框选表格进行多选
-  - useReactivityTableHeight 响应式根据视口动态计算表格高度
-  - useWebSocket WebSocket 封装（支持心跳机制）
+详细文档请查看 `AGENTIC.md`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jnrs/vue-core",
-  "version": "1.2.16",
+  "version": "1.2.18",
   "description": "巨能前端工程化开发，Vue 专用核心功能包。",
   "keywords": [
     "jnrs",
@@ -21,6 +21,7 @@
   "files": [
     "dist",
     "README.md",
+    "AGENTIC.md",
     "LICENSE"
   ],
   "exports": {
@@ -58,7 +59,7 @@
     "vue": "^3.5.22",
     "vue-i18n": "^11.2.8",
     "vue-router": "^4.5.1",
-    "@jnrs/shared": "1.1.23"
+    "@jnrs/shared": "1.1.25"
   },
   "devDependencies": {
     "@vitejs/plugin-vue": "^6.0.1",