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'une icône intelligente ?

Grâce aux chips intelligents, vous pouvez importer des données enrichies et interactives provenant d'autres applications Google Workspace directement dans Sheets. Les chips intelligents permettent aux utilisateurs d'accéder rapidement à des informations et à des actions, en transformant un lien vers une 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 d'exécutions 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 exécution de chip 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 exécution du tableau chipRuns correspondra à l'un des espaces réservés. Les courses sans puce peuvent être omises lors de l'écriture.

L'exemple suivant montre comment écrire un chip de fichier, un chip de personne 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-le pour créer un chip de personne.

  • email : (obligatoire) adresse e-mail de la personne à associer.
  • 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-le pour créer un chip de lien enrichi. Bien que l'API puisse lire les 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 la rédaction, 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 méthode spreadsheets.get 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.

  • Sections avec des courses ébréchées : ces sections auront un objet chip renseigné contenant personProperties ou richLinkProperties.
  • Exécutions sans chips : les sections en texte brut auront également un objet d'exécution, mais son champ chip sera vide.

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

Modifier 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. Le chip existant dans la cellule sera remplacé.

Utiliser les 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 projets (chip "Personne") ou les documents associés (chip "Fichier").

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