sksmas-plugin-el-vue3

v3.0.0

Published

4 days ago

用于 Maximo(玄冥资产管理系统)数据接口的 element-plus 扩展组件库(vue3版,由 sks-plugin-el-erp-vue3 移植)

0High
0Medium
0Low

shoukaiseki

sksmas-plugin-el-vue3

用于 Maximo（玄冥资产管理系统）数据接口的 element-plus 扩展组件库（Vue3 版），由 sks-plugin-el-erp-vue3 派生并全量改名为 SksMas*。

版本：3.0.0
定位：Maximo 数据接口（REST / JSON）前端 UI 组件库
宿主框架：Vue 3 + Element Plus（若依 RuoYi-Vue3 适配版 sks-eam-vue3-typescript）
相对 sks-plugin-el-erp-vue3 的差异：
1. 全部组件、工具函数、文件名由 Sks/sks 改名为 SksMas/sksMas/sksmas
2. 新增 Maximo 日期时间支持：lib/sksmas-date.js + SksMasDate / SksMasTime / SksMasDateTime，timeZone 默认 GMT+8

依赖说明

peerDependencies（由宿主项目提供）：

| 依赖 | 版本 | |------|------| | vue | ^3.2.0 | | element-plus | ^2.0.0 | | @element-plus/icons-vue | ^2.0.0 |

dependencies：

| 依赖 | 版本 | 用途 | |------|------|------| | sortablejs | 1.15.0 | SksMasTable 列拖拽排序 | | clipboard | ^2.0.11 | 复制到剪贴板 | | mathjs | ^11.3.3 | 精确数值计算（sksmas-number-math） |

接入方式（源码级 alias 引入）

本库不发布 npm 包，以独立仓库形式被宿主项目通过 vite alias 源码级编译（当前宿主：e:/gitwork/sks-maximo-solon/sks-eam-vue3-typescript）。

vite.config.ts 配置

import path from 'path'

export default {
  resolve: {
    alias: [
      // 插件库源码位于宿主项目外，裸导入无法向上解析到宿主 node_modules，
      // 需显式指向宿主依赖
      { find: 'mathjs', replacement: path.resolve(__dirname, './node_modules/mathjs') },
      { find: 'clipboard', replacement: path.resolve(__dirname, './node_modules/clipboard') },
      { find: 'sortablejs', replacement: path.resolve(__dirname, './node_modules/sortablejs') },
      // 子模块源码引入（正则需排在主入口之前）
      { find: /^sksmas-plugin-el-vue3\/lib\/(.*)/, replacement: 'E:/gitwork/sksmas-plugin-el-vue3/lib/$1' },
      // 主入口
      { find: 'sksmas-plugin-el-vue3', replacement: 'E:/gitwork/sksmas-plugin-el-vue3/index.js' }
    ]
  },
  server: {
    fs: {
      // 允许访问项目外的插件库源码
      allow: [path.resolve(__dirname, './'), 'E:/gitwork/sksmas-plugin-el-vue3']
    }
  }
}

注册插件

// main.ts（在 ElementPlus 之后、mount 之前）
import request, { download } from '@/utils/request'
import SksMasPluginElVue3 from 'sksmas-plugin-el-vue3'

app.use(SksMasPluginElVue3, { request })

install(app, opts) 会：

全局注册全部组件（app.component(component.name, component)）
挂载全局属性到 app.config.globalProperties：
- sksMasUtils — 常用工具函数集合
- sksMasDateUtils — Maximo 日期时间工具集合（lib/sksmas-date.js）
- sksMasConfig — 配置与默认 request
- resetForm / clearFormValidate — 表单重置
- $SKSMAS_PLUGIN_EL_ERP — { request }（宿主传入的 axios 实例）

页面命名导入

import { newSksMasTable, newSksMasDialogInfo, newTableColumn, newTableColumnList } from 'sksmas-plugin-el-vue3'
import { initListVueVirtualUUID, mergeFromObject } from 'sksmas-plugin-el-vue3/lib/core'

主入口同时提供 default 导出（含 install 与全部组件）与命名导出（工具函数 + 组件）。

组件列表

| 组件 | 说明 | |------|------| | SksMasTable | 核心列表组件：动态列、表头 QBE 过滤行、列排序、显示属性名、更多列配置 | | SksMasCacheTable | 带缓存的表格 | | SksMasPagination | 分页 | | SksMasRightToolbar | 右侧工具栏（刷新/隐藏搜索/显示所有列/显示属性名） | | SksMasButton | 按钮封装 | | SksMasButtonTooltip | 带提示的按钮 | | SksMasCheckbox | 复选框封装 | | SksMasDate | Maximo DATE（MaxType=3）日期选择，值 yyyy-MM-dd | | SksMasTime | Maximo TIME（MaxType=5）时间选择，值 HH:mm:ss | | SksMasDateTime | Maximo DATETIME（MaxType=4）日期时间选择，值 yyyy-MM-dd'T'HH:mm:ssXXX，带 timeZone | | SksMasDateYmdRange | 年月日范围选择（可输出 DATE 或 DATETIME 两种格式） | | SksMasStatusSelect | 状态选择 | | SksMasDictLabelTag | 字典值标签展示 | | SksMasImageUseImgUrl | 图片 URL 展示 | | SksMasHtmlMessagePromptDialog | HTML 消息提示对话框 | | SksMasDialog | 增强对话框：最大化/全屏切换、标题栏拖拽，支持全局与单独配置（默认开启） | | SksMasTableQueryFormEl | 列表过滤表单 | | SksMasTablePropTable | 列配置表格（更多列设置弹窗） | | SksMasSelectSingleByLookupController | Lookup 单选下拉 | | SksMasSelectMultipleByLookupController | Lookup 多选下拉 | | SksMasRadioSingleByLookupController | Lookup 单选 | | SksMasSelectMultipleToBitValue | 多选转位标志值 | | SksMasFilterParamInput | 过滤参数输入框 | | SksMasFilterParamDateRange | 过滤参数日期范围 | | SksMasFilterParamDictSelect | 过滤参数字典选择 |

Maximo 日期时间（核心新增能力）

Maximo 三种日期类型与 JSON 值格式

| MaxType | 类型码 | Maximo JSON 值 | 说明 | |---------|--------|----------------|------| | DATE | 3 | 2026-05-16 | MXFormat.dateToSQLString | | DATETIME | 4 | 2026-05-16T05:48:25+08:00 | ConversionUtil.dateToString；开启 mxe.int.enabledatemillis=1 时带 .SSS | | TIME | 5 | 05:48:25 | MXFormat.timeToSQLString |

组件用法

<!-- 用法一：v-model -->
<SksMasDate v-model="form.planDate" />
<SksMasTime v-model="form.startTime" />
<SksMasDateTime v-model="form.createdDate" />

<!-- 用法二：formData + propName（值直接写入表单对象，并支持 clearValidate 联动） -->
<el-form ref="form" :model="form" :rules="rules">
  <el-form-item prop="planDate" label="计划日期">
    <SksMasDate :formData="form" propName="planDate" @clearValidate="clearFormValidate" />
  </el-form-item>
  <el-form-item prop="createdDate" label="创建时间">
    <SksMasDateTime :formData="form" propName="createdDate"
                    timeZone="GMT+8" millis
                    @clearValidate="clearFormValidate" />
  </el-form-item>
</el-form>

<!-- 日期范围：输出到两个字段；maxType="DATETIME" 时起点 00:00:00、终点 23:59:59 -->
<SksMasDateYmdRange :formData="form"
                    startTimePropName="startDate"
                    endTimePropName="endDate"
                    maxType="DATETIME" />

组件 props：

| prop | 类型 | 默认 | 说明 | |------|------|------|------| | modelValue | String/Number/Date | — | v-model 绑定值（Maximo 原数据格式） | | formData | Object | — | 表单对象，与 propName 配合 | | propName | String | — | 字段名，支持 a.b.c 路径 | | timeZone | String | GMT+8 | 时区，支持 GMT+8 / +08:00 / Asia/Shanghai | | format | String | 按类型 | 显示格式（dayjs token，如 YYYY-MM-DD HH:mm:ss） | | valueFormat | String | 同 format | 控件内部值格式，一般无需修改 | | placeholder | String | 按类型 | 占位提示 | | clearable / disabled | Boolean | true / false | 可清空 / 禁用 | | appendTime | String | — | 日期补齐时间，如 " 23:59:59"（首个字符为空格） | | millis | Boolean | false | DATETIME 是否输出毫秒 | | emitClearValidate | Boolean | true | 值变化后是否触发 clearValidate | | refDate | String/Number/Date | 今天 | 仅 SksMasTime：纯时间解析的基准日期 |

lib/sksmas-date.js 工具方法

| 方法 | 说明 | |------|------| | parseTimeZoneOffset(tz) | 解析 GMT+8 / +08:00 / Asia/Shanghai 为分钟偏移（GMT+8 → 480） | | formatOffset(minutes) | 分钟偏移 → +08:00 | | parseToUtcMillis(value, {timeZone, refDate}) | Maximo 值 → UTC 毫秒（值自带偏移时以值自带偏移为准） | | getParts(value, timeZone) | 取指定时区下的年月日时分秒字段 | | nowInTimeZone(timeZone) | 取该时区下的"现在" | | formatDate(value, fmt, {timeZone}) | 按 token 格式化，同时支持 dayjs 大写与 Java 小写 token，支持单引号字面量 | | toMaxDate / toMaxTime / toMaxDateTime | 生成 Maximo 原数据值 | | toMaxValue(value, maxType, opts) | 按 MaxType 码生成 Maximo 原数据值 | | formatByMaxType(value, maxType, opts) | 按 MaxType 码格式化显示 | | maxValueToElValue / elValueToMaxValue | Maximo 值与控件值互转 | | toMaxTypeCode('DATETIME') / isDateTimeMaxType(code) | 类型名/类型码转换 | | isValidDateValue / compareDateValue | 有效性校验 / 比较 | | convertTimeZone(value, tz) | 换时区显示 | | toMaxDayBoundary(value, {type:'start'\|'end'}) | 当天 00:00:00 / 23:59:59 |

import { toMaxDateTime, parseTimeZoneOffset, MAX_TYPE } from 'sksmas-plugin-el-vue3/lib/sksmas-date'
// 或使用全局属性
this.sksMasDateUtils.toMaxDateTime(Date.now(), { timeZone: 'GMT+8' })
// => '2026-05-16T05:48:25+08:00'

所有换算均通过 UTC 计算，结果与浏览器本地时区无关。

lib 工具模块

| 模块 | 说明 | |------|------| | lib/core.js | 核心工具：mergeFromObject、deepCopy、UUID/vueVirtualUUID、位标志转换、字符串/数组判断等 | | lib/sksmas-date.js | Maximo 日期时间解析/时区换算/格式化（DATE/TIME/DATETIME） | | lib/sksmas-model-utils.js | newSksMasTable / newSksMasDialogInfo / newTableColumn(List) 模型工厂 | | lib/sksmas-page.js | sksMasPageMixin 页面混入 | | lib/sksmas-app-utils.js | addOrUpdateRow / deleteRow / rowStyleElTable 等表格行操作 | | lib/sksmas-number-math.js | 基于 mathjs 的精确数值运算（multiply/divide/sum/subtractNullIsZero 等） | | lib/sksmas-number-utils.js | negateNumber / absNumber / numberIsZeroOrNull 等 | | lib/modal.js | msgSuccess / msgError / msgInfo / msgLoading（基于 ElMessage） | | lib/ref.js | resetForm 表单重置 | | lib/clipboard.js | 复制到剪贴板 | | lib/validate.js | isExternal 等校验 | | lib/sksmasConfig.js | sksMasConfig 与默认 request | | lib/sksmas-mock-utils.js | simulateFilterByQueryParams 前端模拟过滤 | | lib/style/sksmas-main.css | 全局样式 |

Vue2 → Vue3 移植要点

移植时统一执行的语法转换（新增/修改组件时请保持一致）：

| Vue2 写法 | Vue3 写法 | |-----------|-----------| | slot="name" | #name（v-slot） | | slot-scope="scope" | #default="scope" | | :visible.sync / .sync | v-model / v-model:xx | | el-icon-xxx 类名图标 | @element-plus/icons-vue 组件 | | beforeDestroy | beforeUnmount | | this.$set(obj, k, v) | 直接赋值 obj[k] = v | | this.$on / $off / $emit 总线 | 移除（改用 props/emit 或 mitt） | | this.$confirm / this.$message | ElMessageBox.confirm / ElMessage | | valueFormat="yyyy-MM-dd" | value-format="YYYY-MM-DD"（dayjs 格式） | | @keyup.enter.native | @keyup.enter | | el-radio-button label="x" | value="x" | | el-button type="text" | el-button link type="primary" | | JSX renderHeader | el-table-column 的 #header 插槽模板 | | Vue.use(plugin) | app.use(plugin)，install 签名改为 (app, opts) |

SksMasTable 扩展能力（本次移植新增）

表头 QBE 过滤行：headerFilterEnable: true 时每列表头下方显示过滤输入框，回车/清除触发 qbeFilter 事件（值存于 mainTable.qbe[prop]）
列排序：@sort-change → sortChange 事件 {column, prop, order}
显示属性名：showTablePropName 开关在表头以 tag 展示属性名（prop）
事件：refresh、sortChange、qbeFilter

目录结构

sksmas-plugin-el-vue3/
├── index.js               # 主入口：install + default 导出 + 命名导出
├── lib/
│   ├── core.js            # 核心工具
│   ├── sksmas-date.js     # Maximo 日期时间工具（DATE/TIME/DATETIME）
│   ├── sksmas-model-utils.js # 模型工厂
│   ├── ui/                # 组件（每组件一个目录 + index.js 子入口）
│   │   ├── sksmas-table/src/SksMasTable.vue
│   │   ├── sksmas-date/src/main.vue            # SksMasDate
│   │   ├── sksmas-date/src/sksmas-date-core.js # 三个日期组件共享逻辑
│   │   ├── sksmas-time/src/main.vue            # SksMasTime
│   │   ├── sksmas-date-time/src/main.vue       # SksMasDateTime
│   │   ├── sksmas-date-ymd-range/index.vue     # SksMasDateYmdRange
│   │   └── ...
│   └── style/sksmas-main.css
├── tools/                 # 自检脚本（不参与打包）
├── rollup.test.config.mjs # 编译验证配置
├── docs/                  # vuepress 文档
└── package.json           # name=sksmas-plugin-el-vue3 version=3.0.0

自检（npm test）

npm install          # 首次需要安装依赖
npm test             # 一键自检:7 项全部通过

npm test 依次执行（可用 npm run test:date / npm run test:build 单独跑）：

| 步骤 | 说明 | |------|------| | 日期工具单测 | lib/sksmas-date.js 的时区/解析/格式化（58 项） | | 组件核心换算单测 | sksmas-date-core.js 的 Maximo 值 ↔ 控件值往返（49 项） | | 组件实例逻辑单测 | mock 实例调用 handleChangeValue/initCurrentValue，校验表单写入与事件（43 项） | | 语法校验 | 全部 .js 与 .vue 内嵌 <script> 的 ESM 语法（84 块） | | 导入可解析性 | 130 处相对导入均可解析 | | 导入大小写一致性 | 防止 Windows 下大小写不敏感的路径在 Linux 构建时失败 | | rollup 编译验证 | 用 @vue/compiler-sfc 编译主入口与全部子模块（不依赖 esbuild） |

编译验证使用 rollup 而非 vite：vite 依赖 esbuild，而 esbuild 需要 spawn 子进程，在受限环境中会被拒绝。

注意事项

插件库源码在宿主项目之外，vite 必须配置 server.fs.allow，否则开发服务器拒绝加载
插件库内部的裸导入（mathjs/clipboard/sortablejs）需在宿主 alias 中显式指向宿主 node_modules
子入口 lib/ui/*/index.js 中导入 .vue 文件必须带 .vue 扩展名（Vite 不做无扩展名解析）
组件 name 必须保留（全局注册与 keep-alive 依赖），如 SksMasTable、SksMasRightToolbar

附：原 Vue2 版发布流程（存档）

以下内容适用于原 Vue2 版 sks-plugin-el-erp 的 npm 发布，Vue3 版当前采用源码级 alias 引入，无需发布。

# 发布前配置
npm login --registry=https://registry.npmjs.org

# 发布正式版
npm publish

# 发布测试版（package.json version 如 1.0.4-beta.2）
npm publish --tag beta1 --registry=https://registry.npmjs.org

# 安装测试版
npm install sks-plugin-el-erp@beta1

撤销发布包千万不要使用：即使撤销了发布的包，发包时也不能再和被撤销的包名称与版本重复。

scss 编译成 css

将 package-sass221102.json 中的依赖复制到 package.json 安装后执行：

npm run css:build

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

sksmas-plugin-el-vue3

依赖说明

接入方式（源码级 alias 引入）

vite.config.ts 配置

注册插件

页面命名导入

组件列表

Maximo 日期时间（核心新增能力）

Maximo 三种日期类型与 JSON 值格式

组件用法

lib/sksmas-date.js 工具方法

lib 工具模块

Vue2 → Vue3 移植要点

SksMasTable 扩展能力（本次移植新增）

目录结构

自检（npm test）

注意事项

附：原 Vue2 版发布流程（存档）

scss 编译成 css