Appearance
版本兼容矩阵
Lingxi UI 面向 Vue3 组件库，同时提供 Vue2.6 存量系统的 SDK 挂载方式。下表记录当前仓库验证过的基线和接入约束。
运行时矩阵
| 环境 | 当前验证版本 | 要求 | 说明 |
|---|---|---|---|
| Vue2 host | vue@2.6.14 | Vue2 页面不能直接渲染 Vue3 组件 | 使用 @zhiyongui/lingxi-ui/sdk 挂载到 DOM 容器。 |
| Vue3 runtime | vue@3.5.x | >=3.5.0 | 组件内部使用 Vue3 app、组合式 API 和 defineExpose。 |
| Element Plus | 2.14.x | 随包依赖 | 基础 UI 和 Element Plus X 包装组件依赖它。 |
| vue-element-plus-x | 1.3.98 | 随包依赖 | 聊天、输入、气泡、附件等基础 AI 组件依赖它。 |
| VitePress docs | 1.6.x | 文档站验证环境 | 文档示例和生产构建以 npm.cmd run docs:build 为准。 |
可选能力依赖
| 能力 | 依赖 | 安装时机 | 对应入口 |
|---|---|---|---|
| PDF 预览 | pdfjs-dist | 使用 AiFilePreview 的 PDF.js provider 时安装 | @zhiyongui/lingxi-ui/ai-file-preview |
| ECharts 图表 | echarts | 使用 AiRichContent chart block 时安装 | @zhiyongui/lingxi-ui/ai-rich-content |
| 知识图谱 | @antv/g6 | 使用 AiKnowledgeGraph 或 graph block 时安装 | @zhiyongui/lingxi-ui/ai-knowledge-graph |
| 脑图 | mind-elixir | 使用 AiMindMap 或 mindmap block 时安装 | @zhiyongui/lingxi-ui/ai-mind-map |
| 表格编辑 | vxe-table、vxe-pc-ui、@vxe-ui/core | 使用 AiExcelEditor 或 excel block 时安装 | @zhiyongui/lingxi-ui/ai-excel-editor |
接入建议
| 场景 | 推荐入口 | 样式入口 | 说明 |
|---|---|---|---|
| Vue3 工程化项目 | ESM 按需子路径 | @zhiyongui/lingxi-ui/<entry>/style.css | 首选方式，利于 tree-shaking 和按需加载。 |
| Vue2 只接入基础聊天 | lingxi-chat.iife.js | lingxi-chat.css | 避免把 PDF、图谱、脑图、表格打进普通聊天页。 |
| Vue2 接入文件预览 | lingxi-file-preview.iife.js | lingxi-file-preview.css | PDF 能力仍需要保证 PDF 运行时资源可用。 |
| Vue2 接入富内容/可视化 | lingxi-visualization.iife.js | lingxi-visualization.css | 包体较大，适合可视化工作台，不建议作为全站默认资源。 |
| 需要所有能力 | lingxi-ui.iife.js 或全量 ESM | lingxi-ui.css | 兼容入口，包体最大。 |
Vue2 生命周期规则
- 页面销毁时必须调用
instance.unmount()，否则 Vue3 app、事件监听和异步任务会残留。 - Vue2 数据变化后必须调用
instance.update(nextProps)，不要只修改 Vue2 data。 - Vue3 事件以
onXxxprops 传入；update:modelValue使用'onUpdate:modelValue'。 - 调用 Vue3 暴露方法时使用
instance.callMethod(name, ...args)。 - 不要在同一个 DOM 容器重复 mount；重新挂载前先 unmount。
验证命令
bash
npm.cmd run typecheck
npm.cmd -w packages/lingxi-ui run test
npm.cmd run build
npm.cmd run docs:build