Tworzenie interfejsów edytora Google

Dzięki dodatkom do Google Workspace możesz udostępniać dostosowane interfejsy w edytorach, takich jak Dokumenty, Arkusze i Prezentacje Google. Pozwala to dostarczać użytkownikowi odpowiednie informacje, automatyzować zadania i łączyć systemy innych firm z edytorami.

Dostęp do interfejsu dodatku

Dodatek do Google Workspace możesz otworzyć w edytorach, jeśli jego ikona pojawi się w panelu bocznym szybkiego dostępu Google Workspace w interfejsach 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 aktywator 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 EDITOR_NAME.homepageTrigger dla edytora, w którym użytkownik otwiera dodatek, zamiast niego wyświetla się ogólna karta strony głównej.

  • Interfejsy interfejsu API REST: jeśli dodatek korzysta z interfejsów API REST, możesz dodać aktywatory które żądają dostępu do dokumentu na poziomie pliku za pomocą zakresu drive.file. Po przyznaniu dostępu uruchamia się inny aktywator o nazwie EDITOR_NAME.onFileScopeGrantedTrigger i wyświetla interfejs specyficzny dla pliku.

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

Tworzenie interfejsów dla dodatków do edytora

Aby utworzyć interfejsy dodatków do edytora, wykonaj te czynności:

  1. Dodaj odpowiednie addOns.common, addOns.docs, addOns.sheets, i addOns.slides pola do pliku manifestu projektu skryptu dodatku .
  2. Dodaj do pliku manifestu projektu skryptu wszystkie wymagane zakresy edytora.
  3. Jeśli udostępniasz stronę główną specyficzną dla edytora, zaimplementuj EDITOR_NAME.homepageTrigger funkcję, aby utworzyć interfejs. W przeciwnym razie użyj common.homepageTrigger interfejsu, aby utworzyć wspólną stronę główną dla aplikacji hosta.
  4. Jeśli używasz interfejsów API REST, zaimplementuj proces autoryzacji zakresu drive.file i EDITOR_NAME.onFileScopeGrantedTrigger funkcję aktywatora, aby wyświetlić interfejs specyficzny dla otwartego pliku. Więcej informacji znajdziesz w sekcji Interfejsy interfejsu API REST.
  5. Jeśli konfigurujesz podgląd linków z usługi innej firmy, zaimplementuj zakres https://www.googleapis.com/auth/workspace.linkpreviewproces autoryzacji i linkPreviewTriggers funkcję. Więcej informacji znajdziesz w sekcji Interfejsy podglądu linków.
  6. Zaimplementuj powiązane wywołania zwrotne potrzebne do reagowania na interakcje użytkownika z interfejsem, takie jak kliknięcia przycisków.

Strony główne edytora

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

Funkcja aktywatora strony głównej otrzymuje jako parametr obiekt zdarzenia, który zawiera informacje takie jak platforma klienta. Możesz użyć danych obiektu zdarzenia, aby dostosować tworzenie strony głównej.

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

Wyświetlanie wspólnej strony głównej

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

Poniższy przykład przedstawia część addons pliku manifestu dodatku do Google Workspace. Dodatek 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świetlanie strony głównej specyficznej dla edytora

Aby wyświetlać stronę główną specyficzną dla edytora, dodaj do pliku manifestu dodatku aktywator EDITOR_NAME.homepageTrigger.

Poniższy przykład przedstawia część 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. Wywołanie zwrotne 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 interfejsu 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 specyficzny dla pliku otwartego w aplikacji hosta edytora.

Aby używać funkcji onFileScopeGrantedTrigger, musisz uwzględnić proces autoryzacji zakresu drive.file. Aby dowiedzieć się, jak poprosić o zakres drive.file , przeczytaj artykuł Żądanie dostępu do pliku w przypadku bieżącego dokumentu.

Gdy użytkownik przyzna zakres drive.file, uruchomi się EDITOR_NAME.onFileScopeGrantedTrigger.runFunction. Gdy aktywator się uruchomi, wykona funkcję aktywatora kontekstowego określoną w EDITOR_NAME.onFileScopeGrantedTrigger.runFunction polu 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żywać, 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 aktywator do "sheets" sekcji.
  2. Zaimplementuj funkcję o nazwie w sekcji EDITOR_NAME.onFileScopeGrantedTrigger. Ta funkcja przyjmuje jako zdarzenia obiekt jako argument i musi zwracać pojedynczy Card obiekt lub tablicę Card obiektów.
  3. Podobnie jak w przypadku każdej karty, musisz zaimplementować wywołania zwrotne używane do zapewnienia interaktywności widżetu w interfejsie. Jeśli na przykład dodasz do interfejsu przycisk, powinien on mieć dołączoną czynność i zaimplementowane wywołanie zwrotne, które uruchamia się po kliknięciu przycisku.

Poniższy przykład przedstawia część addons pliku manifestu dodatku do Google Workspace. Dodatek korzysta z interfejsów API REST, dlatego w przypadku Arkuszy Google uwzględniono aktywator onFileScopeGrantedTrigger. Gdy użytkownik przyzna zakres drive.file, wywołanie zwrotne onFileScopeGrantedSheets 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"
      }
    }
  }
}

Aby włączyć podgląd linków do usługi innej firmy, musisz skonfigurować podgląd linków 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.

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

Obiekty zdarzeń

Obiekt zdarzenia jest tworzony i przekazywany do funkcji aktywatora, takich jak EDITOR_NAME.homepageTrigger lub EDITOR_NAME.onFileScopeGrantedTrigger. Funkcja aktywatora używa informacji w obiekcie zdarzenia, aby określić, jak tworzyć karty dodatku lub w inny sposób kontrolować jego działanie.

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

Gdy edytor jest aplikacją hosta dodatku, obiekty zdarzeń zawierają Dokumentów, Arkuszach lub Prezentacjach pola obiektu zdarzenia, 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 edytora.

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

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

O ile nie stwierdzono inaczej, treść tej strony jest objęta licencją Creative Commons – uznanie autorstwa 4.0, a fragmenty kodu są dostępne na licencji Apache 2.0. Szczegółowe informacje na ten temat zawierają zasady dotyczące witryny Google Developers. Java jest zastrzeżonym znakiem towarowym firmy Oracle i jej podmiotów stowarzyszonych.

Ostatnia aktualizacja: 2026-09-14 UTC.