在 Next.js 中集成
本页从安装和基本使用开始。下面的示例使用 Next.js App Router,将 Univer Bases 挂载到一个高度固定的容器中。
编辑器应放在客户端组件中,并通过 ssr: false1 动态加载。仅添加 use client 指令并不会关闭预渲染,具体原因参见 Next.js。
将 YOUR_CLIENT_LICENSE 替换为客户端许可证内容。此处填写的是许可证文本,而非文件路径。配置方式参见许可证配置。
集成步骤
- 在
useEffect中初始化 Univer。 - 在
useEffect cleanup中销毁 Univer。
插件配置
UniverUIPlugin
containerstring | HTMLElement编辑器挂载目标的 DOM 元素或其 ID。
UniverLicensePlugin
licensestring客户端许可证文件的内容。
示例代码
每次挂载都会创建独立的子容器。销毁在微任务中执行,即等外层 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
-
服务端渲染(SSR)会在浏览器加载页面前执行渲染代码,此时没有浏览器的
window和 DOM。Client Component 仍可能被预渲染,因此需要单独关闭编辑器组件的 SSR。 ↩
你觉得这篇文档如何?