npm package: @jnrs/vue-core
Description: 巨能前端工程化开发，Vue 专用核心功能包。
Author: talia_tan
Latest version: 1.2.10

# @jnrs/vue-core

## ✨ 介绍
巨能前端工程化开发，Vue 专用核心功能包。
- Pinia store
- Vue composables
- Vue Router
- 全局指令
- 插件
- 公共 Vue 组件

## 💻 技术栈
TypeScript、Vue3 生态

## 🧩 安装教程
```shell
pnpm add @jnrs/vue-core
```

## 🔍 使用示例
```typescript
import type { User, DictItem } from '@jnrs/vue-core'
import { useRouter, useRoute } from '@jnrs/vue-core/router'
import { useAuthStore } from '@jnrs/vue-core/pinia'
```

## 📋 API

#### @jnrs/vue-core 模块
接口

- ElSize（Element 尺寸类型）
```
类型定义：字面量联合类型
可选值：'' | 'large' | 'default' | 'small'
```

- ElButtonType（Element 按钮类型）
```
类型定义：字面量联合类型
可选值：'default' | 'primary' | 'success' | 'info' | 'warning' | 'text' | 'danger'
```
 
- MenuItem 菜单项

| 属性名 | 描述 | 类型 | 
|--------|------|------|
| meta | 路由元信息 | `RouteMeta` |
| path | 路径 | `string` |
| name | 名称（可选） | `string` |
| component | 组件路径（可选） | `string` |
| redirect | 重定向路径（可选） | `string` |
| children | 子菜单项（可选） | `MenuItem[]` |

- Attachment（文件信息）

| 属性名 | 描述 | 类型 | 
|--------|------|------|
| id | 数据 id | `number` |
| documentId | 文件 id | `number` |
| fileName | 文件名 | `string` |
| uniqueFileName | 文件名唯一标识（用于文件获取 API） | `string` |
| fileType | MIME 类型 | `string` |
| fileSize | 文件大小（单位：字节） | `number` |

- Pagination（分页）

| 属性名 | 描述 | 类型 | 
|--------|------|------|
| pageNo | 当前页码 | `number` |
| pageSize | 每页大小 | `number` |

- PageTableDataT（分页列表数据）继承自 Pagination

| 属性名 | 描述 | 类型 | 
|--------|------|------|
| list | 数据列表 | `T[]` |
| count | 数据总数 | `number` |


#### @jnrs/vue-core/pinia 模块
函数
``` typescript
/**
 * useSystemStore 系统仓库
 * @returns theme 主题（国际化、主题、自定义强调色）
 * @returns menuCollapse 菜单是否折叠
 * @returns documentFullscreen 文档是否全屏
 * @methods toggleCollapse 折叠菜单切换
 * @methods toggleFullScreen 全屏切换
 * @methods setTheme 设置主题
 */
```
``` typescript
/**
 * useAuthStore 权限仓库
 * @returns hasAuthenticated 是否已登录
 * @returns token 登录凭证
 * @returns userInfo 用户信息
 * @returns dict 字典
 * @methods asyncSetAuth 设置权限信息
 * @methods clearAuth 清除权限信息
 */
```
``` 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 | 当前页码和每页大小（用于序号计算） | `Pagination` | `{ 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 | 文件列表 | `FileItem[]` | `[]` |
| showFileName | 是否显示文件名 | `boolean` | `true` |
| isPdf | 是否是 pdf 文件（pdf 文件直接预览，其他文件下载） | `boolean` | `false` |
| windowWidth | 预览窗口宽度 | `number` | `800` |
| windowHeight | 预览窗口高度 | `number` | `600` |

  - JnPagination	分页组件

| 属性名 | 描述 | 类型 | 默认值 |
|--------|------|------|--------|
| modelValue | 分页模型值 | `Pagination` | `{ 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<BusinessResponse>` | — |
| 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 | 开启图片预览功能 | `FileItem[]` | `[]` |
| 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: Attachment) => 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 封装（支持心跳机制）