Ovladavanje ONLYOFFICE API-jima uz Playground

27 November 2025By Natalija Blagojevic

Testiranje i istraživanje ONLYOFFICE API-ja može biti izazovno ako morate da postavite kompletno okruženje dodatka ili automatizacije za svaki mali eksperiment. ONLYOFFICE docs API Playground pruža posebno okruženje gde programeri mogu da rade s dokumentima programatski, isprobavaju komande i razumeju ponašanje API-ja u realnom vremenu.

U ovom vodiču pokazaćemo kako Playground ubrzava razvoj, predstavićemo praktične primere i dati smernice za izbor odgovarajućeg API-ja prema vašim potrebama.

Mastering ONLYOFFICE APIs with Playground

Zašto je Playground važan

Playground je napravljen za programere koji žele da:

Eksperimentišu sa različitim API-jima u živom okruženju uređivača;
Ubacuju i manipulišu tekstom ili HTML sadržajem programatski;
Prate i reaguju na događaje u dokumentu;
Testiraju granične slučajeve, velike ulaze ili specijalne karaktere bez postavljanja kompletnog dodatka ili konektor-okruženja.

Korišćenje Playground-a pre izrade dodatka ili automatizovanog toka rada pomaže da rano otkrijete potencijalne probleme, bolje razumete ograničenja API-ja i ubrzate proces razvoja.

Razumevanje dostupnih API-ja

Playground podržava tri glavna API-ja:

Office JavaScript API – Direktna izgradnja i manipulacija dokumentima, idealno za skripte, generisanje dokumenata i jednostavne automatizacije.
Plugin API – Koristi se za izradu interaktivnih ONLYOFFICE dodataka. Podržava async/await obrasce za čisto izvršavanje koda i složenije operacije.
Automation API / Konektor – Služi eksternim sistemima da pristupe i menjaju dokumente, koristeći callback funkcije za integracije i automatizaciju.

Svaki API ima svoju namenu, a Playground vam omogućava da ih testirate paralelno i odredite koji najbolje odgovara vašem toku rada.

Početak rada sa Playground snippettima

U nastavku su praktični primeri kako koristiti svaki API. Kopirajte snippet u Playground editor i pokrenite ga odmah.

Osnovno umetanje teksta

Svrha: Pokazuje umetanje teksta na trenutnu poziciju kursora u sva tri API-ja.

Upotreba: Jednostavno umetanje teksta u dokument ili testiranje ponašanja API-ja.

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

Developer savet: Uvek proverite API odgovor u konzoli odmah nakon poziva metode. Čak i jednostavne operacije kao što su PasteText ili PasteHtml mogu se različito ponašati u zavisnosti od pozicije kursora, selekcije ili HTML strukture. Logovanje rezultata pomaže da rano otkrijete nepredviđeno ponašanje.

HTML sadržaj sa formatiranjem

Svrha: Prikazuje kako umetnuti bogat HTML sadržaj, uključujući naslove, liste i prilagođene stilove.

Upotreba: Uvoz formatiranog sadržaja, lepljenje bogatog teksta ili dinamičko generisanje sekcija.

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

Slušači događaja za izmene u dokumentu

Svrha: Prikazuje praćenje događaja kao što su promene selekcije ili ažuriranja sadržaja.

Upotreba: Izgradnja interaktivnih funkcija, praćenje radnji korisnika ili sinhronizacija sa eksternim sistemima.

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

Veliki i ugnježdeni HTML sadržaj

Svrha: Testira rukovanje složenim HTML strukturama sa ugnježdenim elementima i tabelama.

Upotreba: Generisanje izveštaja, migracija formatiranih dokumenata, kreiranje naprednih rasporeda.

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

Jednostavan prvi API poziv sa graničnim slučajevima

Svrha: Uvodi početnike u korišćenje API-ja, česte granične slučajeve i obrasce za rukovanje greškama.

Upotreba: Učenje osnova Office JavaScript API, Plugin API, i 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);
  }
})();

Developer savet: Kada koristite Plugin API uz async/await, obavezno okružite pozive try/catch blokovima. Ovo sprečava da greške poput nedefinisane selekcije ili nepodržanog sadržaja prekinu skriptu, a omogućava vam da u konzoli prikažete korisne poruke za debugovanje.

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

Uputstva i najbolje prakse

Pokrećite snippete pojedinačno da izbegnete konflikte.
Koristite konzolu pregledača za prikaz logova i debug rezultata.
Izaberite pravi API:

Izgradnja dokumenata od nule → Office JavaScript API,

Razvoje plugin-ova → Plugin API,

Integracija sa eksternim aplikacijama → Automation API (Connector).

Eksperimentišite sa formatiranjem, HTML-om i događajima da biste detaljno razumeli ponašanje API-ja.

Preporučeni put učenja

Počnite sa simple first API call da uporedite pristupe.
Nastavite sa osnovnim umetanjem teksta da razumete razlike među API-jima.
Testirajte umetanje HTML-a za formatirani sadržaj.
Istražite event listenere u Automation i Plugin API-jima.
Pređite na složen HTML sadržaj za rad sa velikim, ugnježdenim strukturama.

Zaključak

ONLYOFFICE Playground je moćan alat za ubrzano učenje API-ja, testiranje i razvoj dodataka. Omogućava programerima da eksperimentišu bez rizika, bolje razumeju ponašanje API-ja i brže razviju stabilne dodatke i automatizovane tokove rada.