Integrar en React

Si está buscando cómo utilizar los componentes de React como componentes personalizados, consulte aquí.

Antes de integrar Univer en un proyecto de React, asegúrese de haber leído la sección Instalación y uso básico de Univer y de comprender los conceptos básicos y los enlaces del ciclo de vida de React.

Integración de Web SDK con React 18 y 19

Integración Pasos

Inicializar Univer en el gancho useEffect
Destruir Univer en la función de retorno del gancho useEffect

Ejemplo

Cada montaje usa su propio contenedor hijo. La destrucción se ejecuta en una microtarea tras la limpieza de React para evitar desmontar una raíz React anidada durante un commit.

TSX

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 }} />  )}

Integración de Web SDK con React 16.9+ y 17

Notas antes de la integración

Compatibilidad Notas

La capa de vista de Univer está desarrollada en base a React 18.3.1, pero brindamos soporte de compatibilidad mínimo para proyectos React 16.9+ y 17. Tenga en cuenta que esto no significa que las versiones inferiores de React serán compatibles indefinidamente; recomendamos actualizar a la última versión lo antes posible para obtener la mejor experiencia y nuevas funciones.

Configuración del alias de la herramienta de compilación

En un entorno React 16.9+ y 17, debe usar la función de alias de su herramienta de compilación para simular la exportación de react-dom/client; de lo contrario, es posible que algunas funciones no funcionen correctamente.

Ejemplo de configuración de Vite

TypeScript

export default defineConfig({  plugins: [react()],  resolve: {    alias: {      'react-dom/client': path.resolve(__dirname, './src/client.ts'),     },  },})

TypeScript

import ReactDOM from 'react-dom'export function createRoot(container: HTMLElement) {  return {    render: (element: JSX.Element) => {      ReactDOM.render(element, container)    },  }}

Escena CDN/UMD Adaptación

Si incluye Univer y React mediante etiquetas <script>, también debe asegurarse de que se agregue el siguiente código después de importar React para simular la exportación de react-dom/client:

HTML

<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>

Pasos de integración

Inicializar Univer en el gancho useEffect
Destruir Univer en la función de retorno del useEffect gancho

Ejemplo

TSX

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 }} />  )}

¿Cómo es esta guía?