Smart chip

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

Che cos'è uno smart chip?

Con i chip intelligenti, puoi importare direttamente in Fogli dati interattivi e completi da altre applicazioni Google Workspace. Gli smart chip consentono agli utenti di accedere rapidamente a informazioni e azioni, trasformando un link a 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 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 contenente caratteri segnaposto (@) per ogni chip che intendi aggiungere. Ogni esecuzione nell'array chipRuns corrisponderà a uno dei segnaposto. Le esecuzioni non con chip possono essere omesse durante la scrittura.

L'esempio seguente mostra come scrivere un chip di file, un chip di persone e un 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

Usa questa opzione per creare un chip di una persona.

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

Utilizzalo 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.

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

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

Aggiornare uno 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. Il chip esistente nella cella verrà sostituito.

Utilizzare gli smart chip con altre funzionalità di Fogli

Tables: gli smart chip possono essere utilizzati come tipo di colonna di tabella per monitorare i proprietari dei progetti (chip Persone) o i documenti correlati (chip File).

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