Ampliación de Documentos de Google

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

Conceptos básicos

Apps Script puede interactuar con Documentos de Google de dos maneras principales: 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 se puede vincular 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 de Google, haz clic en Extensiones > Apps Script.

En cualquier caso, es sencillo interactuar con un documento de Documentos 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 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 y, 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, aplica un diseño a ese párrafo como encabezado y agrega una tabla basada en los valores de un array de dos dimensiones. La secuencia de comandos podría hacer estos cambios en un documento existente con la misma facilidad si se reemplazara la llamada a DocumentApp.create() por DocumentApp.openById() o openByUrl(). Para las secuencias de comandos creadas dentro de un documento (vinculadas a un contenedor), usa DocumentApp.getActiveDocument() y Document.getActiveTab().

Estructura de un documento

Desde la perspectiva de Apps Script, un documento de Documentos de Google está estructurado de manera 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 de Google comienzan con una llamada a getTab() y asDocumentTab(), seguidas de getBody(), ya que Body es un elemento principal 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. Además, el servicio de documentos en Apps Script solo puede insertar ciertos tipos de elementos en otros. En el siguiente árbol, se muestran los elementos que puede contener un tipo de elemento determinado.

Se pueden insertar los elementos que aparecen en negrita. Los elementos que no están en negrita solo se pueden manipular en su lugar.

Reemplaza el texto

Apps Script se usa a menudo para reemplazar texto en Documentos de Google. Supongamos que tienes una hoja de cálculo repleta de información del cliente y quieres generar un Documento de Google personalizado para cada cliente. (Este tipo de operación suele denominarse combinación de correspondencia).

Existen muchas formas de reemplazar texto, pero la más sencilla 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 se muestra a continuación agrega varias líneas de texto de marcador de posición a un documento de Documentos de Google. En la vida 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 propiedades definidas en el objeto client.

Ten en cuenta que 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 de Google. 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 y interfaces de usuario personalizados

Puedes personalizar Documentos de Google agregando 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 está vinculada al documento.

Descubre cómo agregar menús personalizados y diálogos a Documentos de Google. Para obtener más información sobre cómo crear interfaces personalizadas para un diálogo o una barra lateral, consulta la guía del servicio HTML. Si planeas 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 quieres compartirla con el mundo, Apps Script te permite publicarla como un complemento para que otros usuarios puedan instalarla desde la tienda de complementos.

Para ver cómo puedes crear un complemento para Documentos de Google, consulta la guía de inicio rápido para crear 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 se produce 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(). Para ver un ejemplo de este activador, consulta Menús personalizados en Google Workspace. Aunque el activador simple es útil para agregar menús, no puede usar ningún servicio de Apps Scripts que requiera autorización.