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 przekazywać użytkownikowi odpowiednie informacje, automatyzować zadania i łączyć systemy innych firm z Edytorami.

Otwieranie interfejsu dodatku

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

Dodatek do Google Workspace może udostępniać te interfejsy:

• Interfejsy strony głównej: jeśli plik manifestu dodatku zawiera wyzwalacz EDITOR_NAME.homepageTrigger dla edytora, w którym użytkownik otwiera dodatek, dodatek tworzy i zwraca kartę strony głównej przeznaczoną specjalnie dla tego edytora. Jeśli plik manifestu dodatku nie zawiera elementu EDITOR_NAME.homepageTrigger dla edytora, w którym użytkownik otwiera dodatek, zamiast niego wyświetla się ogólna karta strony głównej.

• Interfejsy API REST: jeśli dodatek korzysta z interfejsów API REST, możesz uwzględnić aktywatory, które żądają dostępu do dokumentu na poziomie poszczególnych plików za pomocą zakresu drive.file. Po przyznaniu uprawnień uruchamia się kolejny aktywator o nazwie EDITOR_NAME.onFileScopeGrantedTrigger, który wyświetla interfejs dostosowany do pliku.

• Interfejsy podglądu linków: jeśli dodatek jest zintegrowany z usługą innej firmy, możesz tworzyć karty, które wyświetlają podgląd treści z adresów URL tej usługi.

Tworzenie interfejsów dodatków do edytora

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

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 wszystkie wymagane zakresy edytora.
3. Jeśli udostępniasz stronę główną dostosowaną do edytora, zaimplementuj funkcję EDITOR_NAME.homepageTrigger, aby utworzyć interfejs. W przeciwnym razie użyj interfejsu common.homepageTrigger, aby utworzyć wspólną stronę główną dla aplikacji hostujących.
4. Jeśli używasz interfejsów REST API, zaimplementuj przepływ autoryzacji zakresu drive.file i funkcję wyzwalającą EDITOR_NAME.onFileScopeGrantedTrigger, aby wyświetlać interfejs dostosowany do otwartego pliku. Więcej informacji znajdziesz w artykule Interfejsy API REST.
5. Jeśli konfigurujesz podgląd linków z usługi innej firmy, zaimplementuj przepływ autoryzacji zakresu https://www.googleapis.com/auth/workspace.linkpreview i funkcję linkPreviewTriggers. Więcej informacji znajdziesz w artykule Interfejsy podglądu linków.
6. Zaimplementuj powiązane funkcje wywołania zwrotnego potrzebne do reagowania na interakcje użytkownika z interfejsem, takie jak kliknięcia przycisków.

Strony główne edytorów

W projekcie skryptu dodatku musisz podać funkcję wywołującą strony głównej, która tworzy i zwraca pojedynczy obiekt Card lub tablicę obiektów Card, które składają się na stronę główną dodatku.

Do funkcji wywołującej na stronie głównej przekazywany jest obiekt zdarzenia jako parametr zawierający informacje takie jak platforma klienta. Możesz używać danych obiektu zdarzenia do dostosowywania konstrukcji strony głównej.

Możesz wyświetlać wspólną stronę główną lub stronę główną dostosowaną do edytora, w którym użytkownik otwiera dodatek.

wyświetlać wspólną stronę główną,

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

Poniższy przykład pokazuje fragment addons pliku manifestu dodatku do Google Workspace. Dodatek rozszerza funkcje Dokumentów, Arkuszy i Prezentacji 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świetlanie strony głównej przeznaczonej dla edytora

Aby wyświetlać stronę główną dostosowaną do potrzeb edytora, dodaj element EDITOR_NAME.homepageTrigger do pliku manifestu dodatku.

Poniższy przykład pokazuje fragment addons pliku manifestu dodatku do Google Workspace. Dodatek jest włączony w Dokumentach, Arkuszach i Prezentacjach. Wyświetla wspólną stronę główną w Dokumentach i Prezentacjach oraz unikalną stronę główną w Arkuszach. Funkcja wywołania zwrotnego onSheetsHomepage tworzy kartę strony głównej 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 dodatek korzysta z interfejsów API REST, takich jak Google Sheets API, możesz użyć funkcji onFileScopeGrantedTrigger, aby wyświetlić nowy interfejs dostosowany do pliku otwartego w aplikacji hosta Edytora.

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

Gdy użytkownik przyzna zakres drive.file, zostanie uruchomiony zdarzenie EDITOR_NAME.onFileScopeGrantedTrigger.runFunction. Gdy reguła zostanie uruchomiona, wykona funkcję reguły kontekstowej określoną w polu 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 wybraną aplikacją hosta Edytora, np. sheets.onFileScopeGrantedTrigger.

1. Dodaj EDITOR_NAME.onFileScopeGrantedTrigger do odpowiedniej sekcji edytora w pliku manifestu. Jeśli na przykład chcesz utworzyć ten interfejs w Arkuszach Google, dodaj regułę w 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 używane do zapewnienia interaktywności widżetu w interfejsie. Jeśli na przykład w interfejsie umieścisz przycisk, powinien on mieć dołączoną akcję i zastosowaną funkcję wywołania zwrotnego, która jest uruchamiana po kliknięciu przycisku.

Poniższy przykład pokazuje fragment addons pliku manifestu dodatku do Google Workspace. Dodatek korzysta z interfejsów API REST, więc w przypadku Arkuszy Google uwzględniono onFileScopeGrantedTrigger. Gdy użytkownik przyzna zakres drive.file, funkcja wywołania zwrotnegoonFileScopeGrantedSheets utworzy interfejs specyficzny dla 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"
     }
   }

Interfejsy podglądu linków do usług innych firm

Aby włączyć podgląd linków w usłudze innej firmy, musisz skonfigurować podgląd linków w manifeście dodatku i utworzyć funkcję, która zwraca kartę podglądu. W przypadku usług, które wymagają autoryzacji użytkownika, funkcja musi też wywoływać proces autoryzacji.

Instrukcje włączania podglądu linków znajdziesz w artykule Wyświetlanie podglądu linku za pomocą elementów inteligentnych.

Obiekty zdarzeń

Obiekt zdarzenia jest tworzony i przekazywany do funkcji aktywujących, takich jak EDITOR_NAME.homepageTrigger lub EDITOR_NAME.onFileScopeGrantedTrigger. Funkcja aktywująca używa informacji z obiektu zdarzenia, aby określić, jak tworzyć karty dodatków lub w inny sposób kontrolować działanie dodatku.

Pełna struktura obiektów zdarzeń jest opisana w sekcji Obiekty zdarzeń.

Gdy aplikacją hostującą dodatek jest Edytor, obiekty zdarzeń zawierają pola obiektów zdarzeń Dokumentów, Arkuszy lub Prezentacji, które zawierają informacje o kliencie.

Jeśli dodatek nie ma drive.fileautoryzacji zakresu 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 Edytora.

Poniższy przykład przedstawia obiekt zdarzenia Edytora, który jest przekazywany do funkcji sheets.onFileScopeGrantedTrigger. W tym przypadku dodatek ma drive.fileautoryzację zakresu dla bieżącego dokumentu:

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