Padroneggiare le API di ONLYOFFICE con Playground

27 novembre 2025Da Alice

Testare e sperimentare le API di ONLYOFFICE può essere complicato se devi creare ogni volta un intero ambiente di plugin o automazione per fare piccoli test. Il Playground delle API di ONLYOFFICE Docs offre uno spazio dedicato dove gli sviluppatori possono interagire con i documenti in modo programmatico, provare comandi e capire il comportamento delle API in tempo reale.

In questa guida mostriamo come Playground accelera lo sviluppo, proponiamo esempi pratici e diamo indicazioni per scegliere l’API più adatta alle tue esigenze.

Mastering ONLYOFFICE APIs with Playground

Perché Playground è importante

Playground è pensato per gli sviluppatori che vogliono:

  • Sperimentare varie API in un editor live.
  • Inserire e manipolare testo o contenuti HTML in modo programmatico.
  • Monitorare e gestire eventi del documento.
  • Testare casi limite, input molto grandi o caratteri speciali senza creare un plugin o un connettore completo.

Usare Playground prima di creare un plugin o un flusso di automazione ti aiuta a individuare problemi in anticipo, capire i limiti delle API e ottimizzare il processo di sviluppo.

Comprendere le API disponibili

Il Playground supporta tre API principali:

  1. Office JavaScript API – Creazione e manipolazione diretta dei documenti, ideale per script, generazione di documenti e automazioni semplici.
  2. Plugin API – Usata per creare plugin interattivi ONLYOFFICE. Supporta pattern async/await per un codice più pulito e operazioni complesse.
  3. Automation API / Connector – Usata dai sistemi esterni per accedere e modificare i documenti tramite callback per integrazioni e automazioni.

Ogni API ha uno scopo diverso e Playground permette di testarle fianco a fianco per vedere quale si adatta meglio al tuo flusso di lavoro.

Primi passi con gli snippet di Playground

Qui sotto trovi esempi pratici che mostrano come usare ogni API. Copia uno snippet nell’editor di Playground per eseguirlo subito.

Inserimento basico del testo

Scopo: mostra come inserire testo nella posizione del cursore usando tutte e tre le API.

Caso d’uso: inserimento semplice di testo o test del comportamento delle 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");

Consiglio da sviluppatore: controlla sempre la risposta dell’API nella console subito dopo aver chiamato un metodo. Anche operazioni semplici come PasteText o PasteHtml possono comportarsi in modo diverso in base alla posizione del cursore, alla selezione o alla struttura HTML. Loggare i risultati aiuta a individuare comportamenti inattesi.

Contenuto HTML con formattazione

Scopo: mostra come inserire contenuti HTML formattati, con titoli, liste e stili personalizzati.

Caso d’uso: importare contenuti formattati, incollare rich text o generare sezioni dinamiche.

// 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");
})();

Listener di eventi per le modifiche al documento

Scopo: mostra come monitorare eventi del documento come cambi di selezione o aggiornamenti del contenuto.

Caso d’uso: funzioni reattive, tracciamento azioni dell’utente o sincronizzazione con sistemi esterni.

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);
})();

Contenuto HTML ampio e annidato

Scopo: testa la gestione di HTML complesso con elementi annidati e tabelle.

Caso d’uso: generare report, migrare documenti formattati o creare layout avanzati.

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");
})();

Prima chiamata API semplice con casi limite

Scopo: introduce i principianti all’uso delle API, ai casi limite più comuni e ai pattern di gestione degli errori.

Caso d’uso: imparare le basi della Office JavaScript API, della Plugin API e della Automation API.

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

Consiglio da sviluppatore: quando usi la Plugin API con async/await, racchiudi le chiamate in blocchi try/catch, così eviti che errori come selezioni vuote o contenuti non supportati blocchino lo script e puoi mostrare messaggi utili nella console.

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

Istruzioni per l’uso e pratiche migliori

  • Esegui gli snippet uno alla volta per evitare conflitti.
  • Usa la console del browser per vedere i log di esecuzione e fare debug.
  • Scegli l’API giusta:

Creare documenti da zero → Office JavaScript API,

Sviluppare plugin → Plugin API,

Integrare app esterne → Automation API (Connector).

  • Sperimenta con formattazione, HTML ed eventi per capire bene il comportamento delle API.

Percorso di apprendimento consigliato

  1. Inizia con la prima chiamata API semplice per confrontare gli approcci.
  2. Passa alla inserimento di testo di base per capire le differenze tra le API.
  3. Prova l’inserimento HTML per la formattazione e il contenuto ricco.
  4. Esplora gli listener degli eventi per Automation e Plugin API.
  5. Procedi al contenuto HTML complesso per gestire strutture grandi e annidate.

Conclusione

Il Playground di ONLYOFFICE è uno strumento potente per imparare, testare e sviluppare plugin con le API. Grazie a un ambiente interattivo e isolato, permette agli sviluppatori di sperimentare in sicurezza, capire a fondo il comportamento delle API e creare plugin e flussi di automazione più solidi in meno tempo.

Link utili

Comincia con Playground

Come creare il tuo plugin

ONLYOFFICE su GitHub

Contribuisci a ONLYOFFICE

Crea il tuo account ONLYOFFICE gratuito

Visualizza, modifica e collabora su documenti, fogli, diapositive, moduli e file PDF online.