Extiende Documentos de Google

Google Apps Script te permite crear y modificar documentos de forma programática, así como 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 dos maneras generales: cualquier secuencia de comandos puede crear o modificar un documento si el usuario de la secuencia tiene los permisos adecuados para el documento, y una secuencia de comandos también puede estar vinculada a un documento, lo que le otorga habilidades especiales para alterar la interfaz de usuario o responder cuando se abre el documento. Para crear una secuencia de comandos vinculada a un contenedor desde Documentos, haz clic en Extensiones > Apps Script.

En cualquier caso, puedes interactuar con un documento de Docs usando el Servicio de Documentos de Apps Script, como se demuestra en el siguiente ejemplo.

function createDoc() {
  var doc = DocumentApp.create('Sample Document');
  var documentTab = doc.getTab('t.0').asDocumentTab();
  var body = documentTab.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 Google Drive del usuario, luego recupera la pestaña con el ID t.0 (la primera pestaña predeterminada), inserta un párrafo que contiene el mismo texto que el nombre del documento, le aplica el estilo de encabezado a ese párrafo y agrega una tabla basada en los valores de un array bidimensional. La secuencia de comandos también podría realizar estos cambios en un documento existente reemplazando la llamada a DocumentApp.create por DocumentApp.openById o openByUrl. Para las secuencias de comandos creadas dentro de un documento (vinculadas al contenedor), usa DocumentApp.getActiveDocument y Document.getActiveTab.

Estructura de un documento

Desde la perspectiva de Apps Script, un documento de Documentos se estructura de forma muy similar a un documento HTML, es decir, un documento se compone de uno o más objetos Tab, cada uno de los cuales contiene elementos (como un Paragraph o un Table) que a menudo contienen otros elementos. La mayoría de las secuencias de comandos que modifican un documento de Documentos comienzan con una llamada a getTab y asDocumentTab, seguida de getBody, ya que Body es un elemento central que contiene todos los demás elementos de una pestaña, excepto HeaderSection, FooterSection y cualquier Footnotes.

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

Los elementos que se muestran en negrita se pueden insertar, mientras que los que no están en negrita solo se pueden manipular en su lugar.

Reemplazar texto

Apps Script se suele usar para reemplazar texto en Documentos. Supongamos que tienes una hoja de cálculo llena de información del cliente y deseas generar un documento personalizado para cada cliente. (Este tipo de operación suele llamarse combinación de correspondencia).

Puedes reemplazar texto con el método replaceText, que admite la mayoría de las funciones de expresión regular de JavaScript. En el siguiente ejemplo, la primera función agrega texto de marcador de posición al documento, y la segunda reemplaza ese texto por propiedades de un objeto client.

Ambas funciones usan los métodos getActiveDocument y getActiveTab, que solo se aplican a las secuencias de comandos creadas dentro de un documento de Documentos. En una secuencia de comandos independiente, usa DocumentApp.create, openById o openByUrl, combinados con Document.getTab.

Agrega algunos marcadores de posición

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

Reemplaza los marcadores de posición

function searchAndReplace() {
  var body = DocumentApp.getActiveDocument().getActiveTab().asDocumentTab().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);
}

Menús e interfaces de usuario personalizados

Puedes personalizar Documentos agregando menús personalizados, cuadros de diálogo y barras laterales. Ten en cuenta que una secuencia de comandos solo puede interactuar con la IU del documento al que está vinculada.

Para obtener más información sobre cómo crear interfaces personalizadas con HTML y CSS, consulta la guía del servicio HTML. Si planeas publicar tu interfaz como un complemento, sigue la guía de estilo para garantizar que su apariencia sea coherente con el editor de Documentos.

Complementos para Documentos

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

Para crear un complemento para Documentos, consulta la guía de inicio rápido para crear complementos de Documentos.

Activadores

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

Para configurar el activador, escribe una función llamada onOpen. Para ver un ejemplo de este activador, consulta Menús personalizados en Google Workspace. Si bien el activador es útil para agregar menús, no puede usar ningún servicio de Apps Script que requiera autorización.