@jqms/components_lib

@jqms/components_lib

JQMS 可复用 Vue 3 组件库。适用于已有 Vue 3 + Element Plus + vue-i18n 业务系统，通过插件注入宿主能力（多语言、用户信息、字典、业务 API 等），按需使用组件。

当前 npm 版本以 registry 为准（仓库内 package.json 为 1.1.0）；需配合 @jqms/system_service 与 @jqms/utils 兼容版本。

目录

• 环境要求
• 安装
• 接入步骤（推荐）
• 插件配置说明
• 与 @jqms/system_service 配合
• 样式接入
• 多语言接入
• 组件清单
• 按需引入
• 宿主侧额外准备
• TypeScript
• 业务应用接入（npm）
• 仓库内开发联调
• 常见问题
• 维护者：构建与发布

环境要求

组件库通过 @jqms/system_service 发起业务请求，宿主只需安装并配合配置插件（i18n、用户、字典、URL 等）。

安装

# npm
npm install @jqms/components_lib

# pnpm
pnpm add @jqms/components_lib

# yarn
yarn add @jqms/components_lib

同时安装 peer 依赖（若项目尚未具备）：

pnpm add vue element-plus vue-i18n vue-router @element-plus/icons-vue \
  echarts dayjs lodash-es fuse.js file-saver xlsx-js-style \
  @wangeditor/editor @wangeditor/editor-for-vue \
  @vueuse/core @jqms/utils @jqms/system_service

接入步骤（推荐）

在宿主应用中按以下顺序完成接入。以 Vite + Vue 3 为例。

1. 引入样式

打包后组件样式在独立 CSS 中，必须手动导入，否则会出现尺寸/间距丢失等问题（例如 SvgIcon 变回默认大小）。

// main.ts
import '@jqms/components_lib/style.css'

2. 合并组件库多语言

请从 独立子入口 @jqms/components_lib/i18n 导入，不要从主入口导入 i18n helper，以避免初始化时加载完整组件包并触发 TDZ 错误。

内置语言：zh-cn、zh-tw、en。文案统一挂在 jqmsComponents.* 命名空间下，不会覆盖宿主已有的 btn、toast 等顶级 key。

// i18n/index.ts
import { createI18n } from 'vue-i18n'
import { mergeJqmsComponentsLocales } from '@jqms/components_lib/i18n'

const i18n = createI18n({
  legacy: false,
  globalInjection: true,
  locale: 'zh-cn',
  fallbackLocale: 'zh-cn',
  messages: {
    'zh-cn': { /* 宿主文案 */ },
    'zh-tw': { /* 宿主文案 */ },
    en: { /* 宿主文案 */ }
  }
})

// 在 createI18n 之后、远程语言加载之前合并
mergeJqmsComponentsLocales((locale, messages) => {
  i18n.global.mergeLocaleMessage(locale, messages)
})

export default i18n

3. 注册插件与图标

在 ElementPlus 和 vue-i18n 之后安装组件库插件：

// main.ts
import { createApp } from 'vue'
import ElementPlus from 'element-plus'
import 'element-plus/dist/index.css'
import '@jqms/components_lib/style.css'
import {
  createJqmsComponentsPlugin,
  elementIcons,
  registerJqmsChartThemes
} from '@jqms/components_lib'
import vueI18n from './i18n'
import App from './App.vue'

const app = createApp(App)

// 可选：注册 ECharts 主题
registerJqmsChartThemes()

app
  .use(ElementPlus)
  .use(elementIcons) // 注册 Element Plus Icons，供 SvgIcon 的 ele-* 名称使用
  .use(vueI18n)
  .use(
    createJqmsComponentsPlugin({
      t: vueI18n.global.t,
      getLanguage: () => 'zh-cn',
      setLanguage: (language) => {
        // 切换宿主语言
      },
      showLoading: (message) => {
        // 可选：全局 loading
      },
      getCurrentUser: () => ({
        // 返回当前登录用户对象
      }),
      getSideTheme: () => 'theme-dark',
      getIndustrialMode: () => false,
      getDictionary: () => ({
        getDictsFun: (/* ... */) => {},
        getComputedDict: (/* ... */) => {},
        getDictLabel: (/* ... */) => {}
      }),
      k2ServiceUrl: import.meta.env.VITE_APP_K2_SERVICE,
      uploadUrl: import.meta.env.VITE_APP_BASE_API + import.meta.env.VITE_APP_UPLOAD_URL
    })
  )
  .mount('#app')

安装后，注册表中的组件会全局注册，可直接在模板中使用，例如 <UserPicker />、<Pagination />。

插件配置说明

createJqmsComponentsPlugin(options) 的 options 类型为 JqmsComponentsOptions：

字典适配器 getDictionary()

需返回：

interface JqmsDictionaryAdapter {
  getDictsFun: (...args: any[]) => any
  getComputedDict: (...args: any[]) => any
  getDictLabel: (...args: any[]) => any
}

JqmsDictSelect 通过该适配器读取字典数据。

与 @jqms/system_service 配合

组件库内部通过 @jqms/system_service 调用业务 HTTP，不再需要宿主注入 services。

业务应用也可直接 import 这些 service，与组件库共享同一实现。

样式接入

发布包导出：

@jqms/components_lib/style.css  →  dist/style.css

import '@jqms/components_lib/style.css'

说明：

• dist（npm 包）模式：SFC 样式已提取到该 CSS，必须手动 import。
• source（本地联调）模式：该入口指向占位 CSS，实际样式由 Vite 编译 .vue 时注入；仍建议保留同一行 import，方便日后切到 npm 包。

多语言接入

为什么要用 /i18n 子入口？

// ✅ 正确：轻量入口，只含 locale + merge helper
import { mergeJqmsComponentsLocales } from '@jqms/components_lib/i18n'

// ❌ 不推荐：从主入口引入会拉起整个组件包，可能引发初始化时序问题
import { mergeJqmsComponentsLocales } from '@jqms/components_lib'

命名空间

组件内文案 key 形如：

jqmsComponents.btn.search
jqmsComponents.user.selectUser
jqmsComponents.arTask.flowHistory
...

宿主侧若要覆盖组件库文案，在自身 locale 中按同样路径覆盖即可。

合并时机

1. createI18n(...)
2. mergeJqmsComponentsLocales(...)
3. （可选）再加载远程/服务端语言包

这样远程文案可以覆盖组件库默认文案，而组件库不会误覆盖宿主无关顶级 key。

组件清单

插件安装后全局注册以下组件（名称与 PascalCase 一致）：

同名 Element 增强组件会在插件安装时覆盖 Element Plus 的全局组件名。若宿主不需要增强行为，可改为按需引入其它组件，或自行评估是否全局注册这些包装组件。

按需引入

除全局插件外，也可以从主入口按名导入：

<script setup lang="ts">
import { Pagination, UserPicker, SvgIcon } from '@jqms/components_lib'
</script>

<template>
  <UserPicker v-model="userIds" />
  <Pagination v-model:page="page" v-model:limit="limit" :total="total" />
</template>

即使按需引入单个组件，仍建议：

1. 导入 style.css
2. 合并 i18n
3. 调用 createJqmsComponentsPlugin（或至少 installJqmsComponentsConfig）注入配置，否则依赖 getJqmsComponentsConfig() 的组件会报错。

其它导出示例：

import {
  createJqmsComponentsPlugin,
  elementIcons,
  registerJqmsChartThemes,
  jqmsComponents,
  getJqmsComponentsConfig,
  useJqmsComponentsConfig
} from '@jqms/components_lib'

宿主侧额外准备

SvgIcon

• name 以 ele- 开头：解析为 Element Plus Icons（需先 app.use(elementIcons)）。
• 其它名称：使用 SVG sprite，引用 #icon-${name}。宿主需自行注册 SVG sprite（例如 vite-plugin-svg-icons 的 virtual:svg-icons-register），并保证图标 id 前缀为 icon-。

上传相关

注入 uploadUrl，并保证请求头鉴权可用（组件内部会通过 @jqms/utils 的 token 能力读取登录态）。

图表主题

import { registerJqmsChartThemes } from '@jqms/components_lib'
registerJqmsChartThemes()

TypeScript

包内已提供类型声明：

• 主入口：@jqms/components_lib → types/index.d.ts
• i18n：@jqms/components_lib/i18n → types/i18n.d.ts

安装插件后，全局组件类型会通过 vue 的 GlobalComponents 扩展。若 IDE 未识别，确认 tsconfig 能解析到包的 types 字段，并重启 TS 服务。

业务应用接入（npm）

业务项目通过 npm 安装已发布版本（推荐）：

{
  "dependencies": {
    "@jqms/components_lib": "^1.1.0",
    "@jqms/system_service": "^1.0.0",
    "@jqms/utils": "^1.0.2"
  }
}

安装 peer 依赖后按本文「接入步骤」配置即可，无需 clone 基础设施仓库或将本包作为 workspace 成员。

仓库内开发联调

本仓库为 前端基础设施管理仓库，packages/jqms_components_lib 为组件库源码。维护者在仓库内开发时可切换 source / dist：

# 指向 src（本地热更新）
pnpm -C packages/jqms_components_lib use:source

# 指向 dist（模拟发布产物）
pnpm -C packages/jqms_components_lib build
pnpm -C packages/jqms_components_lib use:dist

查看当前模式：

pnpm -C packages/jqms_components_lib mode

切换到 dist 后，若 Vite 仍加载旧预构建缓存，请强制重建：

pnpm exec vite --force

常见问题

1. 组件尺寸/间距异常（如图标变大）

未导入样式：

import '@jqms/components_lib/style.css'

2. Cannot access 'xxx' before initialization（i18n 初始化）

从主入口导入了 mergeJqmsComponentsLocales。请改为：

import { mergeJqmsComponentsLocales } from '@jqms/components_lib/i18n'

3. 请求失败 / 接口 404

确认宿主已安装 @jqms/system_service（与组件库 peer 版本兼容），且后端提供对应 API（如 /system/user/list、/mdplantcustomer/list 等）。

4. @jqms/components_lib has not been configured

未调用 createJqmsComponentsPlugin(options)，或在插件安装前就渲染了依赖配置的组件。

5. ElDropdown 递归更新 / TSX 行为异常（仅 dist）

组件库构建必须启用 @vitejs/plugin-vue-jsx。已发布包已包含正确构建配置；若自行 fork 构建，请确认 Vite 插件包含 Vue JSX。

6. 业务项目应使用 npm 版本而非仓库路径

检查业务项目 package.json：

1. 依赖应为 semver 版本号（如 ^1.1.0），而非 workspace:^ 或 file:
2. node_modules/@jqms/components_lib 应来自 npm registry，而非指向本基础设施仓库

维护者：构建与发布

cd packages/jqms_components_lib

# 构建主包 + 独立 i18n 入口
pnpm build

# 发布前会自动：build → use:dist
pnpm publish

# 发布后会自动切回 source

构建产物：

dist 目录建议加入 .gitignore，由 prepublishOnly 在发布时生成，不必提交到 Git。

导出子路径一览

完整最小示例

// main.ts
import { createApp } from 'vue'
import { createI18n } from 'vue-i18n'
import ElementPlus from 'element-plus'
import 'element-plus/dist/index.css'
import '@jqms/components_lib/style.css'
import {
  createJqmsComponentsPlugin,
  elementIcons,
  registerJqmsChartThemes
} from '@jqms/components_lib'
import { mergeJqmsComponentsLocales } from '@jqms/components_lib/i18n'
import App from './App.vue'

const i18n = createI18n({
  legacy: false,
  locale: 'zh-cn',
  fallbackLocale: 'zh-cn',
  messages: { 'zh-cn': {}, 'zh-tw': {}, en: {} }
})
mergeJqmsComponentsLocales((locale, messages) => {
  i18n.global.mergeLocaleMessage(locale, messages)
})

const app = createApp(App)
registerJqmsChartThemes()

app.use(ElementPlus).use(elementIcons).use(i18n).use(
  createJqmsComponentsPlugin({
    t: i18n.global.t,
    getLanguage: () => String(i18n.global.locale.value),
    getCurrentUser: () => ({}),
    getSideTheme: () => 'theme-light',
    getIndustrialMode: () => false,
    getDictionary: () => ({
      getDictsFun: () => [],
      getComputedDict: () => [],
      getDictLabel: () => ''
    }),
    k2ServiceUrl: import.meta.env.VITE_APP_K2_SERVICE,
    uploadUrl: import.meta.env.VITE_APP_BASE_API + import.meta.env.VITE_APP_UPLOAD_URL
  })
)

app.mount('#app')

按上述步骤完成后，即可在页面中使用组件库提供的业务组件。若接入过程中遇到具体组件 props / 事件问题，可直接查看 src/components 下对应源码或联系组件库维护者。