Dominando as APIs do ONLYOFFICE com o Playground

28 novembro 2025Por Klaibson

Testar e explorar as APIs do ONLYOFFICE pode ser um desafio se você tiver que configurar um plugin completo ou um ambiente de automação para cada pequeno experimento. O ONLYOFFICE docs API Playground oferece um espaço dedicado onde os desenvolvedores podem interagir com documentos programaticamente, experimentar comandos e entender o comportamento da API em tempo real.

Neste guia, mostraremos como o Playground acelera o desenvolvimento, destacaremos exemplos práticos e forneceremos orientações para escolher a API certa para suas necessidades.

Dominando as APIs do ONLYOFFICE com o Playground

Por que o Playground é importante

O Playground foi projetado para desenvolvedores que desejam:

  • Experimente diferentes APIs em um ambiente de editor ao vivo.
  • Insira e manipule texto ou conteúdo HTML programaticamente.
  • Monitorar e responder a eventos relacionados a documentos.
  • Teste casos extremos, entradas grandes ou caracteres especiais sem configurar um ambiente completo de plug-in ou conector.

Usar o Playground antes de criar um plug-in ou fluxo de trabalho de automação ajuda você a detectar possíveis problemas antecipadamente, entender as restrições da API e otimizar seu processo de desenvolvimento.

Entendendo as APIs disponíveis

O Playground suporta três APIs principais:

  1. Office JavaScript API – Criação e manipulação direta de documentos, ideal para scripts, geração de documentos e tarefas simples de automação.
  2. Plugin API – Usado para criar plug-ins interativos ONLYOFFICE. Suporta padrões async/await para execução de código limpo e operações complexas.
  3. Automation API / Connector – Usado para sistemas externos acessarem e modificarem documentos, usando callbacks para integração e automação.

Cada API tem finalidades distintas, e o Playground permite que você as teste lado a lado para ver qual se adapta melhor ao seu fluxo de trabalho.

Introdução aos trechos do Playground

Abaixo estão exemplos práticos que demonstram como usar cada API. Copie um trecho no editor do Playground para executá-lo imediatamente.

Inserção de texto básico

Objetivo: Demonstra como inserir texto na posição atual do cursor usando as três APIs.

Caso de uso: inserção simples de texto em documentos ou teste do comportamento da 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");

Dica para desenvolvedores: sempre verifique a resposta da API no console imediatamente após chamar um método. Mesmo operações simples como PasteText ou PasteHtml podem se comportar de maneira diferente dependendo da posição do cursor, da seleção ou da estrutura HTML. Registrar os resultados ajuda a detectar comportamentos inesperados antecipadamente.

Conteúdo HTML com formatação

Objetivo: Mostra como inserir conteúdo HTML avançado, incluindo títulos, listas e estilos personalizados.

Caso de uso: importe conteúdo formatado, cole texto rico ou gere seções dinamicamente.

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

Ouvintes de eventos para alterações em documentos

Objetivo: Demonstra o monitoramento de eventos de documentos, como alterações de seleção ou atualizações de conteúdo.

Caso de uso: crie recursos responsivos, acompanhe as ações dos usuários ou sincronize com sistemas externos.

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

Conteúdo HTML grande e aninhado

Objetivo: Testa o manuseio de estruturas HTML complexas com elementos e tabelas aninhados.

Caso de uso: Gerar relatórios, migrar documentos formatados ou criar layouts avançados.

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

Primeira chamada de API simples com casos extremos

Objetivo: Apresenta aos iniciantes o uso da API, casos extremos comuns e padrões de tratamento de erros.

Caso de uso: Aprenda o básico sobre Office JavaScript API, Plugin API, e 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);
  }
})();

Dica para desenvolvedores: ao usar a API do plug-in com async/await, envolva suas chamadas em blocos try/catch. Isso garante que erros como seleções indefinidas ou conteúdo não compatível não interrompam seu script e permite que você forneça mensagens informativas no console para depuração.

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

Instruções de uso e melhores práticas

  • Execute trechos individualmente para evitar conflitos.
  • Use o console do navegador para visualizar os registros de execução e os resultados da depuração.
  • Escolha a API certa:

Crie documentos do zero → API JavaScript do Office,

Desenvolver plugins → API do plugin,

Integrar com aplicativos externos → API de automação (conector).

  • Experimente formatação, HTML e eventos para entender completamente o comportamento da API.

Caminho de aprendizagem recomendado

  1. Comece com a primeira chamada de API simples para comparar abordagens.
  2. Passe para a inserção de texto básico para entender as diferenças entre as APIs.
  3. Teste a inserção de html para formatação e conteúdo avançado.
  4. Explore os ouvintes de eventos para APIs de automação e plug-ins.
  5. Avance para conteúdo html complexo para lidar com estruturas grandes e aninhadas.

Conclusão

O ONLYOFFICE Playground é uma ferramenta poderosa para acelerar o aprendizado, o teste e o desenvolvimento de plug-ins de API. Ao fornecer um ambiente interativo e isolado, ele permite que os desenvolvedores experimentem com segurança, compreendam o comportamento da API em profundidade e criem plug-ins robustos e fluxos de trabalho de automação com mais eficiência.

Links úteis

Comece agora mesmo com Playground

Como criar seu próprio plugin

ONLYOFFICE no GitHub

Contribua para o ONLYOFFICE

#API

Crie sua conta gratuita no ONLYOFFICE

Visualize, edite e colabore em documentos, planilhas, slides, formulários e arquivos PDF online.