Interfaces en Cards via CardService

1. Qu’est-ce que CardService et à quoi cela sert ?

CardService est un service natif d’Apps Script permettant de gérer un type d’interface ne nécessitant pas de HTML ou de CSS, et reposant sur un système de « cards ». Une card est un bloc d’interface structuré, pouvant contenir des éléments visuels comme du texte, des boutons, des champs de saisie ou des listes. CardService fournit les classes nécessaires pour créer ces cards, y ajouter des widgets, des boutons, etc.

Cette simplicité implique des limites. Vous ne pouvez pas injecter votre propre CSS ni du JavaScript côté client. Les widgets proposés par Google sont les seuls disponibles. C’est une contrainte, mais elle garantit une cohérence graphique et une compatibilité parfaite dans tous les hôtes.

Ce service est réservé à deux environnements précis : les modules complémentaires Google Workspace et les applications Google Chat. Vous ne pouvez donc pas l’utiliser dans une simple application web ni dans un script autonome.

2. Créer un environnement de test type module complémentaire

Avant de pouvoir tester CardService, il est nécessaire de travailler dans un environnement adapté : celui d’un module complémentaire Google Workspace (ou application Google Chat). En effet...

1. Créer une Card simple

Plutôt que d’afficher un simple message de bienvenue, faisons en sorte que notre première Card reflète déjà l’idée du projet fil rouge : un gestionnaire de tâches lié à une feuille Google Sheets.

On garde une structure minimaliste, mais cette fois avec un en-tête adapté et un texte qui annonce la suite.

function onHomepage(e) { 
  const header = CardService.newCardHeader() 
    .setTitle("Task Manager") 
    .setSubtitle("Suivi des tâches dans Sheets"); 
 
  const text = CardService.newTextParagraph() 
    .setText("Ce module complémentaire affichera bientôt la liste 
 des tâches extraites de votre feuille. Pour l'instant, il s'agit 
simplement d'un aperçu."); 
 
  const section = CardService.newCardSection() 
    .addWidget(text); 
 
  return CardService.newCardBuilder() 
    .setHeader(header) 
    .addSection(section) 
    .build(); 
} 

Une fois la fonction enregistrée, il n’est pas nécessaire de rafraîchir le tableur ni de redéployer le projet.

Regardons maintenant le code de plus près. Le principe de CardService repose sur une série d’objets que l’on construit étape par étape grâce à des builders. Chaque élément, qu’il s’agisse...

1. Navigation

Un module complémentaire contient souvent plus d’une Card figée. Il peut en présenter plusieurs, comme un mini-flux de navigation.

Par exemple, notre gestionnaire de tâches (Task Manager) pourrait afficher une Card principale avec la liste des tâches et, lorsqu’on clique sur une tâche, ouvrir une Card de détails :

function onHomepage(e) { 
  const header = CardService.newCardHeader() 
    .setTitle("Task Manager") 
    .setSubtitle("Tasks overview in Sheets"); 
 
  const sheet = SpreadsheetApp.getActiveSpreadsheet().getSheetByName("Tasks"); 
  const data = sheet.getRange(2, 1, sheet.getLastRow() - 1, 4).getValues(); 
 
  const taskSection = CardService.newCardSection().setHeader 
("My tasks"); 
 
  data.forEach(row => { 
    const [id, name, dueDate, status] = row; 
 
    const openDetailsButton = CardService.newTextButton() 
      .setText(name) 
      .setOnClickAction( 
        CardService.newAction() 
          .setFunctionName("openTaskDetails") 
          .setParameters({ taskId: String(id) }) 
      ); 
 
    taskSection.addWidget(openDetailsButton); 
  }); 
 
  return CardService.newCardBuilder() 
    .setHeader(header) 
    .addSection(taskSection) 
    .build(); 
} 
 
function openTaskDetails(e) { ...