Tworzenie interfejsów Edytora Google

Dzięki dodatkom do Google Workspace możesz udostępniać niestandardowe interfejsy w edytorach, w tym w Dokumentach, Arkuszach i Prezentacjach Google. Dzięki temu możesz udostępniać użytkownikowi istotne informacje, automatyzować zadania i podłączać systemy innych firm do aplikacji.

Otwieranie interfejsu dodatku

Dodatek do Google Workspace możesz otworzyć w Edytorach, jeśli jego ikona jest widoczna w panelu szybkiego dostępu Google Workspace po prawej stronie interfejsów Dokumentów, Arkuszy i Prezentacji.

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

  • Interfejsy strony głównej: jeśli manifest dodatku zawiera element EDITOR_NAME.homepageTrigger dla edytora, w którym użytkownik otwiera dodatek, dodatek tworzy i zwraca kartę strony głównej specjalnie dla tego edytora. Jeśli manifest dodatku nie zawiera informacji o edytorze, w którym użytkownik otwiera dodatek, wyświetla się ogólna karta strony głównej.EDITOR_NAME.homepageTrigger

  • Interfejsy API REST: jeśli dodatek korzysta z interfejsów API REST, możesz uwzględnić w nim żądania dostępu do dokumentu na poziomie pliku za pomocą zakresu drive.file. Po udzieleniu uprawnień uruchamia się kolejny skrypt o nazwie EDITOR_NAME.onFileScopeGrantedTrigger, który wyświetla interfejs odpowiedni dla danego pliku.

  • Linki do interfejsów podglądu: jeśli dodatek integruje się z usługą innej firmy, możesz tworzyć karty z podglądem treści z adresów URL tej usługi.

Tworzenie interfejsów dla dodatków do edytora

Aby utworzyć interfejsy dodatków do edytora dla edytorów:

  1. Dodaj odpowiednie pola addOns.common, addOns.docs, addOns.sheets i addOns.slides do manifestu projektu skryptu dodatku.
  2. Dodaj do pliku manifestu projektu skryptu wymagane uprawnienia edytora.
  3. Jeśli udostępniasz stronę główną w edytorze, użyj funkcji EDITOR_NAME.homepageTrigger, aby utworzyć interfejs. Jeśli nie, użyj interfejsu common.homepageTrigger, aby utworzyć wspólną stronę główną dla aplikacji hosta.
  4. Jeśli używasz interfejsów API REST, zastosuj drive.fileprzepływ autoryzacji zakresu i funkcję EDITOR_NAME.onFileScopeGrantedTrigger, aby wyświetlić interfejs odpowiedni dla otwartego pliku. Więcej informacji znajdziesz w artykule Interfejsy interfejsu API REST.
  5. Jeśli konfigurujesz podgląd linków z usługi innej firmy, zastosuj https://www.googleapis.com/auth/workspace.linkpreviewprzepływ autoryzacji zakresu i funkcję linkPreviewTriggers. Więcej informacji znajdziesz w artykule Interfejsy podglądu linków.
  6. Wdrożyć powiązane funkcje wywołania zwrotnego, które są potrzebne do reagowania na interakcje użytkownika z interfejsem użytkownika, takie jak kliknięcia przycisków.

Strony główne edytora

W projekcie skryptu dodatku musisz podać funkcję wyzwalacza strony głównej, która tworzy i zwraca pojedynczy obiekt Card lub tablicę obiektów Card, które tworzą stronę główną dodatku.

Funkcja reguły dotyczącej strony głównej otrzymuje jako parametr obiekt zdarzenia, który zawiera informacje o takich elementach, jak platforma klienta. Możesz użyć danych obiektu zdarzenia, aby dostosować konstrukcję strony głównej.

Możesz wyświetlić wspólną stronę główną lub stronę główną, która jest specyficzna dla edytora, w którym użytkownik otwiera Twoje dodatki.

Wyświetlanie wspólnej strony głównej

Aby wyświetlać wspólną stronę główną dodatku w Edytorach, dodaj odpowiednie pola Edytorzy, takie jak addOns.docs, addOns.sheets lub addOns.slides, do pliku manifestu dodatku.

Ten przykład pokazuje część addons w pliku manifestu dodatku Google Workspace. Wtyczka rozszerza Dokumenty, Arkusze i Prezentacje oraz wyświetla wspólną stronę główną w każdej aplikacji hosta.

 "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świetlać stronę główną związaną z Edytorem,

Aby wyświetlić stronę główną dla konkretnego edytora, dodaj do pliku manifestu rozszerzenia parametr EDITOR_NAME.homepageTrigger.

Przykład poniżej pokazuje część addons pliku manifestu dodatku Google Workspace. Dodatek jest włączony w Dokumentach, Arkuszach i Prezentacjach. W Dokumentach i Prezentacjach wyświetla wspólną stronę główną, a w Arkuszach – osobną. Funkcja wywołania zwrotnego onSheetsHomepage tworzy kartę strony głównej 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 Twoje rozszerzenie korzysta z interfejsów API REST, takich jak interfejs API Arkuszy Google, możesz użyć funkcji onFileScopeGrantedTrigger, aby wyświetlić nowy interfejs przeznaczony do pliku otwartego w aplikacji gospodarza edytora.

Aby korzystać z funkcji onFileScopeGrantedTrigger, musisz uwzględnić przepływ autoryzacji zakresu drive.file. Aby dowiedzieć się, jak poprosić o dostęp do zakresu drive.file, przeczytaj artykuł Prośba o dostęp do pliku w bieżącym dokumencie.

Gdy użytkownik przyzna uprawnienia o zakresie drive.file, wywoływana jest funkcja EDITOR_NAME.onFileScopeGrantedTrigger.runFunction. Gdy reguła zostanie uruchomiona, wykona funkcję reguły kontekstowej określoną przez pole EDITOR_NAME.onFileScopeGrantedTrigger.runFunction w pliku manifestu dodatku.

Aby utworzyć interfejs API REST dla jednego z edytorów, wykonaj te czynności. Zastąp EDITOR_NAME nazwą aplikacji hosta Edytora, której chcesz użyć, np. sheets.onFileScopeGrantedTrigger.

  1. Wpisz EDITOR_NAME.onFileScopeGrantedTrigger w odpowiedniej sekcji edytora w pliku manifestu. Jeśli na przykład chcesz utworzyć ten interfejs w Arkuszach Google, dodaj regułę do sekcji "sheets".
  2. Zaimplementuj funkcję o nazwie podanej w sekcji EDITOR_NAME.onFileScopeGrantedTrigger. Ta funkcja przyjmuje jako argument obiekt zdarzenia i musi zwracać pojedynczy obiekt Card lub tablicę obiektów Card.
  3. Podobnie jak w przypadku każdej karty, musisz zaimplementować funkcje wywołania zwrotnego, które zapewniają interaktywność widżetu w interfejsie. Jeśli na przykład dodasz do interfejsu przycisk, powinien on mieć przypisaną działkę i zaimplementowaną funkcję wywołania zwrotnego, która będzie wykonywana po kliknięciu tego przycisku.

Przykład poniżej pokazuje część addons pliku manifestu dodatku Google Workspace. Dodatek korzysta z interfejsów API REST, więc onFileScopeGrantedTrigger jest uwzględniony w Arkuszach Google. Gdy użytkownik przyzna dostęp o zakresie drive.file, funkcja wywołania zwrotnego onFileScopeGrantedSheets tworzy interfejs dla konkretnego pliku.

"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ądy linków dla usługi innej firmy, musisz skonfigurować podglądy linków w pliku manifestu dodatku i utworzyć funkcję, która zwraca kartę podglądu. W przypadku usług wymagających autoryzacji przez użytkownika funkcja musi też wywoływać przepływ danych autoryzacji.

Aby dowiedzieć się, jak włączyć podgląd linków, przeczytaj artykuł Wyświetlanie podglądów linków za pomocą elementów inteligentnych.

Obiekty zdarzeń

Tworzony jest obiekt zdarzenia i przekazywany do funkcji aktywatora, np. EDITOR_NAME.homepageTrigger lub EDITOR_NAME.onFileScopeGrantedTrigger. Funkcja aktywatora korzysta z informacji w obiekcie zdarzenia, aby określić sposób tworzenia kart dodatków lub sterowania ich działaniem.

Pełna struktura obiektów zdarzeń została opisana w artykule Obiekty zdarzenia.

Gdy edytujący jest aplikacją hostującą dodatku, obiekty zdarzeń obejmują pola obiektów zdarzeń Dokumenty, Arkusze lub Prezentacje, które zawierają informacje o kliencie.

Jeśli dodatek nie ma autoryzacji zakresu drive.file dla bieżącego użytkownika lub dokumentu, obiekt zdarzenia zawiera tylko pole docs.addonHasFileScopePermission, sheets.addonHasFileScopePermission lub slides.addonHasFileScopePermission. Jeśli dodatek ma autoryzację, obiekt zdarzenia zawiera wszystkie pola obiektu zdarzenia w Edytorze.

Poniższy przykład pokazuje obiekt zdarzenia edytora przekazywany do funkcji sheets.onFileScopeGrantedTrigger. W tym przypadku dodatek ma uprawnienia dostępu do bieżącego dokumentu w zakresie drive.file:

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