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 gli smart chip, puoi inserire dati interattivi e avanzati da altre applicazioni Google Workspace direttamente in Fogli. Gli smart chip forniscono agli utenti un accesso rapido a informazioni e azioni, trasformando un link di una cella in un oggetto dinamico. Per saperne di più, consulta 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 anche fornire un userEnteredValue che contenga caratteri segnaposto (@) per ogni chip che intendi aggiungere. Ogni esecuzione nell'array chipRuns corrisponderà a uno dei segnaposto. Le esecuzioni senza chip possono essere omesse in 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
            }
          }
        }

Configurare le proprietà dei chip

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

personProperties

Utilizza questa opzione per creare un chip di persone.

  • email: (obbligatorio) l'indirizzo email della persona a cui 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.

Utilizza questa opzione 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 spreadsheets.get metodo 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 senza chip: anche le sezioni di testo normale avranno un oggetto di esecuzione, 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. In questo modo, il chip esistente nella cella verrà sostituito.

Utilizzare gli smart chip con altre funzionalità di Fogli

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

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