Maîtriser les API ONLYOFFICE avec Playground

27 novembre 2025Par Dasha

Tester et explorer les API ONLYOFFICE peut s’avérer difficile si vous devez configurer un plugin complet ou un environnement d’automatisation pour chaque petite expérience. L’API Playground de ONLYOFFICE docs offre un espace dédié où les développeurs peuvent interagir avec des documents par programmation, essayer des commandes et comprendre le comportement de l’API en temps réel.

Dans ce guide, nous vous montrerons comment Playground accélère le développement, nous mettrons en avant des exemples pratiques et nous vous donnerons des conseils pour choisir l’API adaptée à vos besoins.

Mastering ONLYOFFICE APIs with Playground

Pourquoi le Playground est-il important ?

Le Playground est conçu pour les développeurs qui souhaitent :

  • Tester différentes API dans un environnement d’édition en direct.
  • Insérer et manipuler du texte ou du contenu HTML par programmation.
  • Surveiller et répondre aux événements liés aux documents.
  • Tester des cas limites, des entrées volumineuses ou des caractères spéciaux sans avoir à configurer un environnement complet de plug-ins ou de connecteurs.

Utiliser le Playground avant de créer un plug-in ou un workflow d’automatisation vous aide à détecter rapidement les problèmes potentiels, à comprendre les contraintes des API et à rationaliser votre processus de développement.

Comprendre les API disponibles

Le Playground prend en charge trois API principales :

  1. API JavaScript Office – Création et manipulation directes de documents, idéale pour les scripts, la génération de documents et les tâches d’automatisation simples.
  2. API Plugin – Utilisée pour créer des plugins interactifs ONLYOFFICE. Prend en charge les modèles async/await pour une exécution propre du code et des opérations complexes.
  3. API d’automatisation / Connecteur – Utilisée pour permettre à des systèmes externes d’accéder à des documents et de les modifier, à l’aide de rappels pour l’intégration et l’automatisation.

Chaque API a un objectif distinct, et le Playground vous permet de les tester côte à côte afin de déterminer celle qui correspond le mieux à votre flux de travail.

Premiers pas avec les extraits de code Playground

Vous trouverez ci-dessous des exemples pratiques illustrant l’utilisation de chaque API. Copiez un extrait de code dans l’éditeur Playground pour l’exécuter immédiatement.

Insertion de texte de base

Objectif : illustrer l’insertion de texte à la position actuelle du curseur à l’aide des trois API.

Cas d’utilisation : insertion de texte simple dans des documents ou test du comportement de l’API.

//APPROACH 1: Using Automation API (Connector)

// Use this when working with connector for external document access

connector.executeMethod(
  "PasteText",
  ["Hello from ONLYOFFICE Automation API!"],
  function() {
    console.log("Text inserted using Automation API");
  }
);
//APPROACH 2: Using Plugin API with Editor helper

// Use this when developing plugins
(async function(){
  await Editor.callMethod("PasteText", ["Hello from ONLYOFFICE Plugin API!"]);
  console.log("Text inserted using Plugin API");
})();

//APPROACH 3: Using Office JavaScript API directly
// Use this for direct document building and manipulation
var oDocument = Api.GetDocument();
var oParagraph = Api.CreateParagraph();
oParagraph.AddText("Hello from ONLYOFFICE Office JavaScript API!");
oDocument.InsertContent([oParagraph]);
console.log("Text inserted using Office JavaScript API");

Conseil pour les développeurs : vérifiez toujours la réponse de l’API dans la console immédiatement après avoir appelé une méthode. Même des opérations simples telles que PasteText ou PasteHtml peuvent se comporter différemment en fonction de la position du curseur, de la sélection ou de la structure HTML. La journalisation des résultats permet de détecter rapidement les comportements inattendus.

Contenu HTML avec mise en forme

Objectif : montrer comment insérer du contenu HTML enrichi, notamment des titres, des listes et des styles personnalisés.

Cas d’utilisation : importer du contenu formaté, coller du texte enrichi ou générer dynamiquement des sections.

// HTML string with various formatting elements
const htmlContent = `
  <h2 style="color: #2E86C1;">Welcome to ONLYOFFICE</h2>
  <p>This is a <strong>bold text</strong> and this is <em>italic text</em>.</p>
  <ul>
    <li>First bullet point</li>
    <li>Second bullet point with <u>underlined text</u></li>
    <li>Third bullet point</li>
  </ul>
  <p style="color: #28B463;">This paragraph has custom color styling.</p>
`;

// APPROACH 1: Using Automation API (Connector)

// The PasteHtml method automatically converts HTML to document elements

connector.executeMethod(
  "PasteHtml",
  [htmlContent],
  function() {
    console.log("HTML content inserted using Automation API");
  }
);
// APPROACH 2: Using Plugin API with Editor helper

(async function(){
  await Editor.callMethod("PasteHtml", [htmlContent]);
  console.log("HTML content inserted using Plugin API");
})();

Écouteurs d’événements pour les modifications de documents

Objectif : illustrer la surveillance des événements liés aux documents, tels que les modifications de sélection ou les mises à jour de contenu.

Cas d’utilisation : créer des fonctionnalités réactives, suivre les actions des utilisateurs ou synchroniser avec des systèmes externes.

connector.attachEvent("onSelectionChanged", function(selectionInfo) {

  console.log("Selection changed:", JSON.stringify(selectionInfo, null, 2));
  // Get the current word under cursor
  connector.executeMethod("GetCurrentWord", [], function(currentWord) {
    console.log("Current word:", currentWord);
  });

});

connector.attachEvent("onDocumentContentReady", function() {
  console.log("Document ready");
});
// APPROACH 2: Using Plugin API

// Event listeners work similarly with Asc.plugin.attachEvent()
Asc.plugin.attachEvent("onSelectionChanged", function(selectionInfo) {
  console.log("Selection changed:", JSON.stringify(selectionInfo, null, 2));
});
(async function(){

  let word = await Editor.callMethod("GetCurrentWord");
  console.log("Current word:", word);
})();

Contenu HTML volumineux et imbriqué

Objectif : tester la gestion de structures HTML complexes avec des éléments et des tableaux imbriqués.

Cas d’utilisation : générer des rapports, migrer des documents formatés ou créer des mises en page avancées.

const complexHtml = `
  <h1 style="color: #2C3E50; text-align: center;">Comprehensive Document Report</h1>
  
  <h2 style="color: #E74C3C;">1. Executive Summary</h2>
  <p>This report demonstrates the ONLYOFFICE API's capability to handle 
  <em>complex HTML structures</em> with <u>multiple levels of nesting</u>.</p>
  
  <h2 style="color: #E74C3C;">2. Key Features</h2>
  <ul>
    <li>Rich Text Formatting: Bold, italic, underline, and colors</li>
    <li>Hierarchical Lists: Nested bullet points
      <ul>
        <li>Sub-item level 1</li>
        <li>Sub-item level 2
          <ul>
            <li>Sub-item level 3 (deeply nested)</li>
          </ul>
        </li>
      </ul>
    </li>
    <li>Tables and Structures: Complex layouts</li>
  </ul>
  
  <h2 style="color: #E74C3C;">3. Data Presentation</h2>
  <table border="1" cellpadding="10" style="width: 100%; border-collapse: collapse;">
    <thead>
      <tr style="background-color: #3498DB; color: white;">
        <th>Feature</th>
        <th>Description</th>
        <th>Status</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td>Text Insertion</td>
        <td>Insert plain and formatted text</td>
        <td style="color: #27AE60;">✓ Supported</td>
      </tr>
      <tr>
        <td>HTML Import</td>
        <td>Convert HTML to document elements</td>
        <td style="color: #27AE60;">✓ Supported</td>
      </tr>
      <tr>
        <td>Event Handling</td>
        <td>Monitor document changes</td>
        <td style="color: #27AE60;">✓ Supported</td>
      </tr>
    </tbody>
  </table>
  
  <h2 style="color: #E74C3C;">4. Conclusion</h2>
  <p style=" padding: 15px;">
    The ONLYOFFICE API successfully handles 
    <span style="background-color: #F39C12; color: white; padding: 2px 5px;">
    complex HTML content</span> with multiple levels of nesting.
  </p>
`;
// APPROACH 1: Using Automation API (Connector)
connector.executeMethod(
  "PasteHtml",
  [complexHtml],
  function() {
    console.log("Complex HTML inserted (" + complexHtml.length + " characters)");
  }
);
// APPROACH 2: Using Plugin API with Editor helper

(async function(){
  await Editor.callMethod("PasteHtml", [complexHtml]);
  console.log("Complex HTML inserted using Plugin API");
})();

Premier appel API simple avec cas limites

Objectif : initier les débutants à l’utilisation des API, aux cas limites courants et aux modèles de gestion des erreurs.

Cas d’utilisation : apprendre les bases de l’API JavaScript Office, de l’API Plugin et de l’API Automation.

// APPROACH 1: Office JavaScript API
var oDocument = Api.GetDocument();
var oParagraph = Api.CreateParagraph();
oParagraph.AddText(" Hello from Office JavaScript API!");
oDocument.InsertContent([oParagraph]);
console.log("Content created with Office JavaScript API");

// EDGE CASE 1: Handling empty or null text
var oParagraph2 = Api.CreateParagraph();
var textToInsert = ""; // Empty string
if (textToInsert && textToInsert.trim().length > 0) {
  oParagraph2.AddText(textToInsert);
} else {
  oParagraph2.AddText("(Empty text was provided)");
}
oDocument.InsertContent([oParagraph2]);

// EDGE CASE 2: Working with special characters and Unicode
var oParagraph3 = Api.CreateParagraph();
oParagraph3.AddText("Special chars: © ® ™ € £ ¥ • · « » — 'quotes' 中文 العربية");
oDocument.InsertContent([oParagraph3]);

// EDGE CASE 3: Creating content with mixed formatting
var oParagraph4 = Api.CreateParagraph();
var oRun1 = Api.CreateRun();
oRun1.AddText("This is bold ");
oRun1.SetBold(true);
oParagraph4.AddElement(oRun1);
var oRun2 = Api.CreateRun();
oRun2.AddText("and this is italic ");
oRun2.SetItalic(true);
oParagraph4.AddElement(oRun2);
var oRun3 = Api.CreateRun();
oRun3.AddText("and this is colored.");
oRun3.SetColor(220, 20, 60, false); // Crimson color
oParagraph4.AddElement(oRun3);
oDocument.InsertContent([oParagraph4]);
// EDGE CASE 4: Checking if document exists before operations
if (oDocument) {
  var oParagraph5 = Api.CreateParagraph();
  oParagraph5.AddText("Document validation: OK");
  oDocument.InsertContent([oParagraph5]);
  console.log("Document exists and is accessible");
} else {
  console.log("ERROR: Document not accessible");
}
// APPROACH 2: Plugin API with Editor Helper (For Plugin Development)
// Use async/await pattern with error handling
(async function(){
  try {
    // Get editor version
    let version = await Editor.callMethod("GetVersion");
    console.log("Editor version:", version);

    // EDGE CASE 1: Insert HTML with error handling
    await Editor.callMethod("PasteHtml", [
      "<p><b>Hello</b> from <i>Plugin API</i>!</p>"
    ]);
    console.log("Content inserted with Plugin API");
   
    // EDGE CASE 2: Check if method returns undefined or null
    let selectedText = await Editor.callMethod("GetSelectedText");
    if (selectedText) {
      console.log("Selected text:", selectedText);
    } else {
      console.log("No text selected or selection is empty");
    }
    // EDGE CASE 3: Handling special characters in Plugin API
    await Editor.callMethod("PasteText", [
      "Special: © 2024 | €100 | 中文"
    ]);

    // EDGE CASE 4: Multiple async operations in sequence
    await Editor.callMethod("PasteText", ["Line 1 "]);
    await Editor.callMethod("PasteText", ["Line 2 "]);
    await Editor.callMethod("PasteText", ["Line 3"]);
    console.log("Multiple operations completed");
  } catch (error) {
    console.log("ERROR in Plugin API:", error.message || error);
  }
})();

Conseil pour les développeurs : lorsque vous utilisez l’API du plugin avec async/await, placez vos appels dans des blocs try/catch. Cela garantit que les erreurs telles que les sélections non définies ou le contenu non pris en charge n’interrompent pas votre script et vous permet de fournir des messages de console informatifs pour le débogage.

// APPROACH 3: Automation API (Connector - For External Access)

// Uses callbacks with error handling

// EDGE CASE 1: Check if connector exists before using

if (typeof connector !== 'undefined' && connector) {

  // Basic text insertion with callback error handling
  connector.executeMethod(
    "PasteText",
    ["Hello from Automation API!"],
    function(result) {
      if (result !== undefined) {
        console.log("Content inserted with Automation API");
      } else {
        console.log("Insert may have failed, result is undefined");
      }

      // EDGE CASE 2: Chain multiple operations with error checking
      connector.executeMethod("GetCurrentWord", [], function(word) {
        if (word && word.length > 0) {
          console.log("Current word:", word);
        } else {
          console.log("No word at cursor position");
        }
      });
    }
  );

  // EDGE CASE 3: Handling empty or invalid HTML

  var htmlToInsert = "<p>Test</p>";
  if (htmlToInsert && htmlToInsert.includes("<")) {
    connector.executeMethod(
      "PasteHtml",
      [htmlToInsert],
      function() {
        console.log("HTML inserted successfully");
      }
    );
  } else {
    console.log("Invalid HTML content");
  }

  // EDGE CASE 4: Timeout handling for slow operations

  var operationTimeout = setTimeout(function() {

    console.log("WARNING: Operation taking longer than expected");

  }, 5000);
  connector.executeMethod(
    "PasteText",
    ["Async operation test"],
    function() {
      clearTimeout(operationTimeout);

      console.log("Operation completed in time");
    }
  );

} else {
  console.log("ERROR: Connector is not available");
}

Instructions d’utilisation et meilleures pratiques

  • Exécuter les extraits individuellement pour éviter les conflits.
  • Utiliser la console du navigateur pour afficher les journaux d’exécution et déboguer les résultats.
  • Choisir l’API appropriée :

Créer des documents à partir de zéro → API JavaScript Office,

Développer des plugins → API des plugins,

Intégration avec des applications externes → API d’automatisation (connecteur).

  • Expérimenter avec le formatage, le HTML et les événements pour bien comprendre le comportement de l’API.

Parcours d’apprentissage recommandé

  1. Commencez par un premier appel API simple pour comparer les différentes approches.
  2. Passez à l’insertion de texte de base pour comprendre les différences entre les API.
  3. Testez l’insertion HTML pour le formatage et le contenu enrichi.
  4. Explorez les écouteurs d’événements pour les API d’automatisation et de plug-ins.
  5. Passez à un contenu HTML complexe pour gérer des structures imbriquées de grande taille.

Conclusion

ONLYOFFICE Playground est un outil puissant qui permet d’accélérer l’apprentissage des API, les tests et le développement de plugins. En fournissant un environnement interactif et sécurisé, il permet aux développeurs d’expérimenter en toute sécurité, de comprendre en profondeur le comportement des API et de créer plus efficacement des plugins robustes et des workflows automatisés.

Liens utiles

Commencer avec Playground

Comment créer votre propre plugin

ONLYOFFICE sur GitHub

Contribuer à ONLYOFFICE

Créez votre compte ONLYOFFICE gratuit

Affichez, modifiez et coéditez des documents texte, feuilles de calcul, diapositives, formulaires et fichiers PDF en ligne.