Extension de Google Docs

Google Apps Script vous permet de créer et de modifier Google Docs par programmation. Vous pouvez également personnaliser l'interface utilisateur à l'aide de nouveaux menus, boîtes de dialogue et barres latérales.

Principes de base

Apps Script peut interagir avec Google Docs de deux manières différentes: tout script peut créer ou modifier un document si l'utilisateur du script dispose des autorisations appropriées, et un script peut également être lié à un document, ce qui lui donne les capacités spéciales de modifier l'interface utilisateur ou de répondre à l'ouverture du document. Pour créer un script lié à un conteneur depuis Google Docs, cliquez sur Extensions > Apps Script.

Dans les deux cas, l'interaction avec un document Google Docs via le service Document d'Apps Script est très simple, comme le montre l'exemple suivant.

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

Le script ci-dessus crée un document dans le Google Drive de l'utilisateur, insère un paragraphe qui contient le même texte que le nom du document, applique un style à ce paragraphe comme en-tête et ajoute une table en fonction des valeurs dans un tableau bidimensionnel. Le script peut tout aussi facilement apporter ces modifications à un document existant en remplaçant l'appel de DocumentApp.create() par DocumentApp.openById() ou openByUrl(). Pour les scripts créés dans un document (lié à un conteneur), utilisez DocumentApp.getActiveDocument().

Structure d'un document

Du point de vue d'Apps Script, un document Google Docs est structuré comme un document HTML, c'est-à-dire qu'il est composé d'éléments (tels que Paragraph ou Table) qui contiennent souvent d'autres éléments. La plupart des scripts qui modifient un document Google Docs commencent par appeler getBody(), car Body est un élément maître contenant tous les autres éléments, à l'exception de HeaderSection, FooterSection et de tout autre élément Footnotes.

Toutefois, il existe des règles précisant quels types d'éléments peuvent contenir d'autres types. De plus, le service Document de Apps Script ne peut insérer que certains types d'éléments. L'arborescence ci-dessous montre quels éléments peuvent être contenus dans un certain type d'élément.

Vous pouvez insérer des éléments en gras. Les éléments qui ne sont pas en gras ne peuvent être manipulés que sur place.

Remplacement du texte

Apps Script est souvent utilisé pour remplacer du texte dans Google Docs. Imaginons que vous disposiez d'une feuille de calcul comportant de nombreuses informations sur les clients et que vous souhaitiez générer un document Google Docs personnalisé pour chaque client. Ce type d'opération est souvent appelé fusion d'e-mails.

Il existe de nombreuses façons de remplacer du texte, mais la plus simple est la méthode replaceText() présentée dans l'exemple ci-dessous. replaceText est compatible avec la plupart des fonctionnalités d'expression régulière de JavaScript. La première fonction ci-dessous ajoute plusieurs lignes d'espace réservé à un document Google Docs. En situation réelle, vous auriez plus de chances de saisir les espaces réservés dans le document. La deuxième fonction remplace les espaces réservés par les propriétés définies dans l'objet client.

Notez que ces deux fonctions utilisent la méthode getActiveDocument(), qui ne s'applique qu'aux scripts créés dans un document Google Docs. Dans un script autonome, utilisez plutôt DocumentApp.create(), openById() ou openByUrl().

Ajouter des espaces réservés

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

Remplacer les espaces réservés

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

Menus personnalisés et interfaces utilisateur

Vous pouvez personnaliser Google Docs en ajoutant des menus, des boîtes de dialogue et des barres latérales. Toutefois, n'oubliez pas qu'un script ne peut interagir avec l'interface utilisateur de l'instance actuelle d'un document ouvert que s'il est lié au document.

Découvrez comment ajouter des menus personnalisés et des boîtes de dialogue à Google Docs. Pour en savoir plus sur la création d'interfaces personnalisées pour une boîte de dialogue ou une barre latérale, consultez le guide du service HTML. Si vous prévoyez de publier votre interface personnalisée dans le cadre d'un module complémentaire, suivez le guide de style pour plus de cohérence avec le style et la mise en page de l'éditeur Google Docs.

Modules complémentaires pour Google Docs

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

Pour savoir comment créer un module complémentaire pour Google Docs, consultez le guide de démarrage rapide pour la création de modules complémentaires Docs.

Triggers

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

Pour configurer le déclencheur, il vous suffit d'écrire 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 simple soit utile pour ajouter des menus, il ne peut pas utiliser de services Apps Script nécessitant une autorisation.