Ícones inteligentes

Este guia descreve como e por que usar a API Google Sheets para adicionar e gerenciar ícones inteligentes nas suas planilhas.

O que é um ícone inteligente?

Com os ícones inteligentes, você pode trazer dados avançados e interativos de outros aplicativos do Google Workspace diretamente para as Planilhas. Os ícones inteligentes oferecem aos usuários acesso rápido a informações e ações, transformando um link de célula em um objeto dinâmico. Para saber mais, consulte Inserir ícones inteligentes nas Planilhas Google.

Adicionar um ícone inteligente

Os chips são representados como execuções de chips, que fazem parte de CellData. Portanto, é possível inserir um chip usando o método spreadsheets.batchUpdate atual fornecendo um UpdateCellsRequest ou AppendCellsRequest.

A solicitação precisa incluir o campo chipRuns. Uma execução de chip descreve as propriedades de um chip e onde ele está localizado no texto da célula.

Ao escrever chipRuns, você também precisa fornecer um userEnteredValue que contenha caracteres de marcador (@) para cada ícone que você pretende adicionar. Cada execução na matriz chipRuns corresponde a um dos marcadores de posição. Execuções sem chip podem ser omitidas na gravação.

O exemplo a seguir mostra como gravar um ícone de arquivo, um ícone de pessoa e texto simples em uma única célula, 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
            }
          }
        }

Configurar propriedades de chip

Um objeto de ícone pode ter um dos seguintes tipos de propriedade:

personProperties

Use isso para criar um ícone de pessoa.

  • email: (obrigatório) o endereço de e-mail da pessoa a ser vinculada.
  • displayFormat: (opcional) o formato de exibição preferido para o nome da pessoa. Será um dos seguintes valores:
    • DEFAULT: formato padrão "Nome Sobrenome".
    • LAST_NAME_COMMA_FIRST_NAME: formato "Sobrenome, Nome".
    • EMAIL: o endereço de e-mail da pessoa.

Use isso para criar um ícone de link avançado. Embora a API possa ler links para vários Serviços do Google (como YouTube ou Agenda), apenas os links para arquivos do Google Drive podem ser gravados como chips.

  • uri: (obrigatório) o URI do recurso. Para escrita, precisa ser um link de arquivo do Google Drive. Os URIs não podem exceder 2.000 bytes.

Ler um ícone inteligente

Para ler os dados de um ícone inteligente, use o método spreadsheets.get e inclua sheets.data.rowData.values(chipRuns) no parâmetro "fields".

A matriz chipRuns na resposta vai conter objetos para todas as subseções do texto da célula.

  • Execuções com falhas: essas seções terão um objeto chip preenchido com personProperties ou richLinkProperties.
  • Execuções sem chip: as seções de texto simples também terão um objeto de execução, mas o campo chip estará vazio.

Para receber o texto de exibição de um ícone, adicione formattedValue como um campo.

Atualizar um ícone inteligente

Para atualizar ou substituir um ícone inteligente, você precisa substituir o conteúdo da célula. Use o mesmo UpdateCellsRequest ou AppendCellsRequest que você usaria para adicionar um ícone, fornecendo um novo userEnteredValue e chipRun. Isso vai substituir o ícone atual na célula.

Usar ícones inteligentes com outros recursos das Planilhas Google

Tabelas: os ícones inteligentes podem ser usados como um tipo de coluna de tabela para acompanhar os proprietários do projeto (ícone de pessoas) ou documentos relacionados (ícone de arquivo).

Filtros: é possível filtrar intervalos com base no valor de texto dos smart chips neles.