Ícones inteligentes

Neste guia, descrevemos 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 interativos e avançados de outros apps 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 ícones são representados como execuções de ícones, que fazem parte do CellData. Assim, é possível inserir um ícone 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 de posição (@) para cada ícone que pretende adicionar. Cada execução na matriz chipRuns corresponde a um dos marcadores de posição. As execuções sem chip podem ser omitidas na gravação.

O exemplo a seguir mostra como escrever um ícone de arquivo, um ícone de pessoas 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 do ícone

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 o YouTube ou a Agenda), apenas links para arquivos do Google Drive podem ser gravados como ícones.

  • uri: (obrigatório) o URI do recurso. Para escrever, esse link precisa ser de um 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 de campos.

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

  • Execuções com falha: 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 têm um objeto de execução, mas o campo chip está 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, é necessário 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 na célula.

Usar ícones inteligentes com outros recursos das Planilhas

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

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