Intégrer dans React

Pour utiliser les composants React comme composants personnalisés, consultez composants personnalisés.

Avant d'ajouter Univer à un projet React, lisez Installation Univer et utilisation de base et assurez-vous que vous êtes familier avec les concepts de base et les crochets du cycle de vie de React.

Intégrer Web SDK avec React 18 et 19

Étapes d’intégration

  1. Initialisez Univer dans useEffect.
  2. Détruisez-le dans la fonction de nettoyage retournée par useEffect.

Configuration des préréglages

UniverDocsCorePreset

  • container
    string | HTMLElementValeur par défaut: 'app'
    Élément DOM de montage de l’éditeur ou son identifiant.

Exemple

Chaque montage crée son propre conteneur enfant. L'élimination se déroule dans une microtâche après le nettoyage React environnant, de sorte qu'une racine React imbriquée n'est jamais démontée synchronement lors d'un commit React.

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

Intégrer Web SDK avec React 16.9+ et 17

Remarques avant l’intégration

Remarques sur la compatibilité

Le calque de vue de Univer est construit sur React 18.3.1. Les projets React 16,9+ et 17 reçoivent une compatibilité minimale et cette prise en charge ne durera pas indéfiniment. De nouvelles fonctionnalités et la meilleure expérience sont fournies sur la dernière version React, de sorte qu'une mise à niveau est recommandée.

Configuration des alias de l’outil de build

Dans les projets React 16,9+ & 17, utilisez la fonction alias de l'outil de construction pour pointer react-dom/client sur un shim. Sans ce pseudo, certaines fonctionnalités ne fonctionnent pas.

Exemple de configuration 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)    },  }}

Adaptation pour une utilisation avec CDN/UMD

Si Univer et React sont chargés via les balises <script>, ajoutez le code suivant après les charges React. Il fournit l'exportation react-dom/client que UMD construit ne fournit pas:

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>

Étapes d’intégration

  1. Initialisez Univer dans useEffect.
  2. Détruisez-le dans la fonction de nettoyage retournée par useEffect.

Exemple

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

Que pensez-vous de ce guide ?

© 2026 DreamNum Co., Ltd.