Étendre les fonctionnalités de Google Docs

Google Apps Script vous permet de créer et de modifier des documents Docs par programmation, ainsi que de personnaliser l'interface utilisateur avec de nouveaux menus, boîtes de dialogue et barres latérales.

Principes de base

Apps Script peut interagir avec Docs de deux manières générales : n'importe quel script peut créer ou modifier un document si l'utilisateur du script dispose des autorisations appropriées pour le document. Un script peut également être lié à un document, ce qui lui confère des capacités spéciales pour modifier l'interface utilisateur ou répondre lorsque le document est ouvert. Pour créer un script lié à un conteneur dans Docs, cliquez sur Extensions > Apps Script.

Dans les deux cas, vous pouvez interagir avec un document Docs à l'aide de Apps Script's Document Service, comme le montre l'exemple suivant.

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

Le script précédent crée un document dans le Google Drive de l'utilisateur, puis récupère l'onglet avec l'ID t.0 (le premier onglet par défaut), insère un paragraphe contenant le même texte que le nom du document, met en forme ce paragraphe en tant que titre et ajoute un tableau basé sur les valeurs d'un tableau bidimensionnel. Le script peut également apporter ces modifications à un document existant en remplaçant l'appel à DocumentApp.create par DocumentApp.openById ou openByUrl. Pour les scripts créés dans un document (lié à un conteneur), utilisez DocumentApp.getActiveDocument et Document.getActiveTab.

Structure d'un document

Du point de vue d'Apps Script, un document Docs est structuré comme un document HTML. Autrement dit, un document est composé d'un ou de plusieurs Tab objets, chacun contenant des éléments (comme un Paragraph ou Table) qui contiennent souvent d'autres éléments. La plupart des scripts qui modifient un document Docs commencent par un appel à getTab et asDocumentTab suivi de getBody, car le Body est un élément de base qui contient tous les autres éléments d'un onglet, à l'exception de la HeaderSection, FooterSection, et de toutes les Footnotes.

Toutefois, il existe des règles concernant les types d'éléments qui peuvent contenir d'autres types. De plus, le service de document d'Apps Script ne peut insérer que certains types d'éléments dans d'autres éléments. L'arborescence suivante montre les éléments qui peuvent être contenus par un certain type d'élément.

Les éléments affichés en gras peuvent être insérés. Les éléments non mis en gras ne peuvent être manipulés que sur place.

Remplacer le texte

Apps Script est souvent utilisé pour remplacer du texte dans Docs. Supposons que vous disposiez d'une feuille de calcul contenant des informations sur les clients et que vous souhaitiez générer un document Docs personnalisé pour chaque client. (Ce type d'opération est souvent appelé publipostage.)

Vous pouvez remplacer du texte à l'aide de la replaceText méthode, qui est compatible avec la plupart des fonctionnalités d'expression régulière JavaScript . Dans l'exemple suivant, la première fonction ajoute un texte d'espace réservé au document, et la seconde remplace ce texte par des propriétés d'un objet client.

Ces deux fonctions utilisent les getActiveDocument et getActiveTab méthodes, qui ne s'appliquent qu'aux scripts créés dans un document Docs . Dans un script autonome, utilisez plutôt DocumentApp.create, openById, ou openByUrl, combinés à Document.getTab, .

Ajouter des espaces réservés

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

Remplacer les espaces réservés

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

Menus et interfaces utilisateur personnalisés

Vous pouvez personnaliser Docs en ajoutant des menus personnalisés, des boîtes de dialogue et des barres latérales. N'oubliez pas qu'un script ne peut interagir qu'avec l'interface utilisateur du document auquel il est lié.

Pour en savoir plus sur la création d'interfaces personnalisées avec HTML et CSS, consultez le guide du service HTML. Si vous prévoyez de publier votre interface en tant que module complémentaire, suivez le guide de style pour vous assurer que son apparence est cohérente avec l'éditeur Docs.

Modules complémentaires pour Docs

Les modules complémentaires s'exécutent dans Docs et peuvent être installés depuis la boutique de modules complémentaires Docs. Si vous avez développé un script pour Docs et que vous souhaitez le partager avec le monde entier, Apps Script vous permet de le publier en tant que module complémentaire afin que d'autres utilisateurs puissent l'installer depuis la boutique de modules complémentaires.

Pour créer un module complémentaire pour Docs, consultez le guide de démarrage rapide pour créer des modules complémentaires Docs Docs.

Déclencheurs

Les scripts liés à un document Google peuvent utiliser un déclencheur simple pour répondre à l'événement onOpen du document, qui se produit chaque fois qu'un utilisateur disposant d'un accès en modification au document l'ouvre dans Docs.

Pour configurer le déclencheur, écrivez une fonction appelée onOpen. Pour obtenir un exemple de ce déclencheur, consultez Menus personnalisés dans Google Workspace. Bien que le déclencheur soit utile pour ajouter des menus, il ne peut pas utiliser de services Apps Script nécessitant une autorisation.