Elementy inteligentne

Z tego przewodnika dowiesz się, jak i dlaczego używać interfejsu Google Sheets API do dodawania elementów inteligentnych w arkuszach kalkulacyjnych i zarządzania nimi.

Co to jest element inteligentny?

Dzięki inteligentnym elementom możesz wprowadzać bogate, interaktywne dane z innych aplikacji Google Workspace bezpośrednio do Arkuszy. Elementy inteligentne zapewniają użytkownikom szybki dostęp do informacji i działań, przekształcając link do komórki w obiekt dynamiczny. Więcej informacji znajdziesz w artykule Wstawianie elementów inteligentnych w Arkuszach Google.

Dodawanie elementu inteligentnego

Elementy są reprezentowane jako ciągi elementów, które są częścią CellData, więc możesz wstawić element za pomocą istniejącej metody spreadsheets.batchUpdate, podając UpdateCellsRequest lub AppendCellsRequest.

Prośba musi zawierać pole chipRuns. Uruchomienie elementu opisuje jego właściwości i to, gdzie się znajduje w tekście komórki.

Podczas pisania chipRuns musisz też podać userEnteredValue, który zawiera znaki zastępcze (@) dla każdego elementu, który chcesz dodać. Każde uruchomienie w tablicy chipRuns będzie odpowiadać jednemu z tych symboli zastępczych. Niewykorzystane przebiegi można pominąć podczas zapisu.

Ten przykład pokazuje, jak umieścić w jednej komórce A1 element pliku, element osób i zwykły tekst. * {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
            }
          }
        }

Konfigurowanie właściwości elementów

Obiekt elementu może mieć jeden z tych typów właściwości:

personProperties

Użyj tego, aby utworzyć element z osobą.

  • email: (wymagany) adres e-mail osoby, którą chcesz połączyć.
  • displayFormat: (opcjonalnie) preferowany format wyświetlania imienia i nazwiska. Dostępne wartości:
    • DEFAULT: standardowy format „Imię Nazwisko”.
    • LAST_NAME_COMMA_FIRST_NAME: format „Imię i nazwisko”.
    • EMAIL: adres e-mail tej osoby.

Użyj tego, aby utworzyć element graficzny z linkiem. Interfejs API może odczytywać linki do różnych usług Google (np. YouTube czy Kalendarza), ale tylko linki do plików na Dysku Google mogą być zapisywane jako elementy.

  • uri: (wymagany) identyfikator URI zasobu. W przypadku pisania musi to być link do pliku na Dysku Google. Adresy URI nie mogą przekraczać 2000 bajtów.

Odczytywanie elementu inteligentnego

Aby odczytać dane elementu inteligentnego, użyj metody spreadsheets.get i uwzględnij parametr sheets.data.rowData.values(chipRuns) w polu fields.

Tablica chipRuns w odpowiedzi będzie zawierać obiekty odpowiadające wszystkim poddziałom tekstu w komórce.

  • Uruchomienia z użyciem chipów: te sekcje będą zawierać wypełniony obiekt chip, który zawiera albo personProperties, albo richLinkProperties.
  • Sekcje z tekstem niesformatowanym: sekcje z tekstem niesformatowanym będą też zawierać obiekt przebiegu, ale pole chip będzie puste.

Aby uzyskać tekst wyświetlany na elemencie, dodaj pole formattedValue.

Aktualizowanie elementu inteligentnego

Aby zaktualizować lub zastąpić element inteligentny, musisz nadpisać zawartość komórki. Użyj tych samych wartości UpdateCellsRequest lub AppendCellsRequest, co w przypadku dodawania elementu, podając nowe wartości userEnteredValue i chipRun. Spowoduje to zastąpienie dotychczasowego elementu w komórce.

Korzystanie z elementów inteligentnych w innych funkcjach Arkuszy

Tabele: elementy inteligentne można używać jako typ kolumny tabeli do śledzenia właścicieli projektu (element inteligentny dotyczący osób) lub powiązanych dokumentów (element inteligentny dotyczący pliku).

Filtry: możesz filtrować zakresy według wartości tekstowej elementów inteligentnych w nich zawartych.