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 elementuEDITOR_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 nazwieEDITOR_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:
- Dodaj odpowiednie pola
addOns.common
,addOns.docs
,addOns.sheets
iaddOns.slides
do pliku manifestu dodatku w projekcie dodatku. - Dodaj dowolne wymagane zakresy edytora do pliku manifestu projektu skryptu.
- Jeśli udostępniasz stronę główną edytora, zaimplementuj funkcję
EDITOR_NAME.homepageTrigger
, aby utworzyć interfejs. Jeśli nie, użyj interfejsucommon.homepageTrigger
do utworzenia wspólnej strony głównej dla aplikacji hostowanych. - 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). - 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. - 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
.
- 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"
. - Zaimplementuj funkcję o nazwie w sekcji
EDITOR_NAME.onFileScopeGrantedTrigger
. Ta funkcja akceptuje obiekt zdarzenia jako argument i musi zwracać pojedynczy obiektCard
lub tablicę obiektówCard
. - 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" } }
Interfejsy podglądu linków do usług innych firm
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" }, ... }