Smart chip

Questa guida descrive come e perché utilizzare l'API Google Sheets per aggiungere e gestire gli smart chip nei fogli di lavoro.

Che cos'è uno smart chip?

Con i chip intelligenti, puoi importare dati interattivi e avanzati da altre applicazioni Google Workspace direttamente in Fogli. I chip intelligenti consentono agli utenti di accedere rapidamente a informazioni e azioni, trasformando un link di una cella in un oggetto dinamico. Per saperne di più, vedi Inserire smart chip in Fogli Google.

Aggiungere uno smart chip

I chip sono rappresentati come esecuzioni di chip, che fanno parte di CellData, quindi puoi inserire un chip utilizzando il metodo spreadsheets.batchUpdate esistente fornendo un UpdateCellsRequest o un AppendCellsRequest.

La richiesta deve includere il campo chipRuns. Un'esecuzione di chip descrive le proprietà di un chip e la sua posizione all'interno del testo della cella.

Quando scrivi chipRuns, devi fornire anche un userEnteredValue che contenga caratteri segnaposto (@) per ogni chip che intendi aggiungere. Ogni esecuzione nell'array chipRuns corrisponderà a uno dei segnaposto. Le corse senza chip possono essere omesse durante la scrittura.

L'esempio seguente mostra come scrivere un chip di file, un chip di persone e testo normale in una singola cella, 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
            }
          }
        }

Configura le proprietà dei chip

Un oggetto chip può avere uno dei seguenti tipi di proprietà:

personProperties

Utilizza questo strumento per creare un chip persona.

  • email: (Obbligatorio) L'indirizzo email della persona da collegare.
  • displayFormat: (Facoltativo) Il formato di visualizzazione preferito per il nome della persona. Può corrispondere a uno dei seguenti:
    • DEFAULT: formato standard "Nome Cognome".
    • LAST_NAME_COMMA_FIRST_NAME: formato "Cognome, Nome".
    • EMAIL: l'indirizzo email della persona.

Utilizza questo elemento per creare un chip di link avanzato. Sebbene l'API possa leggere i link a vari servizi Google (come YouTube o Calendar), solo i link ai file di Google Drive possono essere scritti come chip.

  • uri: (obbligatorio) l'URI della risorsa. Per la scrittura, deve essere un link a un file di Google Drive. Gli URI non possono superare i 2000 byte.

Leggere uno smart chip

Per leggere i dati di uno smart chip, utilizza il metodo spreadsheets.get e includi sheets.data.rowData.values(chipRuns) nel parametro fields.

L'array chipRuns nella risposta conterrà oggetti per tutte le sottosezioni del testo della cella.

  • Corse con chip: queste sezioni avranno un oggetto chip compilato contenente personProperties o richLinkProperties.
  • Corse non chip: anche le sezioni di testo normale avranno un oggetto corsa, ma il campo chip sarà vuoto.

Per ottenere il testo visualizzato di un chip, aggiungi formattedValue come campo.

Aggiornare una smart chip

Per aggiornare o sostituire uno smart chip, devi sovrascrivere i contenuti della cella. Utilizza lo stesso UpdateCellsRequest o AppendCellsRequest che utilizzeresti per aggiungere un chip, fornendo un nuovo userEnteredValue e chipRun. Questo sostituirà il chip esistente nella cella.

Utilizzare gli smart chip con altre funzionalità di Fogli

Tabelle: gli smart chip possono essere utilizzati come tipo di colonna della tabella per monitorare i proprietari del progetto (smart chip di persone) o i documenti correlati (smart chip di file).

Filtri: puoi filtrare gli intervalli in base al valore di testo delle smart chip al loro interno.