在 Next.js 中集成

本页从安装和基本使用开始。下面的示例使用 Next.js App Router,将 Univer Bases 挂载到一个高度固定的容器中。

编辑器应放在客户端组件中,并通过 ssr: false1 动态加载。仅添加 use client 指令并不会关闭预渲染,具体原因参见 Next.js。

将 YOUR_CLIENT_LICENSE 替换为客户端许可证内容。此处填写的是许可证文本,而非文件路径。配置方式参见许可证配置。

集成步骤

  1. 在 useEffect 中初始化 Univer。
  2. 在 useEffect cleanup 中销毁 Univer。

插件配置

UniverUIPlugin

  • container
    string | HTMLElement
    编辑器挂载目标的 DOM 元素或其 ID。

UniverLicensePlugin

  • license
    string
    客户端许可证文件的内容。

示例代码

每次挂载都会创建独立的子容器。销毁在微任务中执行,即等外层 React 清理完成后才执行,这样嵌套的 React root 不会在 React 提交期间被同步卸载。

TSX
'use client'import { useEffect, useRef } from 'react'import { UniverBasesPlugin } from '@univerjs-pro/bases'import { UniverBasesUIPlugin } from '@univerjs-pro/bases-ui'import BasesUIzhCN from '@univerjs-pro/bases-ui/locale/zh-CN'import BaseszhCN from '@univerjs-pro/bases/locale/zh-CN'import { UniverProFormulaEnginePlugin } from '@univerjs-pro/engine-formula'import { UniverLicensePlugin } from '@univerjs-pro/license'import { LocaleType, mergeLocales, Univer, UniverInstanceType } from '@univerjs/core'import DesignzhCN from '@univerjs/design/locale/zh-CN'import { UniverRenderEnginePlugin } from '@univerjs/engine-render'import { UniverUIPlugin } from '@univerjs/ui'import UIzhCN from '@univerjs/ui/locale/zh-CN'import '@univerjs/design/lib/index.css'import '@univerjs/ui/lib/index.css'import '@univerjs-pro/bases-ui/lib/index.css'export default function UniverEditor() {  const containerRef = useRef<HTMLDivElement>(null)  useEffect(() => {    const host = containerRef.current    if (!host) return    const container = document.createElement('div')    container.style.height = '100%'    host.append(container)    const univer = new Univer({      locale: LocaleType.ZH_CN,      locales: {        [LocaleType.ZH_CN]: mergeLocales(          DesignzhCN,          UIzhCN,          BaseszhCN,          BasesUIzhCN,        ),      },    })    univer.registerPlugin(UniverLicensePlugin, {      license: 'YOUR_CLIENT_LICENSE',    })    univer.registerPlugin(UniverRenderEnginePlugin)    univer.registerPlugin(UniverUIPlugin, { container })    univer.registerPlugin(UniverProFormulaEnginePlugin)    univer.registerPlugin(UniverBasesPlugin)    univer.registerPlugin(UniverBasesUIPlugin)    univer.createUnit(UniverInstanceType.UNIVER_BASE, {})    return () => {      queueMicrotask(() => {        univer.dispose()        container.remove()      })    }  }, [])  return <div ref={containerRef} style={{ height: 600 }} />}
TSX
'use client'import dynamic from 'next/dynamic'const UniverEditor = dynamic(() => import('./univer-editor'), { ssr: false })export default function Page() {  return <UniverEditor />}

Footnotes

  1. 服务端渲染(SSR)会在浏览器加载页面前执行渲染代码,此时没有浏览器的 window 和 DOM。Client Component 仍可能被预渲染,因此需要单独关闭编辑器组件的 SSR。 ↩

你觉得这篇文档如何?

© 2026 DreamNum Co., Ltd.