Tworzenie interfejsów Edytora Google

Dodatki do Google Workspace pozwalają udostępnić niestandardowe interfejsy w edytorach, takich jak Dokumenty, Arkusze i Prezentacje Google. Dzięki temu możesz udostępnić użytkownikowi istotne informacje, automatyzowanie zadań i łączenie systemów innych firm z Edytujący.

Uzyskiwanie dostępu do interfejsu dodatku

Dodatek do Google Workspace możesz otworzyć w edytorach jeśli jego ikona pojawia się w szybkim podglądzie Google Workspace otwórz panel boczny po prawej stronie użytkownika Dokumentów, Arkuszy i Prezentacji i interfejsów.

Dodatek do Google Workspace może wyświetlać te interfejsy:

  • Interfejsy strony głównej: jeśli plik manifestu dodatku zawiera zawiera regułę EDITOR_NAME.homepageTrigger w Edytorze, w którym użytkownik otwiera dodatek; dodatek tworzy i zwraca karta na stronie głównej specjalnie dla tego edytora. Jeśli w pliku manifestu dodatku nie ma EDITOR_NAME.homepageTrigger w edytorze otwieranym przez użytkownika. pojawi się karta ogólna.

  • Interfejsy API typu REST: jeśli dodatek używa REST interfejsów API, możesz dodać aktywatory, które żądają dostępu do dokumentu na podstawie wybranych plików za pomocą zakresu drive.file. Po przyznaniu następuje uruchomienie kolejnego aktywatora o nazwie EDITOR_NAME.onFileScopeGrantedTrigger wykonania i wyświetli interfejs odpowiedni dla danego pliku.

  • Interfejsy linku podglądu: jeśli Twój dodatek integruje się z usługą innej firmy, możesz tworzyć karty, z adresów URL Twojej usługi.

Tworzenie interfejsów dodatków do Edytora

Aby utworzyć interfejsy dodatku Edytor dla edytorów, wykonaj te czynności:

  1. Dodaj odpowiednie addOns.common, addOns.docs, addOns.sheets oraz addOns.slides do manifestu projektu skryptu dodatku.
  2. Dodaj wymagane zakresy edytora do: w pliku manifestu projektu skryptu.
  3. Jeśli udostępniasz stronę główną Edytora, zastosuj EDITOR_NAME.homepageTrigger. do utworzenia interfejsu. Jeśli nie, użyj metody common.homepageTrigger za pomocą interfejsu, aby utworzyć wspólną stronę główną aplikacji hosta.
  4. Jeśli używasz interfejsów API REST, wdróż proces autoryzacji zakresu drive.file oraz EDITOR_NAME.onFileScopeGrantedTrigger. w celu wyświetlenia interfejsu charakterystycznego dla otwartego pliku. Więcej więcej informacji znajdziesz w artykule na temat interfejsów API REST.
  5. Jeśli konfigurujesz podglądy linków z usługi innej firmy, zaimplementuj procesu autoryzacji zakresu https://www.googleapis.com/auth/workspace.linkpreview oraz linkPreviewTriggers. . Więcej informacji: Interfejsy API podglądu linków.
  6. Zaimplementować powiązane funkcje wywołania zwrotnego niezbędne do reagowania na interakcje z interfejsem, np. kliknięcia przycisków;

Strony główne edytora

W projekcie skryptu dodatku musisz podać funkcję aktywatora strony głównej tworzący i zwracający pojedynczy element Card lub tablica obiektów Card tworzących stronę główną dodatku.

Funkcja aktywatora strony głównej jest przekazywana do obiektu zdarzenia. jako parametr zawierający informacje m.in. o platformie klienta. Dostępne opcje użyć danych obiektu zdarzenia, aby dostosować konstrukcję strony głównej.

Możesz zaprezentować stronę główną lub stronę główną specyficzną dla Edytora użytkownik otworzy dodatek.

Wyświetl wspólną stronę główną

Aby wyświetlić wspólną stronę główną dodatku w edytorach, dodaj do niej pola edytora, np. addOns.docs, addOns.sheets, lub addOns.slides, w pliku manifestu dodatku.

Poniższy przykład pokazuje część dodatku do Google Workspace dotyczącą addons pliku manifestu. Dodatek stanowi rozszerzenie Dokumentów, Arkuszy i Prezentacji oraz pokazuje stronie głównej w każdej aplikacji hostującej.

 "addOns": {
    "common": {
      "name": "Translate",
      "logoUrl": "https://www.gstatic.com/images/branding/product/1x/translate_24dp.png",
      "layoutProperties": {
        "primaryColor": "#2772ed"
      },
      "homepageTrigger": {
        "runFunction": "onHomepage"
      }
    },
    "docs": {},
    "sheets": {},
    "slides": {}
  }
}

Wyświetlanie strony głównej specyficznej dla Edytora

Aby udostępnić stronę główną użytkownikom z uprawnieniami do edycji, dodaj do dodatku EDITOR_NAME.homepageTrigger pliku manifestu.

Poniższy przykład pokazuje część addons pliku manifestu dodatku do Google Workspace. Dodatek jest włączony w Dokumentach, Arkuszach i Prezentacjach. Wyświetlane są typowe stronę główną w Dokumentach i Prezentacjach oraz niepowtarzalną stronę główną w Arkuszach. Wywołanie zwrotne funkcja onSheetsHomepage tworzy kartę strony głównej specyficzną dla Arkuszy.

 "addOns": {
    "common": {
      "name": "Translate",
      "logoUrl": "https://www.gstatic.com/images/branding/product/1x/translate_24dp.png",
      "layoutProperties": {
        "primaryColor": "#2772ed"
      },
      "homepageTrigger": {
        "runFunction": "onHomepage"
      }
    },
    "docs": {},
    "slides": {},
    "sheets": {
     "homepageTrigger": {
       "runFunction": "onSheetsHomepage"
     },
  }
}

Interfejsy API REST

Jeśli Twój dodatek używa interfejsów API typu REST, takich jak GoogleSheet API, możesz użyć funkcji onFileScopeGrantedTrigger do wyświetlenia nowego interfejsu powiązane z plikiem otwartym w aplikacji hosta Edytora.

Musisz uwzględnić proces autoryzacji zakresu drive.file, aby korzystać z onFileScopeGrantedTrigger. Aby dowiedzieć się, jak poprosić o drive.file zakres: przeczytaj artykuł o wysyłaniu prośby o dostęp do bieżącego dokumentu.

Gdy użytkownik przyzna zakres drive.file, EDITOR_NAME.onFileScopeGrantedTrigger.runFunction. pożary. Po uruchomieniu reguły uruchamia funkcję aktywatora kontekstowego. określona przez pole EDITOR_NAME.onFileScopeGrantedTrigger.runFunction w tabeli pliku manifestu dodatku.

Aby utworzyć interfejs API REST dla jednego z edytorów, wykonaj poniższe czynności. Zastąp EDITOR_NAME wybraną aplikacją hosta Edytora użyj na przykład sheets.onFileScopeGrantedTrigger.

  1. Obejmują EDITOR_NAME.onFileScopeGrantedTrigger w odpowiedniej sekcji edytora pliku manifestu. Jeśli na przykład chcesz utworzyć ten interfejs w Arkuszach Google, dodaj regułę do sekcji "sheets".
  2. Zaimplementuj funkcję o nazwie w polu EDITOR_NAME.onFileScopeGrantedTrigger . Ta funkcja przyjmuje obiekt zdarzenia jako argument i musi zwrócić jeden Card. lub tablica obiektów Card.
  3. Tak jak w przypadku każdej karty, musisz zaimplementować funkcje wywołania zwrotnego służące do i aktywności widżetów w interfejsie. Jeśli na przykład dodasz przycisk interfejs powinien mieć przypisaną funkcję Action i zaimplementowaną funkcję wywołania zwrotnego, która uruchamia się, gdy przycisk gdy użytkownik kliknie reklamę.

Poniższy przykład pokazuje część addons pliku manifestu dodatku do Google Workspace. Dodatek wykorzystuje interfejsy API REST, dlatego onFileScopeGrantedTrigger jest dostępny dla Arkusze Google. Gdy użytkownik przyzna zakres drive.file, funkcja wywołania zwrotnego onFileScopeGrantedSheets tworzy interfejs przeznaczony do obsługi plików.

"addOns": {
   "common": {
     "name": "Productivity add-on",
     "logoUrl": "https://www.gstatic.com/images/icons/material/system_gm/1x/work_outline_black_18dp.png",
     "layoutProperties": {
       "primaryColor": "#669df6",
       "secondaryColor": "#ee675c"
     }
   },
   "sheets": {
     "homepageTrigger": {
       "runFunction": "onEditorsHomepage"
     },
     "onFileScopeGrantedTrigger": {
       "runFunction": "onFileScopeGrantedSheets"
     }
   }

Aby włączyć podgląd linków dla usługi innej firmy, musisz skonfigurować link w pliku manifestu dodatku i utworzyć funkcję zwracającą podgląd W przypadku usług, które wymagają autoryzacji użytkownika, funkcja musi również wywoływać proces autoryzacji.

Aby dowiedzieć się, jak włączyć podgląd linków, zobacz Wyświetl podgląd linków z elementami inteligentnymi.

Obiekty zdarzeń

Obiekt zdarzenia jest tworzony i przekazywany w celu aktywowania funkcji, takich jak EDITOR_NAME.homepageTrigger lub EDITOR_NAME.onFileScopeGrantedTrigger. Funkcja aktywująca korzysta z informacji w sekcji zdarzenia, aby określić sposób tworzenia kart dodatkowych lub w inny sposób kontrolować działania dodatku.

Pełną strukturę obiektów zdarzeń opisano w sekcji Obiekty zdarzeń.

Gdy edytujący jest aplikacją hosta dodatku, obiekty zdarzeń zawierają Dokumenty, Arkusze lub Prezentacje pól obiektu zdarzenia, które zawierają informacje o kliencie.

Jeśli dodatek nie ma autoryzacji zakresu drive.file dla bieżącego użytkownika lub dokument, obiekt zdarzenia zawiera tylko docs.addonHasFileScopePermission, sheets.addonHasFileScopePermission lub slides.addonHasFileScopePermission. Jeśli dodatek ma , obiekt zdarzenia będzie zawierał wszystkie pola obiektów zdarzenia edytora.

Poniższy przykład pokazuje obiekt zdarzenia Edytora, który jest przekazywany do sheets.onFileScopeGrantedTrigger. Dodatek zawiera funkcje Autoryzacja zakresu drive.file dla bieżącego dokumentu:

`        {
          "commonEventObject": { ... },
          "sheets": {
            "addonHasFileScopePermission": true,
            "id":"A_24Q3CDA23112312ED52",
            "title":"How to get started with Sheets"
          },
          ...
        }