kantboot-frame-vue

Kantboot Vue 前端基础框架包，提供 Kantboot 项目常用的工具库、全局组件、主题样式、请求配置和自动路由接入能力。

这个包主要服务于 Kantboot 体系内部项目，不是一个完全按公开通用组件库标准整理出来的包。它承载了多个业务后台长期复用下来的组件、工具和约定，所以内部会存在一些历史包袱、命名不够统一、职责边界不够清晰的地方。

当前阶段优先保证 Kantboot 体系内各个 vue-admin 项目可以稳定复用，并逐步向普通 npm 包的使用方式靠拢。开发阶段可以继续使用 file: 本地依赖，后续发布到 npm 后也可以直接切换为版本号依赖。

如果你不是在 Kantboot 体系内使用这个包，需要注意：很多能力默认依赖 Kantboot 的接口约定、目录结构、请求配置、样式变量和后台页面组织方式，直接用于其他项目可能需要额外适配。

安装

本地开发阶段：

{
  "dependencies": {
    "kantboot-frame-vue": "file:D:/code/kantboot-frame-java/kantboot-frame-vue"
  }
}

发布到 npm 后：

{
  "dependencies": {
    "kantboot-frame-vue": "^0.0.1"
  }
}

业务项目还需要安装这些基础依赖：

npm install vue vue-router element-plus axios markdown-it tinycolor2 highlight.js

使用

在业务项目的 src/main.js 中引入：

import { createApp } from 'vue';
import App from './App.vue';
import elementPlus from 'element-plus';
import $kt from 'kantboot-frame-vue';
import './root.css';

const pages = import.meta.glob('/src/pages/**/page.vue', { eager: true });

async function initApp() {
  const response = await fetch('/config.json');
  const resData = await response.json();

  $kt.request.config.rootAddress = resData.request.config.rootAddress;
  $kt.request.config.websocketAddress = resData.request.config.websocketAddress;
  $kt.request.config.fileAddress = resData.request.config.fileAddress;
  $kt.request.config.uploadAddress = resData.request.config.uploadAddress;
  $kt.request.config.staticAddress = resData.request.config.staticAddress;

  createApp(App)
    .use(elementPlus)
    .use($kt, { router: { pages } })
    .mount('#app');
}

initApp();

自动路由

业务项目负责收集自己的页面文件：

const pages = import.meta.glob('/src/pages/**/page.vue', { eager: true });

然后在安装框架时传给 $kt：

.use($kt, { router: { pages } })

框架会把 /src/pages/**/page.vue 转成路由：

• /src/pages/page.vue -> /
• /src/pages/admin/page.vue -> /admin
• /src/pages/admin/user/page.vue -> /admin/user

这样做的原因是：kantboot-frame-vue 作为 npm 包时，包内部不能可靠扫描业务项目的 /src/pages，所以页面扫描必须放在业务项目侧执行。

Vite 配置建议

业务项目使用本地 file: 依赖时，建议在 vite.config.js 中配置：

import { createLogger, defineConfig } from 'vite';
import vue from '@vitejs/plugin-vue';

const customLogger = createLogger();
const warnOnce = customLogger.warnOnce;

customLogger.warnOnce = (msg, options) => {
  if (/Sourcemap for .*node_modules[\\/]entities[\\/].* points to missing source files/.test(msg)) {
    return;
  }

  warnOnce(msg, options);
};

export default defineConfig({
  customLogger,
  plugins: [vue()],
  optimizeDeps: {
    exclude: ['kantboot-frame-vue'],
  },
  resolve: {
    preserveSymlinks: true,
  },
});

optimizeDeps.exclude 可以避免 Vite 把本地框架包预构建成旧缓存。修改框架源码后，如果页面没有更新，重启 dev server 并加 --force：

npm run dev -- --force

全局对象

安装后可以通过组件实例访问：

this.$kt
this.$request
this.$i18n

也可以直接从模块默认导入对象中使用：

import $kt from 'kantboot-frame-vue';

$kt.request.config.rootAddress = 'http://localhost:8080';

常用能力

默认导出的 $kt 包含：

• date
• dataChange
• enums
• event
• file
• i18n
• math
• request
• router
• storage
• style
• userAccount
• util

全局组件

安装 $kt 后会注册常用组件，包括：

• KtButton
• KtButtonGroup
• kt-icon
• KtRow
• KtCol
• KtDateInput
• KtPagination
• KtMarkdown
• KtRouterView
• KtInput
• KtSwitch
• KtMenu
• KtMenuItem
• KtSubMenu
• KtMenuItemGroup
• KtPopover
• KtTable
• KtTableColumn
• KtProgress
• KtDialog
• KtTooltip
• KtContainer
• KtImage
• KtPopup
• KtAdminTable
• KtSelect
• KtTip
• KtLoading
• KtUploadImage
• KtFormat
• KtUserAccountSelect

样式

框架入口会自动引入：

import './style.css';
import 'element-plus/dist/index.css';
import './element-plus.css';

业务项目通常只需要继续维护自己的 root.css 或页面样式。

本地开发

框架包自身提供 Sass 监听脚本：

cd kantboot-frame-vue
npm run dev

业务项目运行：

cd project/project-lxyz/vue-admin
npm run dev -- --force

发布前检查

发布前建议执行：

npm pack --dry-run

确认包中包含：

• index.js
• components
• libs
• style.css
• element-plus.css
• tags.json
• web-types.json
• package.json

注意事项

• 这个包主要给 Kantboot 体系内部使用，优先兼容内部项目现状，而不是优先追求外部通用性。
• 包内组件和工具来自多个项目的长期沉淀，短期内可能会有一些混乱，例如命名风格不完全一致、部分组件职责偏重业务、部分工具 API 暴露较宽。
• 后续会逐步整理边界，但在整理完成前，业务项目升级时建议先跑本项目的 vue-admin 构建和页面验证。
• 自动路由扫描必须写在业务项目中，不要写回框架包内部。
• 本地 file: 依赖修改后，Vite 可能有缓存，优先使用 npm run dev -- --force。
• 如果未来发布 npm 包，业务项目只需要把 file: 改成版本号依赖，main.js 的引入方式不需要变。
• KtMarkdown 当前不在启动阶段依赖 highlight.js 的 JS 运行时代码，避免不同打包方式下因为 CommonJS/ESM 兼容问题导致白屏。