Chips intelligents

Ce guide explique comment et pourquoi utiliser l'API Google Sheets pour ajouter et gérer des chips intelligents dans vos feuilles de calcul.

Qu'est-ce qu'un chip intelligent ?

Les chips intelligents vous permettent d'intégrer des données interactives et enrichies provenant d'autres applications Google Workspace directement dans Sheets. Ils offrent aux utilisateurs un accès rapide aux informations et aux actions, transformant un lien de cellule en objet dynamique. Pour en savoir plus, consultez Insérer des chips intelligents dans Google Sheets.

Ajouter un chip intelligent

Les chips sont représentés sous forme de séquences de chips, qui font partie de CellData. Vous pouvez donc insérer un chip à l'aide de la méthode spreadsheets.batchUpdate existante en fournissant un UpdateCellsRequest ou un AppendCellsRequest.

La requête doit inclure le champ chipRuns. Une séquence de chips décrit les propriétés d'un chip et son emplacement dans le texte de la cellule.

Lorsque vous écrivez chipRuns, vous devez également fournir un userEnteredValue contenant des caractères d'espace réservé (@) pour chaque chip que vous souhaitez ajouter. Chaque séquence du tableau chipRuns correspond à l'un des espaces réservés. Les séquences sans chip peuvent être omises lors de l'écriture.

L'exemple suivant montre comment écrire un chip de fichier, un chip de contact et du texte brut dans une seule cellule, A1. * {JSON}

        {
          "updateCells": {
            "rows": [
              {
                "values": [
                  {
                    "userEnteredValue": {
                      "stringValue": "@ is the owner of @."
                    },
                    "chipRuns": [
                      {
                        "chip": {
                          "personProperties": {
                            "email": "johndoe@gmail.com",
                            "displayFormat": "DEFAULT"
                          }
                        }
                      },
                      {
                        "startIndex": 18,
                        "chip": {
                          "richLinkProperties": {
                            "uri": "https://docs.google.com/document/d/YOUR_DOCUMENT_ID/edit"
                          }
                        }
                      }
                    ]
                  }
                ]
              }
            ],
            "fields": "userEnteredValue,chipRuns",
            "range": {
              "startRowIndex": 0,
              "startColumnIndex": 0
            }
          }
        }

Configurer les propriétés des chips

Un objet chip peut avoir l'un des types de propriétés suivants :

personProperties

Utilisez cette option pour créer un chip de personne.

  • email (obligatoire) : adresse e-mail de la personne à lier.
  • displayFormat (facultatif) : format d'affichage préféré pour le nom de la personne. La valeur peut être l'une des suivantes :
    • DEFAULT : format standard "Prénom Nom".
    • LAST_NAME_COMMA_FIRST_NAME : format "Nom, Prénom".
    • EMAIL : adresse e-mail de la personne.

Utilisez cette option pour créer un chip de lien enrichi. Bien que l'API puisse lire des liens vers différents services Google (comme YouTube ou Agenda), seuls les liens vers des fichiers Google Drive peuvent être écrits sous forme de chips.

  • uri (obligatoire) : URI de la ressource. Pour l'écriture, il doit s'agir d'un lien vers un fichier Google Drive. Les URI ne peuvent pas dépasser 2 000 octets.

Lire un chip intelligent

Pour lire les données d'un chip intelligent, utilisez la spreadsheets.get méthode et incluez sheets.data.rowData.values(chipRuns) dans le paramètre fields.

Le tableau chipRuns de la réponse contient des objets pour toutes les sous-sections du texte de la cellule.

  • Séquences avec chip : ces sections comportent un objet chip rempli contenant personProperties ou richLinkProperties.
  • Séquences sans chip : les sections de texte brut comportent également un objet de séquence, mais son champ chip est vide.

Pour obtenir le texte d'affichage d'un chip, ajoutez formattedValue en tant que champ.

Mettre à jour un chip intelligent

Pour mettre à jour ou remplacer un chip intelligent, vous devez écraser le contenu de la cellule. Utilisez le même UpdateCellsRequest ou AppendCellsRequest que pour ajouter un chip, en fournissant un nouveau userEnteredValue et chipRun. Cela remplacera le chip existant dans la cellule.

Utiliser des chips intelligents avec d'autres fonctionnalités Sheets

Tableaux : les chips intelligents peuvent être utilisés comme type de colonne de tableau pour suivre les propriétaires de projet (chip de contact) ou les documents associés (chip de fichier).

Filtres : vous pouvez filtrer des plages en fonction de la valeur textuelle des chips intelligents qu'elles contiennent.