在 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 UniverPresetSheetsCoreZhTW from '@univerjs/preset-sheets-core/locales/zh-TW'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_TW,    locales: {      [LocaleType.ZH_TW]: mergeLocales(        UniverPresetSheetsCoreZhTW,      ),    },    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，開啟終端顯示的網址。範例介面為英文。現有專案依下列步驟整合。

安裝一致的相依套件

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 UniverPresetSheetsCoreZhTW from '@univerjs/preset-sheets-core/locales/zh-TW'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_TW,      locales: {        [LocaleType.ZH_TW]: mergeLocales(          UniverPresetSheetsCoreZhTW,        ),      },      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 清單可能掩蓋缺失或重複模組。

你覺得這篇文檔如何？