Tworzenie interfejsów Edytora Google

Dodatki do Google Workspace pozwalają korzystać z niestandardowych interfejsów edytorów, w tym Dokumentów, Arkuszy i Prezentacji Google. Dzięki temu możesz przekazywać użytkownikom istotne informacje, automatyzować zadania i łączyć z edytorami systemy innych firm.

Uzyskiwanie dostępu do interfejsu dodatku

Dodatek do Google Workspace możesz otworzyć w Edytorach, jeśli jego ikona pojawia się w panelu bocznym szybkiego dostępu Google Workspace w prawej części interfejsów użytkownika Dokumentów, Arkuszy i Prezentacji.

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

  • Interfejsy strony głównej: jeśli plik manifestu dodatku zawiera wyzwalacz EDITOR_NAME.homepageTrigger dla Edytora, użytkownik otworzy go, dodatek stworzy i zwraca kartę strony głównej specjalnie dla tego edytora. Jeśli w pliku manifestu dodatku nie ma elementu EDITOR_NAME.homepageTrigger, w którym użytkownik go otworzy, wyświetlana jest ogólna karta strony głównej.

  • Interfejsy API typu REST: jeśli dodatek używa interfejsów API REST, możesz dołączyć aktywatory, które żądają dostępu do dokumentu z podziałem na pliki za pomocą zakresu drive.file. Po przyznaniu inny aktywator o nazwie EDITOR_NAME.onFileScopeGrantedTrigger zostanie uruchomiony i wyświetli interfejs związany z tym plikiem.

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

Tworzenie interfejsów dodatków do edytora

Wykonaj te czynności, aby dostosować interfejsy dodatku do edytora kompilacji dla edytorów:

  1. Dodaj odpowiednie pola addOns.common, addOns.docs, addOns.sheets i addOns.slides do pliku manifestu dodatku w projekcie dodatku.
  2. Dodaj dowolne wymagane zakresy edytora do pliku manifestu projektu skryptu.
  3. Jeśli udostępniasz stronę główną edytora, zaimplementuj funkcję EDITOR_NAME.homepageTrigger, aby utworzyć interfejs. Jeśli nie, użyj interfejsu common.homepageTrigger do utworzenia wspólnej strony głównej dla aplikacji hostowanych.
  4. Jeśli używasz interfejsów API typu REST, zaimplementuj proces autoryzacji zakresu drive.file i funkcję aktywującą EDITOR_NAME.onFileScopeGrantedTrigger, aby wyświetlać interfejs powiązany z otwartym plikiem. Więcej informacji znajdziesz w artykule o interfejsach API typu REST (w języku angielskim).
  5. Jeśli konfigurujesz podgląd linków z usługi zewnętrznej, zastosuj proces 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 niezbędne do reagowania na interakcje użytkownika w interfejsie, np. na kliknięcia przycisku.

Strony główne edytora

W projekcie skryptu dodatku musisz udostępnić funkcję aktywatora strony głównej, która kompilowa i zwraca pojedynczy obiekt Card lub tablicę obiektów Card, które składają się na stronę główną dodatku.

Funkcja aktywatora strony głównej przekazuje obiekt zdarzenia jako parametr, który zawiera informacje, np. o platformie klienta. Za pomocą danych obiektu zdarzenia możesz dostosować konstrukcję strony głównej.

Możesz udostępnić stronę główną lub stronę główną dostępną tylko w Edytorze, w których użytkownik otworzy Twój dodatek.

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

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

Poniższy przykład pokazuje fragment addons pliku manifestu dodatku Google Workspace. Rozszerza on Dokumenty, Arkusze i Prezentacje oraz wyświetla wspólną stronę główną 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 tylko dla Edytora

Aby zaprezentować edytorowi stronę główną, dodaj EDITOR_NAME.homepageTrigger do pliku manifestu dodatku.

Poniższy przykład pokazuje fragment addons pliku manifestu dodatku 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ę główną 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 interfejs API Arkuszy Google, możesz użyć funkcji onFileScopeGrantedTrigger, aby wyświetlić nowy interfejs dostosowany do pliku otwartego w aplikacji obsługującej Edytor Google Ads.

Aby używać funkcji onFileScopeGrantedTrigger, musisz uwzględnić proces autoryzacji zakresu drive.file. Aby dowiedzieć się, jak poprosić o zakres drive.file, przeczytaj sekcję Prośba o dostęp do pliku bieżącego dokumentu.

Gdy użytkownik przyzna zakres drive.file, uruchamia się EDITOR_NAME.onFileScopeGrantedTrigger.runFunction. Uaktywnienie aktywatora wykonuje funkcję aktywatora kontekstowego wskazaną w polu EDITOR_NAME.onFileScopeGrantedTrigger.runFunction w pliku manifestu dodatku.

Aby utworzyć interfejs API REST dla jednego z edytorów, wykonaj poniższe czynności. Zastąp EDITOR_NAME nazwą hostującą Edytor, której chcesz używać, np. sheets.onFileScopeGrantedTrigger.

  1. Umieść 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 sekcji EDITOR_NAME.onFileScopeGrantedTrigger. Ta funkcja akceptuje obiekt zdarzenia jako argument i musi zwracać pojedynczy obiekt Card lub tablicę obiektów Card.
  3. Tak jak w przypadku każdej karty, musisz wdrożyć funkcje wywołania zwrotnego służące do zapewnienia interaktywności widżetów dla interfejsu. Jeśli np. dodasz przycisk do interfejsu, powinien on mieć dołączony element Action i zaimplementowaną funkcję wywołania zwrotnego, która uruchamia się po kliknięciu przycisku.

Poniższy przykład pokazuje fragment addons pliku manifestu dodatku Google Workspace. Dodatek korzysta z interfejsów API REST, więc onFileScopeGrantedTrigger jest zawarty w Arkuszach Google. Gdy użytkownik przyzna zakres drive.file, funkcja wywołania zwrotnego onFileScopeGrantedSheets stworzy interfejs dostosowany do 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 w usłudze innej firmy, musisz skonfigurować je w pliku manifestu 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 linków za pomocą elementów inteligentnych.

Obiekty zdarzeń

Obiekt zdarzenia jest tworzony i przekazywany do aktywowania funkcji takich jak EDITOR_NAME.homepageTrigger czy EDITOR_NAME.onFileScopeGrantedTrigger. Funkcja aktywatora wykorzystuje informacje zawarte w obiekcie zdarzenia do określania sposobu tworzenia kart dodatków lub kontrolowania działania dodatku w inny sposób.

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

Gdy edytor jest aplikacją hostującą dodatek, obiekty zdarzeń obejmują pola obiektów zdarzeń Dokumentów, Arkuszy lub Prezentacji, 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 będzie zawierać wszystkie pola obiektów zdarzeń edytora.

Poniższy przykład przedstawia obiekt zdarzenia Edytora przekazywanego do funkcji sheets.onFileScopeGrantedTrigger. Tutaj dodatek ma autoryzację zakresu drive.file dla bieżącego dokumentu:

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