automes-ui

AutoMes UI

基于 PrimeVue 的 MES 系统 UI 组件库。

📦 简介

automes-ui 是一个为 MES 系统定制的 Vue 3 组件库，基于 PrimeVue 构建，提供了一套统一的 UI 组件和主题配置。

✨ 特性

• 🎨 基于 PrimeVue 4.x 的自定义主题
• 🔧 开箱即用的业务组件
• 📱 响应式设计
• 💪 完整的 TypeScript 类型支持
• 🎯 全局组件类型声明
• ⚡ Vite 构建
• 📦 支持 ES Module 和 CommonJS

📚 常用组件

以下为常用能力摘录，不是完整公开导出清单。完整边界以 automes-ui、automes-ui/heavy、automes-ui/primevue、automes-ui/themes 与 styles 子路径约定为准。

基础组件

• MsButton - 按钮组件
• MsSwitch - 开关组件
• MsTooltip - 提示框组件

数据展示

• MsTable - 数据表格
• MsEmpty - 空状态组件

表单组件

• MsForm - 表单组件
• MsSelect - 选择器组件
• MsPickList - 穿梭框组件

反馈组件

• MsDialog - 对话框
• MsMessage - 消息提示

兼容保留组件

• MsConfirm - 兼容保留确认组件（新增代码优先使用 MsMessage.confirm(...)）

导航组件

• MsMenu - 菜单组件
• MsRouteSearch - 路由搜索
• MsSearch - 搜索栏

heavy 组件

• MsBpmn - BPMN 流程设计器
• MsSqlEditor - SQL 编辑器
• MsWorkFlow - 工作流设计器

🚀 安装

npm

npm install automes-ui

pnpm

pnpm add automes-ui

yarn

yarn add automes-ui

注意: automes-ui 会与应用共享同一份 vue、primevue、@primevue/core 与 @primeuix/themes；在 monorepo 或严格包管理模式下，建议应用侧显式安装并锁定这些 peer 依赖。primeicons、primelocale、@primevue/forms 与 @vueuse/core 由组件库自身依赖提供。只有当业务代码本身需要路由跳转，或希望 MsMenu 根据当前路由自动高亮时，才需要在应用侧安装并初始化 vue-router。

Monorepo 中使用

{
  "dependencies": {
    "automes-ui": "workspace:^"
  }
}

📖 使用

方式 1: 默认插件

默认插件会自动配置 PrimeVue，并注册 core + business 组件：

import { createApp } from "vue";
import AutomesUI from "automes-ui";
// 导入样式
import "automes-ui/styles";
import App from "./App.vue";

const app = createApp(App);

// 自动完成：
// 1. 配置 PrimeVue + 自定义主题
// 2. 注册 core + business 组件
app.use(AutomesUI);

app.mount("#app");

默认插件不包含 MsBpmn、MsSqlEditor、MsWorkFlow。这三个重型组件需要从 automes-ui/heavy 单独引入。

方式 2: 手动接管 PrimeVue + 注册组件

如果你需要手动接管 PrimeVue 配置，同时仍想复用组件库默认初始化参数并注册 core + business 组件：

import { createApp } from "vue";
import { install, setupPrimeVue } from "automes-ui";
import { PrimeVue } from "automes-ui/primevue";
import "automes-ui/styles";
import App from "./App.vue";

const app = createApp(App);

// 先配置 PrimeVue
setupPrimeVue(app, PrimeVue, {
  // 只传入你想覆盖的 PrimeVue 配置
});

// 再注册组件
app.use({ install });

app.mount("#app");

setupPrimeVue() 默认会补齐 createCustomPreset()、zh_CN locale、ripple: true 和 inputVariant: "outlined"；手动接管时只需要覆盖差异项。

方式 3: 按需引入 core / business 组件

import { MsButton, MsDialog, MsMessage } from "automes-ui";
// 导入样式
import "automes-ui/styles";

// 在组件中使用
export default {
  components: {
    MsButton,
    MsDialog,
  },
};

MsDialog 推荐通过 v-model 控制显隐。visible / v-model:visible 仅兼容保留；showCancelBtn 为正式属性，showCancel 为兼容别名。确认按钮默认只触发 confirm 事件，不会自动关闭。

方式 4: 使用 heavy 组件

import { createApp } from "vue";
import AutomesUI from "automes-ui";
import AutomesUIHeavy from "automes-ui/heavy";
import "automes-ui/styles";
import App from "./App.vue";

const app = createApp(App);

app.use(AutomesUI);
app.use(AutomesUIHeavy);

app.mount("#app");

automes-ui/heavy 只负责 heavy 组件注册，本身不处理 PrimeVue 初始化；初始化仍然需要先走默认插件 automes-ui，或先执行 setupPrimeVue() 再注册组件。

也可以只按需导入 heavy 组件本体，再单独导入对应样式；前提同样是应用已经先完成 PrimeVue 初始化：

import { MsSqlEditor } from "automes-ui/heavy";
import "automes-ui/heavy/styles";

样式入口

• automes-ui/styles: core + business + heavy
• automes-ui/core/styles: 仅 core
• automes-ui/business/styles: core + business
• automes-ui/heavy/styles: core + heavy

提示: 默认插件和 install() 只注册 core + business 组件；如果模板里直接使用 heavy 组件，需要显式引入 automes-ui/heavy。

TypeScript 支持

组件库提供完整的类型定义，安装后即可获得：

• ✅ 组件 Props 的智能提示
• ✅ 事件类型检查
• ✅ 默认插件下的 core + business 全局组件类型声明
• ✅ 引入 automes-ui/heavy 后的 heavy 组件类型声明

类型边界约定如下：

• 组件本体按分层导入：core / business 走 automes-ui，heavy 走 automes-ui/heavy
• heavy 组件的全局模板类型声明依赖 automes-ui/heavy 子路径被 TypeScript 载入
• 根入口目前仍兼容保留部分 heavy 相关类型与 defaultPaletteConfig，并带有弃用提示；新增代码应优先从 automes-ui/heavy 导入这些能力
• 根入口当前还兼容保留 MsConfirm、MsFormItem、MsImageViewer 等非主公开面的组件导出，并带有弃用提示；新增代码应优先使用 MsMessage.confirm(...)、MsForm 的配置式能力，或复用业务侧图片预览封装 / MsUpload 内置预览能力

// 自动获得类型提示
import type { MsFormProps, MsSelectProps, MsColumnType } from 'automes-ui'

// 在模板中使用组件也有完整的类型提示
<template>
  <MsButton label="点击" @click="handleClick" />
  <MsDialog v-model="visible" title="标题" />
</template>

使用自定义主题

组件库内置了自定义的 PrimeVue Aura 主题预设，使用默认插件时会自动应用：

// 主题配置已内置，包含：
// - 自定义颜色方案
// - Ripple 波纹效果
// - Outlined 输入框样式

如果需要自定义主题，可以单独导入：

import { install, setupPrimeVue } from "automes-ui";
import { PrimeVue } from "automes-ui/primevue";
import { createCustomPreset } from "automes-ui/themes";

setupPrimeVue(app, PrimeVue, {
  theme: {
    preset: createCustomPreset(),
    options: {
      darkModeSelector: ".dark-mode",
    },
  },
});

app.use({ install });

automes-ui/themes 只提供主题预设封装；实际主题运行时仍依赖消费方项目中已安装的 @primeuix/themes。

📚 API 文档

导出的类型

// 组件 Props 类型
import type {
  SwitchProps,
  MsFormProps,
  MsFormItemType,
  MsSelectProps,
  MsPickListProps,
  ConfirmProps,
  MsSearchFormItem,
  MsColumnType,
} from "automes-ui";

// 工具类型
import type {
  ConfirmInstance,
  ConfirmOptions,
  ConfirmHandler,
  Message,
} from "automes-ui";

全局方法

// Message 消息提示
import { MsMessage } from "automes-ui";

MsMessage.success("操作成功");
MsMessage.error("操作失败");
MsMessage.warning("警告信息");
MsMessage.info("提示信息");

// Confirm 函数式确认
const result = await MsMessage.confirm({
  title: "确认删除",
  message: "确定要删除这条记录吗？",
  type: "danger",
});

MsConfirm 目前作为兼容导出保留；新增代码优先通过 MsMessage.confirm(...) 及其 success / warning / danger / info 变体调用函数式确认。

🛠️ 开发

本地开发

# 安装依赖
pnpm install

# 构建
pnpm build

# 发布：更新 package.json 版本并推送默认分支
pnpm version patch --no-git-tag-version
git add package.json pnpm-lock.yaml
git commit -m "chore(release): prepare ui v1.2.8"
git push origin main

默认分支构建成功后，GitLab CI 会自动创建 ui-v<package version> tag，并将构建产物发布到 npm。项目 CI/CD Variables 必须配置受保护且 masked 的 NPM_TOKEN：它必须是 npm 网站生成的 granular access token，对 automes-ui（或全部包）具有 Read and write (publish and stage) 权限，并勾选 Bypass two-factor authentication。仅能登录/读取包的 token，或未勾选绕过 2FA 的 token，都会在 npm publish 阶段返回 HTTP 403。tag 推送可启用 GitLab 的 Allow Git push requests to the repository（使用 CI_JOB_TOKEN），或另行配置具有 write_repository 权限的 GITLAB_PUSH_TOKEN。

目录结构

automes-ui/
├── src/
│   ├── core/           # core 分层入口
│   ├── business/       # business 分层入口
│   ├── heavy/          # heavy 分层入口
│   ├── styles/         # 样式分层入口
│   ├── components/     # 组件源码
│   ├── hooks/          # 自定义 Hooks
│   └── themes/         # 主题配置
├── core.ts             # core 子入口
├── business.ts         # business 子入口
├── heavy.ts            # heavy 子入口
├── themes.ts           # 主题子入口
├── styles.ts           # 全量样式入口
├── core-styles.ts      # core 样式入口
├── business-styles.ts  # business 样式入口
├── heavy-styles.ts     # heavy 样式入口
├── index.ts            # 默认插件入口
├── es/                 # ES 模块构建输出
├── lib/                # CommonJS 构建输出
└── global.d.ts         # 兼容保留的全局声明

子路径导出

import AutomesUI from "automes-ui";
import { MsButton } from "automes-ui/core";
import { MsForm } from "automes-ui/business";
import { MsBpmn } from "automes-ui/heavy";
import { createCustomPreset } from "automes-ui/themes";

分层约定

• automes-ui: 默认插件入口，负责 PrimeVue 初始化，并导出 core + business 组件与常用类型
• automes-ui/core: 仅基础能力组件
• automes-ui/business: 仅业务通用组件
• automes-ui/heavy: MsBpmn、MsSqlEditor、MsWorkFlow 及其相关类型、默认配置
• automes-ui/themes: 主题预设子路径；运行时依赖应用侧安装的 @primeuix/themes
• automes-ui/styles / core/styles / business/styles / heavy/styles: 按层级拆分的样式入口

📝 依赖

建议应用侧显式安装

• Vue ^3.5.0
• Vue Router ^4.5.0（仅在业务代码需要路由跳转，或希望 MsMenu 根据当前路由自动高亮时安装）
• PrimeVue ^4.4.0
• @primevue/core ^4.5.3
• @primeuix/themes ^1.2.5

Dev Dependencies

• TypeScript ^5.8.2
• Vite ^6.0.3
• @vitejs/plugin-vue ^5.2.1

🔗 相关链接

• PrimeVue 官方文档
• GitHub 仓库
• NPM 包

📋 更新日志

v1.0.4

• ✨ 提供 automes-ui/styles 样式入口
• 📝 更新文档，添加样式导入说明
• 🐛 修复引入后没有样式的问题
• 💡 支持通过 import 'automes-ui/styles' 导入所有必需样式

v1.0.3

• 📝 更新 README 文档

v1.0.2

• ✨ 添加完整的 TypeScript 类型支持
• ✨ 添加全局组件类型声明
• 🐛 修复 install 函数导出问题

v1.0.1

• 🎉 首次发布
• ✨ 基础组件库
• ✨ 自定义主题配置

🤝 贡献

欢迎提交 Issue 和 Pull Request！

👨‍💻 作者

hero

📄 许可证

ISC