Extension de Google Docs

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

Principes de base

Apps Script peut interagir avec Google Docs de deux manières principales: tout 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 donne 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 depuis Google Docs, cliquez sur Extensions > Apps Script.

Dans les deux cas, il est simple d'interagir avec un document Google Docs via le service de documents d'Apps Script, comme l'illustre 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 ci-dessus crée un document dans Google Drive de l'utilisateur, puis récupère l'onglet avec l'ID t.0 (premier onglet par défaut), insère un paragraphe contenant le même texte que le nom du document, stylise ce paragraphe en tant qu'en-tête et ajoute un tableau basé sur les valeurs d'un tableau à deux dimensions. Le script pourrait tout aussi facilement 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és au conteneur), utilisez DocumentApp.getActiveDocument() et Document.getActiveTab().

Structure d'un document

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

Toutefois, il existe des règles concernant les types d'éléments pouvant contenir d'autres types. De plus, le service de documents dans Apps Script ne peut insérer que certains types d'éléments dans d'autres éléments. L'arborescence ci-dessous indique les éléments pouvant être contenus par un type d'élément donné.

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

Remplacer du texte

Apps Script est souvent utilisé pour remplacer du texte dans Google Docs. Imaginons que vous disposiez d'une feuille de calcul remplie d'informations sur les clients et que vous souhaitiez générer un document Google Docs personnalisé pour chacun d'eux. (Ce type d'opération est souvent appelé "fusion de courriers".)

Il existe de nombreuses façons de remplacer du texte, mais la plus simple est la méthode replaceText() illustré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 de texte d'espace réservé à un document Google Docs. Dans la pratique, vous êtes plus susceptible de saisir vous-même 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 les méthodes getActiveDocument() et getActiveTab(), qui ne s'appliquent qu'aux scripts créés dans un document Google 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 Google Docs en ajoutant des menus, des boîtes de dialogue et des barres latérales. N'oubliez pas, cependant, qu'un script ne peut interagir qu'avec l'UI de l'instance actuelle d'un document ouvert, et uniquement si le script est lié au document.

Découvrez comment ajouter des menus et des boîtes de dialogue personnalisés à vos documents 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 composant complémentaire, suivez le guide de style pour assurer la 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 depuis le catalogue de modules complémentaires Google Docs. 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 le publier en tant que module complémentaire afin que d'autres utilisateurs puissent l'installer depuis la plate-forme de téléchargement dédiée.

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

Déclencheurs

Les scripts associés à un document Google Docs 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 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 les services Apps Scripts qui nécessitent une autorisation.