Extiende Documentos de Google

Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.

Google Apps Script te permite crear y modificar Documentos de Google de manera programática, como también personalizar la interfaz de usuario con nuevos menús, cuadros de diálogo y barras laterales.

Conceptos básicos

Apps Script puede interactuar con Documentos de Google de dos maneras: cualquier secuencia de comandos puede crear o modificar un documento si el usuario de la secuencia de comandos tiene los permisos adecuados para el documento, y una secuencia de comandos también puede estar vinculada a un documento, lo que le otorga una capacidad especial para modificar la interfaz de usuario o responder cuando se abre el documento. Para crear una secuencia de comandos vinculada a un contenedor desde Documentos de Google, haz clic en Extensiones Apps Script.

En ambos casos, es fácil interactuar con un Documento de Google a través del Servicio de Documentos de Apps Script, como se muestra en el siguiente ejemplo.

function createDoc() {
  var doc = DocumentApp.create('Sample Document');
  var body = doc.getBody();
  var rowsData = [['Plants', 'Animals'], ['Ficus', 'Goat'], ['Basil', 'Cat'], ['Moss', 'Frog']];
  body.insertParagraph(0, doc.getName())
      .setHeading(DocumentApp.ParagraphHeading.HEADING1);
  table = body.appendTable(rowsData);
  table.getRow(0).editAsText().setBold(true);
}

La secuencia de comandos anterior crea un documento nuevo en la unidad de Google Drive del usuario y, luego, inserta un párrafo que contiene el mismo texto que el nombre del documento, estilos que se incluyen como encabezado y agrega una tabla basada en los valores de un arreglo bidimensional. La secuencia de comandos podría realizar estos cambios en un documento existente de manera muy sencilla reemplazando la llamada a DocumentApp.create() por DocumentApp.openById() o openByUrl(). Para las secuencias de comandos creadas dentro de un documento (vinculado con un contenedor), usa DocumentApp.getActiveDocument().

Estructura de un documento

Desde la perspectiva de Apps Script, un documento de Google se estructura de manera muy similar a un documento HTML, es decir, un documento de Google consta de elementos (como Paragraph o Table) que suelen contener otros elementos. La mayoría de las secuencias de comandos que modifican un documento de Google comienzan con una llamada a getBody(), porque Body es un elemento principal que contiene todos los demás elementos, excepto HeaderSection, FooterSection y cualquier Footnotes.

Sin embargo, existen reglas que determinan los tipos de elementos que pueden contener otros tipos. Además, el servicio de documentos en Apps Script solo puede insertar ciertos tipos de elementos. El siguiente árbol muestra los elementos que puede contener un tipo determinado de elemento.

Se pueden insertar los elementos que aparecen en negrita; los elementos que no están en negrita solo pueden manipularse en su lugar.

Reemplazar texto

A menudo, Apps Script se usa para reemplazar texto en Documentos de Google. Supongamos que tienes una hoja de cálculo llena de información del cliente y deseas generar un documento de Google personalizado para cada cliente. (A menudo, este tipo de operación se denomina combinación de correo).

Hay muchas formas de reemplazar el texto, pero la más simple es el método replaceText(), que se muestra en el siguiente ejemplo. replaceText admite la mayoría de las funciones de expresión regular de JavaScript. La primera función que aparece a continuación agrega varias líneas de texto de marcador de posición a un documento de Google. En el mundo real, es más probable que escribas los marcadores de posición en el documento. La segunda función reemplaza los marcadores de posición por las propiedades definidas en el objeto client.

Ten en cuenta que ambas funciones usan el método getActiveDocument(), que solo se aplica a las secuencias de comandos creadas dentro de un documento de Google. En una secuencia de comandos independiente, usa DocumentApp.create(), openById() o openByUrl().

Agrega algunos marcadores de posición

function createPlaceholders() {
  var body = DocumentApp.getActiveDocument().getBody();
  body.appendParagraph('{name}');
  body.appendParagraph('{address}');
  body.appendParagraph('{city} {state} {zip}');
}

Reemplazar los marcadores de posición

function searchAndReplace() {
  var body = DocumentApp.getActiveDocument()
      .getBody();
  var client = {
    name: 'Joe Script-Guru',
    address: '100 Script Rd',
    city: 'Scriptville',
    state: 'GA',
    zip: 94043
  };

  body.replaceText('{name}', client.name);
  body.replaceText('{address}', client.address);
  body.replaceText('{city}', client.city);
  body.replaceText('{state}', client.state);
  body.replaceText('{zip}', client.zip);
}

Interfaces de usuario y menús personalizados

Para personalizar Documentos de Google, agrega menús, cuadros de diálogo y barras laterales. Sin embargo, ten en cuenta que una secuencia de comandos solo puede interactuar con la IU de la instancia actual de un documento abierto y solo si la secuencia de comandos está vinculada al documento.

Consulta cómo agregar menús personalizados y diálogos a tus Documentos de Google. Si quieres obtener más información sobre cómo crear interfaces personalizadas para un diálogo o una barra lateral, consulta la guía de servicio de HTML. Si piensas publicar tu interfaz personalizada como parte de un complemento, sigue la guía de estilo para mantener la coherencia con el estilo y el diseño del editor de Documentos de Google.

Complementos para Documentos de Google

Los complementos se ejecutan en Documentos de Google y se pueden instalar desde la tienda de complementos de Documentos de Google. Si desarrollaste una secuencia de comandos para Documentos de Google y deseas compartirla con el mundo, Apps Script te permite publicar tu secuencia de comandos como un complemento a fin de que otros usuarios puedan instalarla desde la tienda de complementos.

Si deseas ver cómo puedes crear un complemento de Documentos de Google, consulta la guía de inicio rápido para compilar complementos de Documentos.

Activadores

Las secuencias de comandos que están vinculadas a un documento de Google pueden usar un activador simple para responder al evento onOpen del documento, que ocurre cada vez que un usuario que tiene acceso de edición al documento lo abre en Documentos de Google.

Para configurar el activador, escribe una función llamada onOpen(). El código del menú anterior muestra un ejemplo de este activador. Si bien el activador simple es útil para agregar menús, no puede usar ningún servicio de Apps Script que requiera autorización.