Интеграция в React
Если вы хотите использовать компоненты React в качестве пользовательских компонентов, обратитесь к этому разделу.
Перед интеграцией Univer в проект React убедитесь, что вы прочитали раздел «Установка и базовое использование Univer» и понимаете основные концепции и хуки жизненного цикла React.
Интеграция Web SDK с React 18 и 19
Порядок интеграции
- Инициализируйте Univer в хуке
useEffect - Уничтожьте экземпляр Univer в функции, которую возвращает хук
useEffect
Пример
Каждое монтирование использует отдельный дочерний контейнер. Освобождение выполняется в микрозадаче после очистки внешнего React, чтобы не размонтировать вложенный React root синхронно во время commit.
import { UniverDocsCorePreset } from '@univerjs/preset-docs-core'import UniverPresetDocsCoreEnUS from '@univerjs/preset-docs-core/locales/en-US'import { createUniver, LocaleType, mergeLocales } from '@univerjs/presets'import { useEffect, useRef } from 'react'import '@univerjs/preset-docs-core/lib/index.css'export function App() { 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, univerAPI } = createUniver({ locale: LocaleType.EN_US, locales: { [LocaleType.EN_US]: mergeLocales( UniverPresetDocsCoreEnUS, ), }, presets: [ UniverDocsCorePreset({ container, }), ], }) univerAPI.createDocument({}) return () => { queueMicrotask(() => { univer.dispose() container.remove() }) } }, []) return ( <div ref={containerRef} style={{ height: 600 }} /> )}Интеграция Web SDK с React 16.9+ и 17
Перед интеграцией
Примечания о совместимости
Уровень представления Univer разработан на базе React 18.3.1, однако мы обеспечиваем минимальную совместимость с проектами на React 16.9+ и 17. Обратите внимание: это не означает, что старые версии React будут поддерживаться бессрочно. Для доступа к новым возможностям и наиболее удобной работы рекомендуем как можно скорее перейти на последнюю версию.
Настройка псевдонима в инструменте сборки
В среде React 16.9+ и 17 необходимо использовать функцию псевдонимов инструмента сборки, чтобы имитировать экспорт react-dom/client. В противном случае некоторые функции могут работать некорректно.
Пример конфигурации Vite
export default defineConfig({ plugins: [react()], resolve: { alias: { 'react-dom/client': path.resolve(__dirname, './src/client.ts'), }, },})import ReactDOM from 'react-dom'export function createRoot(container: HTMLElement) { return { render: (element: JSX.Element) => { ReactDOM.render(element, container) }, }}Адаптация для CDN/UMD
Если вы подключаете Univer и React с помощью тегов <script>, после импорта React также необходимо добавить следующий код, имитирующий экспорт react-dom/client:
<script> /** * With the support for React 19[^1], UMD users may need additional adaptation. * * [^1]: [support for React 19] https://github.com/dream-num/univer/pull/4247 */ /** * Fix `Uncaught TypeError: client.createRoot is not a function` * If using UMD React < 18, you might need the following code. */ ;(function (global) { 'use strict' if (!global.ReactDOM) { throw new Error('ReactDOM must be loaded before ReactCreateRoot.') } const ReactDOM = global.ReactDOM if (!ReactDOM.createRoot) { ReactDOM.createRoot = function (container) { return { render: (element) => { ReactDOM.render(element, container) }, } } } })(this) /** * Fix `Uncaught TypeError: jsxRuntime.jsx is not a function` * If using UMD React, you might need the following code. * Reference: https://unpkg.com/react@18.3.1/cjs/react-jsx-runtime.production.min.js */ ;(function (global) { 'use strict' if (!global.React) { throw new Error('React must be loaded before ReactJSXRuntime.') } const React = global.React if (!React.jsx || !React.jsxs) { const REACT_ELEMENT_TYPE = Symbol.for('react.element') const hasOwnProperty = Object.prototype.hasOwnProperty const RESERVED_PROPS = { key: true, ref: true, __self: true, __source: true, } const ReactCurrentOwner = React.__SECRET_INTERNALS_DO_NOT_USE_OR_YOU_WILL_BE_FIRED.ReactCurrentOwner function createReactElement(type, config, maybeKey) { const props = {} let key = null let ref = null if (maybeKey !== undefined) { key = `${maybeKey}` } if (config.key !== undefined) { key = `${config.key}` } if (config.ref !== undefined) { ref = config.ref } for (var propName in config) { if (hasOwnProperty.call(config, propName) && !RESERVED_PROPS.hasOwnProperty(propName)) { props[propName] = config[propName] } } if (type && type.defaultProps) { const defaultProps = type.defaultProps for (var propName in defaultProps) { if (props[propName] === undefined) { props[propName] = defaultProps[propName] } } } return { $$typeof: REACT_ELEMENT_TYPE, type, key, ref, props, _owner: ReactCurrentOwner.current, } } React.jsx = createReactElement React.jsxs = createReactElement } })(this)</script>Порядок интеграции
- Инициализируйте Univer в хуке
useEffect - Уничтожьте экземпляр Univer в функции, которую возвращает хук
useEffect
Пример
import { UniverDocsCorePreset } from '@univerjs/preset-docs-core'import UniverPresetDocsCoreEnUS from '@univerjs/preset-docs-core/locales/en-US'import { createUniver, LocaleType, mergeLocales } from '@univerjs/presets'import { useEffect, useRef } from 'react'import '@univerjs/preset-docs-core/lib/index.css'export function App() { 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, univerAPI } = createUniver({ locale: LocaleType.EN_US, locales: { [LocaleType.EN_US]: mergeLocales( UniverPresetDocsCoreEnUS, ), }, presets: [ UniverDocsCorePreset({ container, }), ], }) univerAPI.createDocument({}) return () => { queueMicrotask(() => { univer.dispose() container.remove() }) } }, []) return ( <div ref={containerRef} style={{ height: 600 }} /> )}Насколько полезно это руководство?