djm-ui

DJM UI

面向企业级中后台的 Vue 3 组件库：100 个组件、明暗主题与品牌色、中英文文案、按钮权限，自带完整文档与无障碍校验。

• 官网与文档：https://ui.duojumi.com
• npm：https://www.npmjs.com/package/djm-ui

环境要求

• Vue 3.4+
• 现代浏览器：Chrome / Edge / Firefox / Safari 最近两个大版本（不支持 IE）
• 组件在挂载后访问 DOM，SSR 场景需在客户端调用 initTheme()，服务端只渲染结构

安装

npm i djm-ui

使用

全量注册

import { createApp } from 'vue'
import DjmUI from 'djm-ui'
import 'djm-ui/styles'
import App from './App.js'

createApp(App)
  .use(DjmUI, { locale: 'zh-CN' })
  .mount('#app')

.use(DjmUI, options) 会注册全部组件与 v-permission 指令，options.locale 可省略，默认中文。

按需引入

ESM 产物支持 tree-shaking，按名字引入即可，未使用的组件不会进入打包结果：

import { DjmButton, DjmTable } from 'djm-ui'
import 'djm-ui/styles'

只要部分组件样式时，按依赖顺序引入基础样式与组件样式：

import 'djm-ui/styles/tokens.css'          // 设计变量
import 'djm-ui/styles/theme-dark.css'      // 暗色主题
import 'djm-ui/styles/base.css'            // 基础重置与工具类
import 'djm-ui/styles/components/button.css'
import 'djm-ui/styles/components/motion.css' // 弹窗、抽屉等过渡动画

模板编译与 CSP

组件用运行时模板编写，需要带编译器的 Vue 构建；npm 里的 vue 默认是 runtime-only，打包时指向完整版：

// vite.config.js
export default {
  resolve: { alias: { vue: 'vue/dist/vue.esm-bundler.js' } }
}

运行时编译依赖 new Function，严格 CSP（script-src 不含 'unsafe-eval'）下会直接报错，需要先放开 'unsafe-eval'；预编译产物在规划中。

栅格

DJM UI 的栅格由 Row / Col 两部分组成，按需引入走各自路径：

import DjmRow from 'djm-ui/components/grid/row'
import DjmCol from 'djm-ui/components/grid/col'

CDN

UMD 产物复用全局 Vue，不会重复打包 Vue。Vue 必须先加载。

下面用 fastly.jsdelivr.net（jsDelivr 官方镜像）；国内访问 cdn.jsdelivr.net 常被拦截，换成 unpkg.com 或 gcore.jsdelivr.net 同理：

<link rel="stylesheet" href="https://fastly.jsdelivr.net/npm/djm-ui@0.74.2/dist/djm-ui.min.css" />
<script src="https://fastly.jsdelivr.net/npm/vue@3/dist/vue.global.prod.js"></script>
<script src="https://fastly.jsdelivr.net/npm/djm-ui@0.74.2/dist/djm-ui.umd.min.js"></script>

<script>
  Vue.createApp({
    template: '<DjmButton variant="primary">按钮</DjmButton>'
  }).use(DjmUI).mount('#app')
</script>

后台模板

需要开箱即用的后台壳（侧边 / 顶部通栏 / 混合 / 双列、页签、用户菜单、皮肤面板、窄屏抽屉）和页面范式时，安装配套模板包：

npm i djm-ui-admin

模板自带登录、个人中心、修改密码、账号设置、异常页，以及用户 / 部门 / 数据字典 / 文件四个业务页，统一走 api 适配层注入数据，不含演示数据。详见 admin/README.md 与文档站「Admin 后台模板」。

响应式

组件按容器宽度自适应，不依赖具体业务布局，断点与行为如下：

组件自身的窄屏处理：

• 表格、周日程、甘特图、看板在容器内横向滚动，不把页面撑宽
• 下拉、日期、颜色、树选择等浮层按视口自动向上翻转并限制在视口内，超高时面板内部滚动
• 图标类按钮（清空、关闭、展开）在手机端扩大透明点击区，文字操作按钮补充高度
• 动态字段、导入向导、批量操作条等复合组件在手机上改为单列排布

主题与主色

import { initTheme, toggleTheme, setPrimaryColor, resetPrimaryColor, PRESET_COLORS } from 'djm-ui'

initTheme()                 // 启动时恢复上次选择
toggleTheme()               // light / dark
setPrimaryColor('#12855a')  // 自定义主色，自动推导整套色阶
resetPrimaryColor()         // 回到默认蓝

外观与导航

示例应用右上角「皮肤」面板可以自由组合，选择写入 localStorage，刷新后保留：

侧栏单独配色时会按当前主色重新推导一套色阶，换主色侧栏同步变化。空间不够时自动降级：≤1320px 混合布局收起顶部一级菜单改抽屉，≤1100px 双列菜单退回单列，≤960px 统一变成抽屉。

AI 助手（MCP）

组件库内置 MCP（Model Context Protocol）服务，AI 编程助手可以在写页面前查询当前版本的组件清单、props、事件、插槽、示例与 DSL：

npm i -D djm-ui
npx djm-ui-mcp

在 Cursor / Trae / Claude Code 的 MCP 配置里加入：

{
  "mcpServers": {
    "djm-ui": { "command": "npx", "args": ["djm-ui-mcp"] }
  }
}

提供 8 个工具：get_component_list、get_component_doc、get_component_props、search_components、get_component_examples、get_component_dsl、get_installation_guide、get_library_info。

manifest 在每次构建时由文档页生成，随包版本发布；npm test 校验数据完整性，npm run test:mcp 校验 stdio 服务与工具调用。

国际化

import { setLocale, localeState, t } from 'djm-ui'

setLocale('en-US')
localeState.code          // 当前语言
t('table.empty')          // 取文案，支持 t('diff.expand', { count: 12 })

按钮权限

import { setPermissions } from 'djm-ui'

setPermissions(['user:add', 'user:edit'])

<DjmButton v-permission="'user:add'">新增用户</DjmButton>
<DjmButton v-permission.disable="['user:export']">导出</DjmButton>

没有权限时元素被移除；加 .disable 修饰符则只禁用置灰。界面显隐不能替代服务端校验。

构建产物

本地开发

npm run dev        # 官网 http://localhost:5180（首页落地页，/app/ 示例应用，/docs/ 文档，/admin/ 模板介绍）
npm run docs       # 文档站 http://localhost:5181
npm run dev:admin  # 后台模板 demo（admin/demo，Vite）
npm test           # 语法 + 模板编译 + 类名命名空间 + 组件一致性审计
npm run typecheck  # 类型声明校验
npm run build      # 构建样式与 ESM / CJS / UMD
npm run visual     # 视觉回归

官网部署

官网跑在 ui.duojumi.com，宝塔静态站点，目录 /www/wwwroot/ui.duojumi.com：

文档页依赖仓库里的 docs/、src/styles、vendor/ 保持相对路径，所以整块同步：

./scripts/deploy-docs.sh

脚本先删远端旧目录再整块解包，最后统一改成 www:www + 目录 755 / 文件 644，服务器上不用手工改文件。默认走 root@100.112.203.74 + ~/.ssh/jzjl_deploy，可用 DJM_DOCS_HOST / DJM_DOCS_KEY / DJM_DOCS_PATH 覆盖。Nginx 配置见 deploy/nginx/ui.duojumi.com.conf。

换一台机器

代码和脚本都在仓库里，凭据不进 git，换机器要单独带三样：

初始化顺序：

git clone https://yohan.cloud:8081/DJM/dimui.git
cd dimui && npm install

# 放私钥并收紧权限，缺了它部署脚本会直接报错
cp /path/to/jzjl_deploy ~/.ssh/ && chmod 600 ~/.ssh/jzjl_deploy

# 逐项验证
ssh -i ~/.ssh/jzjl_deploy root@100.112.203.74 hostname   # 能打印主机名即可
./scripts/deploy-docs.sh                                  # 部署一遍官网
npm whoami --registry=https://registry.npmjs.org           # 打印 shyohan 即可发布

注意：本机 npm 默认源是 npmmirror 镜像，npm publish 依赖 package.json 里的 publishConfig.registry 走官方源；npm whoami、npm view 这类命令要显式加 --registry=https://registry.npmjs.org，否则会报未登录。

发布

npm run release -- patch   # 或 minor / major / 1.2.3
npm publish                # 组件库
cd admin && npm publish    # 后台模板，与组件库同版本号

发布前需在 CHANGELOG.md 顶部补好对应版本段落，脚本会拒绝在没有更新说明时改版本号。release 会一起同步 src/index.js、落地页、README、快速开始、llms.txt 与 admin/package.json 的版本号。

许可

MIT