在 Vue 中集成

如果你正在寻找使用 Vue 组件作为自定义组件的方法，请参阅此处。

在集成 Univer 到 Vue 项目前，请确保你已经阅读了安装和基本使用章节，并了解 Vue 组件和生命周期钩子。

Vue 3.x

集成前须知

应避免对 Univer 和 FUniver 的实例进行代理，否则可能会引起不可预知的错误或性能问题。

集成步骤

在 onMounted 钩子中初始化 Univer
在 onBeforeUnmount 钩子中销毁 Univer

示例代码

Vue

<script lang="ts" setup>import type { Univer } from '@univerjs/presets'import { UniverSheetsCorePreset } from '@univerjs/preset-sheets-core'import UniverPresetSheetsCoreZhCN from '@univerjs/preset-sheets-core/locales/zh-CN'import { createUniver, LocaleType, mergeLocales } from '@univerjs/presets'import { onBeforeUnmount, onMounted, ref } from 'vue'import '@univerjs/preset-sheets-core/lib/index.css'const container = ref<HTMLElement | null>(null)let univerInstance: Univer | null = nullonMounted(() => {  const { univer, univerAPI } = createUniver({    locale: LocaleType.ZH_CN,    locales: {      [LocaleType.ZH_CN]: mergeLocales(        UniverPresetSheetsCoreZhCN,      ),    },    presets: [      UniverSheetsCorePreset({        container: container.value as HTMLElement,      }),    ],  })  univerAPI.createWorkbook({})  univerInstance = univer})onBeforeUnmount(() => {  univerInstance?.dispose()  univerInstance = null})</script><template>  <div ref="container" style="height: 600px" /></template>

Vue 2.x

已有 Vue 2 应用可以使用本节。示例验证环境为 Vue 2.7.16、Vite 6.3.6、@vitejs/plugin-vue2 2.3.3 与 Univer 1.4.0。新项目建议使用 Vue 3。

从空项目体验时，解压最小项目，运行 npm install 和 npm run dev，打开终端中的地址。示例界面为英文。已有 Vue 2 项目按下面步骤接入。

安装一致的依赖

Bash

npm install @univerjs/presets@1.4.0 @univerjs/preset-sheets-core@1.4.0 react@18.3.1 react-dom@18.3.1 rxjs@7.8.2

把组件加入页面

不要把 Univer 实例和 Facade 对象放入响应式 data。在容器已存在的 mounted 中创建编辑器，在 beforeDestroy 中调用 univer.dispose()；不要再通过 Facade 重复销毁同一实例。

Vue

<script>import { UniverSheetsCorePreset } from '@univerjs/preset-sheets-core'import UniverPresetSheetsCoreZhCN from '@univerjs/preset-sheets-core/locales/zh-CN'import { createUniver, LocaleType, mergeLocales } from '@univerjs/presets'import '@univerjs/preset-sheets-core/lib/index.css'export default {  mounted() {    const { univer, univerAPI } = createUniver({      locale: LocaleType.ZH_CN,      locales: {        [LocaleType.ZH_CN]: mergeLocales(          UniverPresetSheetsCoreZhCN,        ),      },      presets: [        UniverSheetsCorePreset({          container: this.$refs.container,        }),      ],    })    this.univerInstance = univer    this.univerAPI = univerAPI    const workbook = univerAPI.createWorkbook({})    workbook.getActiveSheet().getRange('A1:D3').setValues([      ['Item', 'Quantity', 'Unit price', 'Total'],      ['Notebook', 3, 12, '=B2*C2'],      ['Pen', 5, 2, '=B3*C3'],    ])  },  beforeDestroy() {    this.univerInstance?.dispose()    this.univerInstance = null    this.univerAPI = null  },}</script><template>  <div ref="container" style="height: 600px" /></template>

验证运行结果

第一行金额应为 36。把数量从 3 改为 4，确认金额更新为 48；再移除并重新挂载组件，检查编辑器能够正常销毁和重建。

初始化失败时

遇到 setConfig 错误时，先用最小项目对照，并通过下面命令检查依赖树。保持一套相同版本的 Univer 包，以及互相兼容的 React / ReactDOM。仅凭报错堆栈不能判断 Vue 2 不受支持。

Bash

npm ls @univerjs/core @univerjs/ui @univerjs/presets @univerjs/preset-sheets-core react react-dom

如果只有编辑区域空白，检查容器是否设置高度、是否引入预设 CSS。保存实例时不要将其变为响应式对象。

Webpack 4 / Vue CLI 3–4

最小项目使用 Vite 与包导出机制，通过构建不等于已验证 Webpack 4。旧构建工具无法解析 Facade 或语言包导出时，建议先升级构建工具；复制不完整的 alias 清单可能掩盖缺失或重复模块。

你觉得这篇文档如何？