❤
npm
Sign UpSign In

mes-ui

1.1.10 • Public • Published

MES UI 前端共享组件库

这是一个 MES 前端共享代码模块项目，提供可复用的组件和页面模板。

功能特性

  • 🚀 模板生成: 通过 CLI 工具快速生成组件和页面模板
  • 👀 实时预览: 内置预览功能，可视化查看所有模板效果
  • 📝 代码查看: 在预览界面中直接查看模板源代码
  • 📱 响应式预览: 支持桌面、平板、手机等不同设备尺寸预览
  • 🎨 现代化UI: 基于 Ant Design 的美观界面
  • ⚡ 自动化配置: 自动扫描模板目录，生成配置文件
  • 🔍 文件监听: 自动监听模板文件变化，实时更新配置
  • 🤖 AI 集成: 支持 MCP 协议，可与 Cursor 等 AI 工具无缝集成

安装使用

1. 安装依赖

npm install

2. 启动预览服务

# 方式一：带文件监听的开发模式（推荐）
npm run dev:watch

# 方式二：自动生成配置并启动预览
npm run dev

# 方式三：仅启动预览服务
npm run preview

预览服务启动后，访问 http://localhost:3000 即可查看所有模板。

3. 在业务项目中使用模板

在你的业务项目中安装并使用：

# 安装 CLI 工具
npm install mes-ui

# 方式一：交互式选择模板
npx mes-ui add

# 方式二：直接指定模板名称
npx mes-ui add account-settings

# 方式三：批量添加多个模板
npx mes-ui add account-settings user-management login

# 检查模板更新
npx mes-ui check-updates

可用命令

CLI 命令

  • mes-ui add - 添加模板到项目（支持交互式选择或直接指定模板）
  • mes-ui add <template-name> - 直接添加指定模板（支持模糊匹配）
  • mes-ui add <template1> <template2> ... - 批量添加多个模板
  • mes-ui list - 列出已生成的模块
  • mes-ui remove - 删除已生成的模块
  • mes-ui upgrade - 升级已生成的模块
  • mes-ui check-updates - 检查模板更新（基于内容哈希）
  • mes-ui mcp-server - 启动 MCP 服务器（用于 Cursor 集成）

NPM 脚本

  • npm run dev:watch - 启动文件监听 + 预览服务（推荐开发模式）
  • npm run dev - 生成配置并启动预览服务
  • npm run preview - 启动预览服务（开发模式）
  • npm run preview:build - 构建预览站点
  • npm run preview:dev - 启动预览服务（支持外部访问）
  • npm run generate-config - 手动生成模板配置
  • npm run watch-templates - 启动文件监听服务

模板配置系统

自动化配置

本项目采用完全自动化的模板配置系统：

  1. 配置文件: 每个模板目录下需要包含 config.json 文件
  2. 自动扫描: 脚本会自动扫描 /templates 目录下的所有模板
  3. 动态生成: 自动生成多种配置映射供不同模块使用
  4. 文件监听: 自动监听模板文件变化，实时更新配置
  5. 智能导入: 基于配置自动生成模板内容导入映射

🔧 生成的配置类型

系统会自动生成以下配置对象：

  • templateConfigs: 统一的模板配置数组，包含完整信息
  • staticImportMap: 静态文件导入映射，用于代码查看
  • componentImportMap: 组件导入映射，用于预览渲染
  • 工具函数: 提供便捷的配置访问方法

📦 依赖管理系统

每个模板可以在 config.json 中定义自己的依赖：

{
  "id": "YourComponent",
  "name": "组件名称",
  "description": "组件描述",
  "dependencies": {
    "lodash": "^4.17.21",
    "moment": "^2.29.4",
    "@ant-design/pro-components": "^2.4.4"
  }
}

系统会自动合并默认依赖（React + Antd）和自定义依赖，CLI工具会自动安装所有必需的依赖包。

常用依赖说明：

  • @ant-design/pro-components: 用于页面模板的 ProComponents 组件
  • react-syntax-highlighter: 代码高亮显示
  • lodash: 工具函数库
  • dayjs: 日期处理库（推荐替代 moment）

🎯 智能路径生成

系统会根据模板类型自动生成默认目标路径：

  • 页面模板: app/{templateId}
  • 组件模板: components/ui/{templateId}
  • 其他类型: ./{templateId}

CLI工具会自动使用这些路径作为默认值，无需手动维护。

添加新模板

  1. 创建模板目录

    templates/
├── components/          # 组件模板
│   └── YourComponent/
│       ├── config.json  # 配置文件
│       ├── index.tsx    # 组件代码
│       └── example.tsx  # 预览示例（可选）
└── pages/              # 页面模板
    └── YourPage/
        ├── config.json  # 配置文件
        ├── page.tsx     # 页面代码
        ├── form.tsx     # 其他文件
        └── example.tsx  # 预览示例（可选）

  2. 创建配置文件 (config.json)

    {
  "id": "YourComponent",
  "name": "组件显示名称",
  "description": "组件的详细描述"
}

  3. 创建预览示例文件 (example.tsx) - 可选

    对于 Modal、Drawer、Popover 等需要特殊交互的组件，建议创建 example.tsx 文件：

    import React, { useState } from 'react';
import { Button, Card, Typography } from 'antd';
import YourComponent from './index';

const { Title, Paragraph } = Typography;

const Example: React.FC = () => {
    const [visible, setVisible] = useState(false);

    return (
        <div style={{ padding: '24px' }}>
            <Card>
                <Title level={3}>组件名称</Title>
                <Paragraph>组件功能说明</Paragraph>
                
                <Button onClick={() => setVisible(true)}>
                    打开组件
                </Button>
            </Card>

            <YourComponent
                visible={visible}
                onCancel={() => setVisible(false)}
            />
        </div>
    );
};

export default Example;

  4. 自动更新 (如果使用 dev:watch 模式)

    • 保存文件后配置会自动更新
    • 预览界面会自动刷新

  5. 手动更新 (如果需要)

    npm run generate-config

配置文件格式

每个模板的 config.json 文件包含以下字段：

{
  "id": "模板唯一标识符",
  "name": "模板显示名称", 
  "description": "模板的详细描述"
}

其他信息（category、path、files、language）由脚本自动生成。

自动化特性

🔍 文件监听

  • 自动监听 templates/ 目录下的所有文件变化
  • 支持 .tsx、.ts、.json 文件类型
  • 防抖处理，避免频繁触发
  • 实时更新配置文件

📦 智能导入

  • 基于生成的配置自动创建导入映射
  • 支持精确路径匹配和模糊匹配
  • 错误处理和调试信息
  • 无需手动维护导入代码

🎭 示例文件系统 (example.tsx)

本项目支持为模板创建专门的预览示例文件，特别适用于需要特殊交互的组件：

工作机制：

  • 有示例文件时: 预览系统优先使用 example.tsx 进行渲染
  • 无示例文件时: 预览系统直接渲染主组件文件 (index.tsx 或 page.tsx)
  • CLI 工具: example.tsx 文件不会被复制到业务项目中
  • 配置生成: example.tsx 文件不会出现在 staticTemplateConfigs 中

适用场景：

  • Modal、Drawer、Popover 等弹窗组件
  • 需要特定状态或数据的组件
  • 需要展示多种用法的组件
  • 需要提供使用说明的复杂组件

文件结构示例：

templates/components/ChangePasswordModal/
├── config.json      # 组件配置
├── index.tsx        # 主组件文件（会被复制到业务项目）
└── example.tsx      # 预览示例（仅用于预览，不会被复制）

示例文件模板：

import React, { useState } from 'react';
import { Button, Card, Typography } from 'antd';
import YourModal from './index';

const Example: React.FC = () => {
    const [visible, setVisible] = useState(false);

    return (
        <div style={{ padding: '24px' }}>
            <Card>
                <Typography.Title level={3}>组件演示</Typography.Title>
                <Typography.Paragraph>
                    组件功能说明和使用指南
                </Typography.Paragraph>
                
                <Button onClick={() => setVisible(true)}>
                    打开模态框
                </Button>
            </Card>

            <YourModal
                visible={visible}
                onCancel={() => setVisible(false)}
            />
        </div>
    );
};

export default Example;

目前可用的模板

页面模板

  • login: 完整的登录页面，包含账号密码和手机号登录
  • account-settings: 用户账户设置页面，包含基本信息展示和头像上传功能（有示例文件）
  • user-management: 用户管理页面，包含用户列表、添加、编辑、删除等功能
  • role-management: 角色管理页面，包含角色权限配置
  • organization-structure: 组织架构管理页面
  • position-management: 岗位管理页面

组件模板

  • MyButton: 基于 Ant Design 的自定义按钮组件
  • ChangePasswordModal: 修改密码弹窗组件，包含完整的密码验证逻辑（有示例文件）

CLI 高级功能

智能模板匹配

CLI 工具支持智能模板匹配，可以通过以下方式使用：

# 精确匹配
npx mes-ui add account-settings

# 模糊匹配（支持部分名称）
npx mes-ui add account    # 匹配 account-settings
npx mes-ui add user       # 匹配 user-management

# 如果匹配到多个结果，会显示选择列表
npx mes-ui add management # 显示所有包含 management 的模板

批量操作

支持一次性添加多个模板：

# 批量添加多个模板
npx mes-ui add account-settings user-management role-management

# 自动合并依赖，避免重复安装
# 显示进度信息和操作状态

智能默认命名

CLI 工具会根据模板 ID 自动生成有意义的默认名称：

  • account-settings → AccountSettings
  • user-management → UserManagement
  • organization-structure → OrganizationStructure
  • login → Login

版本控制系统

基于内容哈希的可靠版本控制：

# 检查模板更新
npx mes-ui check-updates

# 提供四种处理方式：
# 1. 查看详细差异
# 2. 批量更新所有模板
# 3. 更新版本记录（不修改代码）
# 4. 取消操作

版本控制特点：

  • 使用 SHA-256 算法计算模板内容哈希
  • 基于实际内容变化，不受文件修改时间影响
  • 精确比较，避免误判
  • 支持批量更新和选择性更新

预览功能

预览界面提供以下功能：

  1. 模板列表: 左侧显示所有可用模板，按组件/页面分类
  2. 实时预览: 右侧实时渲染选中的模板效果
  3. 代码查看: 可以切换到代码视图查看模板源码，支持语法高亮
  4. 设备切换: 支持桌面、平板、手机三种预览尺寸
  5. 响应式设计: 界面自适应不同屏幕尺寸
  6. 热更新: 支持模板文件修改后自动刷新
  7. 搜索功能: 支持模板名称和描述搜索，带防抖优化
  8. 懒加载: 模板内容按需加载，提升首屏性能

开发指南

目录结构

mes-frontend-shared-modules/
├── bin/                    # CLI 工具
├── templates/              # 模板文件
│   ├── components/         # 组件模板
│   │   └── MyButton/
│   │       ├── config.json
│   │       └── index.tsx
│   └── pages/             # 页面模板
│       └── login-page/
│           ├── config.json
│           ├── page.tsx
│           └── form.tsx
├── preview-app/           # 预览应用
│   ├── src/
│   │   ├── components/    # 预览组件
│   │   └── utils/         # 工具函数
├── scripts/               # 构建脚本
│   ├── generate-template-config.js
│   └── watch-templates.js
└── utils/                 # 通用工具

推荐工作流程

  1. 开发模式启动

    npm run dev:watch

  2. 创建新模板

    • 在 templates/ 下创建模板目录和文件
    • 添加 config.json 配置文件
    • 保存后自动更新配置

  3. 实时预览

    • 在浏览器中查看模板效果
    • 修改模板文件后自动刷新

  4. 发布使用

    • 在业务项目中使用 mes-ui add 添加模板

高级功能

自定义监听

如果需要自定义监听规则，可以修改 scripts/watch-templates.js：

// 自定义文件过滤规则
if (filename && 
    !filename.startsWith('.') && 
    !filename.includes('node_modules') &&
    (filename.endsWith('.tsx') || 
     filename.endsWith('.ts') || 
     filename.endsWith('.json'))) {
  // 处理文件变化
}

自定义导入逻辑

如果需要特殊的导入处理，可以修改 preview-app/src/utils/templateLoader.ts 中的 createImportMap 函数。

MCP 集成 (AI 工具支持)

MES UI 现在支持作为 MCP (Model Context Protocol) 服务器运行，让 Cursor 等 AI 工具可以直接调用模板生成功能。

快速配置

在 Cursor 的 ~/.cursor/mcp.json 中添加：

{
  "mcpServers": {
    "mes-ui": {
      "command": "npx",
      "args": ["mes-ui", "mcp-server"],
      "timeout": 600
    }
  }
}

可用功能

  • 智能模板推荐: AI 根据需求推荐合适的模板
  • 批量生成: 一次性生成多个相关模板
  • 自动依赖管理: 智能处理依赖关系
  • 版本更新检查: AI 协助维护模板版本

详细配置和使用说明请参考 MCP_INTEGRATION.md

技术栈

  • 构建工具: Vite
  • UI框架: React + Ant Design + Ant Design Pro Components
  • 语言: TypeScript
  • CLI 工具: Node.js + Inquirer
  • 配置管理: 自动化脚本生成
  • 文件监听: Node.js fs.watch API
  • 并发执行: concurrently
  • 代码高亮: react-syntax-highlighter
  • 版本控制: SHA-256 内容哈希
  • 性能优化: 懒加载、防抖、缓存
  • AI 集成: MCP (Model Context Protocol)

许可证

MIT

Readme

Keywords

Package Sidebar

Install

npm i mes-ui

Weekly Downloads

15

Version

1.1.10

License

MIT

Unpacked Size

205 kB

Total Files

34

Last publish

Collaborators

  • xuanhe
Try on RunKit
Report malware