Cómo dominar las APIs de ONLYOFFICE con el Playground

26 noviembre 2025Por Dea

Probar y explorar las APIs de ONLYOFFICE puede ser complicado si tienes que configurar un plugin completo o un entorno de automatización para cada pequeño experimento. El Playground de la API de documentos de ONLYOFFICE proporciona un espacio dedicado donde los desarrolladores pueden interactuar con documentos mediante programación, probar comandos y comprender el comportamiento de la API en tiempo real.

En esta guía, mostraremos cómo el Playground acelera el desarrollo, destacaremos ejemplos prácticos y ofreceremos orientación para elegir la API adecuada según tus necesidades.

Cómo dominar las APIs de ONLYOFFICE con el Playground

Por qué el Playground es importante

El Playground está diseñado para desarrolladores que quieren:

  • Experimentar con diferentes APIs en un entorno de edición en vivo.
  • Insertar y manipular texto o contenido HTML mediante programación.
  • Monitorizar y responder a eventos del documento.
  • Probar casos límite, entradas grandes o caracteres especiales sin configurar un plugin o un entorno de conector completo.

Usar el Playground antes de construir un plugin o un flujo de automatización te ayuda a detectar posibles problemas desde el principio, entender las limitaciones de la API y optimizar tu proceso de desarrollo.

Comprender las APIs disponibles

El Playground es compatible con tres APIs principales:

  1. Office JavaScript API – Manipulación y creación directa de documentos, ideal para scripts, generación de documentos y tareas de automatización simples.
  2. Plugin API – Usada para crear plugins interactivos de ONLYOFFICE. Admite patrones async/await para una ejecución clara del código y operaciones complejas.
  3. Automation API / Connector – Usada por sistemas externos para acceder y modificar documentos, usando callbacks para integración y automatización.

Cada API cumple propósitos distintos, y el Playground te permite probarlas lado a lado para ver cuál se adapta mejor a tu flujo de trabajo.

Primeros pasos con fragmentos de código del Playground

A continuación se muestran ejemplos prácticos que demuestran cómo usar cada API. Copia un fragmento en el editor del Playground para ejecutarlo de inmediato.

Inserción básica de texto

Propósito: mostrar cómo insertar texto en la posición actual del cursor usando las tres APIs.

Caso de uso: inserción simple de texto en documentos o pruebas del comportamiento de la 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");

Consejo para desarrolladores: revisa siempre la respuesta de la API en la consola inmediatamente después de llamar a un método. Incluso operaciones simples como PasteText o PasteHtml pueden comportarse de manera diferente según la posición del cursor, la selección o la estructura HTML. Registrar los resultados ayuda a detectar comportamientos inesperados desde el principio.

Contenido HTML con formato

Propósito: Muestra cómo insertar contenido HTML enriquecido, incluidos encabezados, listas y estilos personalizados.

Caso de uso: Importar contenido formateado, pegar texto enriquecido o generar secciones dinámicamente.

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

Escuchadores de eventos para cambios en el documento

Propósito: demostrar cómo monitorizar eventos del documento, como cambios de selección o actualizaciones de contenido.

Caso de uso: crear funciones reactivas, rastrear acciones del usuario o sincronizar con 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);
})();

Contenido HTML grande y anidado

Propósito: Probar el manejo de estructuras HTML complejas con elementos anidados y tablas.

Caso de uso: Generar informes, migrar documentos formateados o crear diseños avanzados.

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

Primera llamada simple a la API con casos límite

Propósito: introducir a principiantes en el uso de la API, casos límite comunes y patrones de manejo de errores.

Caso de uso: aprender lo básico de Office JavaScript API, Plugin API y 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);
  }
})();

Consejo para desarrolladores: cuando uses la Plugin API con async/await, envuelve tus llamadas en bloques try/catch. Esto asegura que errores como selecciones indefinidas o contenido no compatible no rompan tu script y te permite proporcionar mensajes informativos en la consola para depuración.

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

Instrucciones de uso y mejores prácticas

  • Ejecuta los fragmentos individualmente para evitar conflictos.
  • Usa la consola del navegador para ver los registros de ejecución y depurar resultados.
  • Elige la API adecuada:

Crear documentos desde cero → Office JavaScript API

Desarrollar plugins → Plugin API

Integración con aplicaciones externas → Automation API (Connector)

  • Experimenta con formato, HTML y eventos para comprender a fondo el comportamiento de la API

Ruta de aprendizaje recomendada

  1. Comienza con la primera llamada simple a la API para comparar enfoques.
  2. Continúa con la inserción básica de texto para comprender las diferencias entre las APIs.
  3. Prueba la inserción de HTML para trabajar con formato y contenido enriquecido.
  4. Explora los escuchadores de eventos en las APIs de Automation y Plugin.
  5. Avanza hacia contenido HTML complejo para manejar estructuras grandes y anidadas.

Conclusión

El ONLYOFFICE Playground es una herramienta poderosa para acelerar el aprendizaje de las APIs, las pruebas y el desarrollo de plugins. Al proporcionar un entorno interactivo y aislado, permite a los desarrolladores experimentar de forma segura, comprender en profundidad el comportamiento de las APIs y crear plugins y flujos de automatización robustos de manera más eficiente.

Enlaces útiles

Comenzar con el Playground

Cómo crear tu propio plugin

ONLYOFFICE en GitHub

Cómo contribuir a ONLYOFFICE

#API

Crea tu cuenta gratuita de ONLYOFFICE

Visualiza, edita y colabora en documentos, hojas, diapositivas, formularios y archivos PDF en línea.