Intégrer dans React

Pour savoir comment utiliser des composants React en tant que composants personnalisés, consultez cette section.

Avant d’intégrer Univer à un projet React, assurez-vous d’avoir lu la section Installation et utilisation de base d’Univer et de comprendre les concepts fondamentaux et les hooks de cycle de vie de React.

Intégrer Web SDK à React 18 et 19

Étapes d’intégration

Initialisez Univer dans le hook useEffect
Détruisez Univer dans la fonction de nettoyage renvoyée par le hook useEffect

Exemple

Chaque montage utilise son propre conteneur enfant. La destruction est différée dans une microtâche après le nettoyage React parent, afin de ne pas démonter une racine React imbriquée pendant un commit.

TSX

import { UniverSheetsCorePreset } from '@univerjs/preset-sheets-core'import UniverPresetSheetsCoreEnUS from '@univerjs/preset-sheets-core/locales/en-US'import { createUniver, LocaleType, mergeLocales } from '@univerjs/presets'import { useEffect, useRef } from 'react'import '@univerjs/preset-sheets-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(          UniverPresetSheetsCoreEnUS,        ),      },      presets: [        UniverSheetsCorePreset({          container,        }),      ],    })    univerAPI.createWorkbook({})    return () => {      queueMicrotask(() => {        univer.dispose()        container.remove()      })    }  }, [])  return (    <div ref={containerRef} style={{ height: 600 }} />  )}

Intégrer Web SDK à React 16.9+ et 17

Remarques préalables à l’intégration

Compatibilité

La couche d’affichage d’Univer est développée avec React 18.3.1, mais nous assurons une compatibilité minimale avec les projets sous React 16.9+ et 17. Cela ne signifie pas que les anciennes versions de React seront prises en charge indéfiniment. Pour bénéficier d’une expérience optimale et des nouvelles fonctionnalités, nous vous recommandons de passer à la dernière version dès que possible.

Configuration des alias de l’outil de build

Dans un environnement React 16.9+ ou 17, vous devez utiliser la fonctionnalité d’alias de votre outil de build pour simuler l’export de react-dom/client. Dans le cas contraire, certaines fonctionnalités risquent de ne pas fonctionner correctement.

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 aux environnements CDN/UMD

Si vous incluez Univer et React à l’aide de balises <script>, veillez également à ajouter le code suivant après l’importation de React afin de simuler l’export 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>

Étapes d’intégration

Initialisez Univer dans le hook useEffect
Détruisez Univer dans la fonction de nettoyage renvoyée par le hook useEffect

Exemple

TSX

import { UniverSheetsCorePreset } from '@univerjs/preset-sheets-core'import UniverPresetSheetsCoreEnUS from '@univerjs/preset-sheets-core/locales/en-US'import { createUniver, LocaleType, mergeLocales } from '@univerjs/presets'import { useEffect, useRef } from 'react'import '@univerjs/preset-sheets-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(          UniverPresetSheetsCoreEnUS,        ),      },      presets: [        UniverSheetsCorePreset({          container,        }),      ],    })    univerAPI.createWorkbook({})    return () => {      queueMicrotask(() => {        univer.dispose()        container.remove()      })    }  }, [])  return (    <div ref={containerRef} style={{ height: 600 }} />  )}

Que pensez-vous de ce guide ?