Headless Univer

Headless Univer est l'exécution du contenu de Univer sans interface utilisateur d'éditeur. Il utilise les mêmes modèles de contenu, commandes, calcul et API Facade que l'éditeur de navigateur. Il peut fonctionner dans Node.js pour traiter le contenu, ou dans un navigateur pour des tâches qui ne nécessitent pas d'interface utilisateur.

Dans Node.js, il peut créer ou charger un document, lire et modifier des paragraphes et du texte, modifier la structure et les styles, et enregistrer des instantanés Univer. Les tableaux, listes, colonnes, formules et formes nécessitent leurs plugins de contenu.

L'exemple ci-dessous utilise le mode plugin. @univerjs/core et les plugins de contenu de produit forment la couche de contenu Headless. @univerjs/ui, les paquets de produit *-ui, et les préréglages de base du navigateur par défaut ne font pas partie de cette configuration. L'exemple maintient @univerjs/engine-render comme une dépendance partagée mais ne monte ni Canvas ni éditeur. Pour la classification complète et les exceptions, voir Limites des colis sans tête.

L'exemple de collaboration nécessite également un client, un serveur et une authentification. La conversion de bureau nécessite le Server SDK, et les captures d'écran nécessitent un rendu temps d'exécution. L'importation de /facade n'enregistre à elle seule aucun plugin et ne transforme pas les API UI en API Headless.

Installation

Shell
pnpm add @univerjs/core @univerjs/engine-render @univerjs/engine-formula @univerjs/docs

Utilisation

TypeScript
import { LocaleType, Univer } from '@univerjs/core'import { FUniver } from '@univerjs/core/facade'import { UniverDocsPlugin } from '@univerjs/docs'import { UniverFormulaEnginePlugin } from '@univerjs/engine-formula'import { UniverRenderEnginePlugin } from '@univerjs/engine-render'import '@univerjs/docs/facade'const univer = new Univer({  locale: LocaleType.FR_FR,  locales: {    [LocaleType.FR_FR]: {},  },})univer.registerPlugin(UniverRenderEnginePlugin)univer.registerPlugin(UniverFormulaEnginePlugin)univer.registerPlugin(UniverDocsPlugin)const univerAPI = FUniver.newAPI(univer)univerAPI.createDocument({})

Exemple de collaboration dans Node.js

Node.js peut agir en tant que client de collaboration. Il charge un document existant depuis le serveur, modifie le document via le Facade API et synchronise les modifications à tout autre client qui a le même document ouvert. Avant de lancer l'exemple, préparez un service de collaboration, un licence client et un ID de document accessible.

Configuration des plugins

UniverLicensePlugin

  • license
    string
    Contenu du fichier de licence côté client.

UniverDrawingPlugin

  • override
    [DependencyIdentifier, Provider | null][]
    Dépendance outrepasse le plugin de dessin s'applique.
    • [0]
      DependencyIdentifier
      Identifie la dépendance. Pour le stockage d'images, utilisez IImageIoService.
    • [1]
      Provider | null
      Le fournisseur qui remplace celui par défaut. Passez null pour laisser la collaboration fournir ce service.

UniverCollaborationClientPlugin

  • socketService
    Ctor<ICollaborationSocketService>
    L'implémentation de la socket que ce runtime utilise.
  • enableOfflineEditing
    booleanValeur par défaut: false
    Permet d'éditer localement pendant le déconnecté.
  • enableSingleActiveInstanceLock
    booleanValeur par défaut: false
    Conserve un document activement édité dans une seule instance de navigateur.
  • snapshotServerUrl
    stringValeur par défaut: '/universer-api/snapshot'
    Point d'extrémité qui sert des instantanés de documents.
  • collabSubmitChangesetUrl
    stringValeur par défaut: '/universer-api/comb'
    Point d'arrivée où des changements sont soumis.
  • collabWebSocketUrl
    stringValeur par défaut: 'ws://127.0.0.1:8000/universer-api/comb/connect'
    URL WebSocket de synchronisation en temps réel.
  • wsSessionTicketUrl
    stringValeur par défaut: '/universer-api/user/session-ticket'
    Point de fin qui délivre un ticket de session WebSocket.
  • uploadFileServerUrl
    stringValeur par défaut: '/universer-api/stream/file/upload'
    Point d'arrivée pour les téléchargements de fichiers.
  • signUrlServerUrl
    stringValeur par défaut: '/universer-api/file/{fileID}/sign-url'
    Endpoint qui signe les URLs de fichier. Gardez le porte-place {fileID}.
  • downloadEndpointUrl
    string
    URL de base pour les téléchargements de fichiers.
  • authzUrl
    stringValeur par défaut: '/universer-api/authz'
    Point de terminaison de vérification des permissions.
  • sendChangesetTimeout
    numberValeur par défaut: 2000
    Combien de temps les modifications sont par lots avant leur envoi, en millisecondes.
  • retryConnectingInterval
    numberValeur par défaut: 20000
    Intervalle de reconnexion en millisecondes.
  • customHeaders
    Record<string, string>
    En-têtes supplémentaires envoyés avec la connexion.
    • [header]
      string
      La valeur envoyée pour cet en-tête HTTP.

Fichiers de l’exemple

Arrangez les fichiers comme suit :

text
src/docs/node/├── main.ts└── univer.ts
  • univer.ts crée Univer et enregistre les plugins de fonctionnalités de documents, les extensions Facade et le client de collaboration Node.js.
  • main.ts charge un document collaboratif et exerce des paragraphes, du texte, des en-têtes et des pied de page, des appels, des blocs de code, des citations, des listes, des formes, des tables et des colonnes.

Remplacer your-license, l'URL du serveur et le Cookie en univer.ts, et l'ID du document en main.ts.

TypeScript
import { UniverCollaborationPlugin } from '@univerjs-pro/collaboration'import { UniverCollaborationClientPlugin } from '@univerjs-pro/collaboration-client'import {  NodeCollaborationSocketService,  UniverCollaborationClientNodePlugin,} from '@univerjs-pro/collaboration-client-node'import { UniverDocsCalloutPlugin } from '@univerjs-pro/docs-callout'import { UniverDocsCodePlugin } from '@univerjs-pro/docs-code'import { UniverDocsColumnPlugin } from '@univerjs-pro/docs-column'import { UniverDocsLatexPlugin } from '@univerjs-pro/docs-latex'import { UniverDocsListPlugin } from '@univerjs-pro/docs-list'import { UniverDocsQuotePlugin } from '@univerjs-pro/docs-quote'import { UniverDocsReferencePlugin } from '@univerjs-pro/docs-reference'import { UniverDocsShapePlugin } from '@univerjs-pro/docs-shape'import { UniverDocsTablePlugin } from '@univerjs-pro/docs-table'import { UniverLicensePlugin } from '@univerjs-pro/license'import {  IAuthzIoService,  IImageIoService,  IMentionIOService,  IUndoRedoService,  LocaleType,  Univer,} from '@univerjs/core'import { UniverDocsPlugin } from '@univerjs/docs'import { UniverDocsDrawingPlugin } from '@univerjs/docs-drawing'import { UniverDocsHyperLinkPlugin } from '@univerjs/docs-hyper-link'import { UniverDrawingPlugin } from '@univerjs/drawing'import { UniverRenderEnginePlugin } from '@univerjs/engine-render'import { UniverNetworkPlugin } from '@univerjs/network'import { UniverThreadCommentPlugin } from '@univerjs/thread-comment'import '@univerjs/docs/facade'import '@univerjs/docs-drawing/facade'import '@univerjs-pro/docs-shape/facade'import '@univerjs-pro/docs-callout/facade'import '@univerjs-pro/docs-reference/facade'import '@univerjs-pro/docs-code/facade'import '@univerjs-pro/docs-list/facade'import '@univerjs-pro/docs-quote/facade'import '@univerjs-pro/docs-table/facade'import '@univerjs-pro/docs-column/facade'import '@univerjs-pro/docs-latex/facade'import '@univerjs-pro/collaboration-client/facade'export function createUniverOnNode(): Univer {  const univer = new Univer({    locale: LocaleType.FR_FR,    locales: {},    override: [      [IAuthzIoService, null],      [IUndoRedoService, null],      [IMentionIOService, null],    ],  })  univer.registerPlugin(UniverLicensePlugin, {    license: 'your-license',  })  univer.registerPlugin(UniverRenderEnginePlugin)  univer.registerPlugin(UniverThreadCommentPlugin)  univer.registerPlugin(UniverDrawingPlugin, {    override: [[IImageIoService, null]],  })  univer.registerPlugin(UniverDocsPlugin)  univer.registerPlugin(UniverDocsDrawingPlugin)  univer.registerPlugin(UniverDocsHyperLinkPlugin)  univer.registerPlugin(UniverDocsReferencePlugin)  univer.registerPlugin(UniverDocsCalloutPlugin)  univer.registerPlugin(UniverDocsCodePlugin)  univer.registerPlugin(UniverDocsListPlugin)  univer.registerPlugin(UniverDocsQuotePlugin)  univer.registerPlugin(UniverDocsShapePlugin)  univer.registerPlugin(UniverDocsTablePlugin)  univer.registerPlugin(UniverDocsColumnPlugin)  univer.registerPlugin(UniverDocsLatexPlugin)  registerCollaborationPlugins(univer)  return univer}function registerCollaborationPlugins(univer: Univer): void {  const serverUrl = 'https://your-univer-server.example.com'  univer.registerPlugin(UniverNetworkPlugin)  univer.registerPlugin(UniverCollaborationPlugin)  univer.registerPlugin(UniverCollaborationClientPlugin, {    socketService: NodeCollaborationSocketService,    enableOfflineEditing: false,    enableSingleActiveInstanceLock: false,    snapshotServerUrl: `${serverUrl}/universer-api/snapshot`,    collabSubmitChangesetUrl: `${serverUrl}/universer-api/comb`,    collabWebSocketUrl: `${serverUrl}/universer-api/comb/connect`,    wsSessionTicketUrl: `${serverUrl}/universer-api/user/session-ticket`,    uploadFileServerUrl: `${serverUrl}/universer-api/stream/file/upload`,    signUrlServerUrl: `${serverUrl}/universer-api/file/{fileID}/sign-url`,    downloadEndpointUrl: serverUrl,    authzUrl: `${serverUrl}/universer-api/authz`,    sendChangesetTimeout: 200,    retryConnectingInterval: 1000,    customHeaders: {      // Exemple : si votre serveur Univer exige une authentification par Cookie, définissez l’en-tête 'cookie' ici.      cookie: 'your-cookie',      // ... autres en-têtes    },  })  univer.registerPlugin(UniverCollaborationClientNodePlugin)}

Notes d’exécution

loadDocAsync() charge un document qui existe déjà sur le serveur, donc createDocument() n'est pas nécessaire. Le service de collaboration identifie l'utilisateur et vérifie les autorisations à partir des informations d'authentification, comme le Cookie dans customHeaders. Le serveur retourne le memberID de la connexion.

L'exemple désactive la mise en cache hors ligne du navigateur et le verrouillage à une seule installation active sur les onglets, de sorte que setCurrentUser() n'est pas nécessaire pour l'isolement du cache entre les comptes. Si des fonctionnalités qui dépendent d'un utilisateur courant local, comme les commentaires, sont ajoutées plus tard, l'utilisateur de l'application peut être défini par UserManagerService. Cela ne remplace pas l'authentification du serveur.

L'exemple en-tête/pied de page s'applique uniquement aux documents en page, et l'exemple de colonne s'applique seulement aux documents modernes. L'exemple vérifie le mode document avec isModern() et saute les opérations qui ne s'appliquent pas.

L'exemple insère du contenu dans un document existant, donc utilisez un document de test. La connexion de collaboration reste également ouverte après la fin de l'exemple. Ouvrez le même document dans un navigateur pour voir les modifications. flush() attend que le serveur reconnaisse les modifications de collaboration en file d'attente. Pour un script à une prise, appelez univer.dispose() après toutes les opérations asynchrones et la synchronisation ont été terminées.

Que pensez-vous de ce guide ?

© 2026 DreamNum Co., Ltd.