Tworzenie interaktywnych kart
Zadbaj o dobrą organizację dzięki kolekcji
Zapisuj i kategoryzuj treści zgodnie ze swoimi preferencjami.
Większość dodatków oprócz prezentowania danych wymaga od użytkownika podania informacji. Podczas tworzenia dodatku na podstawie kart możesz używać interaktywnych widżetów, takich jak przyciski, elementy menu na pasku narzędzi lub pola wyboru, aby poprosić użytkownika o dane, których potrzebuje Twój dodatek, lub udostępnić inne elementy sterujące interakcją.
W większości przypadków możesz uczynić widżety interaktywnymi, łącząc je z określonymi czynnikami i wdrażając wymagane działanie w funkcji wywołania zwrotnego. Szczegółowe informacje znajdziesz w sekcji Działania dodatkowe.
W większości przypadków możesz skonfigurować widżet, aby wykonywał określone działanie po wybraniu lub zaktualizowaniu:
- Utwórz obiekt
Action, podając funkcję wywołania zwrotnego, która ma zostać wykonana, wraz z wymaganymi parametrami.
- Połącz widżet z
Action, wywołując odpowiednią funkcję obsługi widżetu.
- Zaimplementuj funkcję wywołania zwrotnego, aby wdrożyć wymagane działanie.
Przykład
W tym przykładzie ustawiamy przycisk, który po kliknięciu wyświetla powiadomienie dla użytkownika. Kliknięcie powoduje wywołanie funkcji notifyUser() z argumentem określającym tekst powiadomienia. Zwrot utworzonego elementu ActionResponse powoduje wyświetlenie powiadomienia.
/**
* Build a simple card with a button that sends a notification.
* @return {Card}
*/
function buildSimpleCard() {
var buttonAction = CardService.newAction()
.setFunctionName('notifyUser')
.setParameters({'notifyText': 'Button clicked!'});
var button = CardService.newTextButton()
.setText('Notify')
.setOnClickAction(buttonAction);
// ...continue creating widgets, then create a Card object
// to add them to. Return the built Card object.
}
/**
* Callback function for a button action. Constructs a
* notification action response and returns it.
* @param {Object} e the action event object
* @return {ActionResponse}
*/
function notifyUser(e) {
var parameters = e.parameters;
var notificationText = parameters['notifyText'];
return CardService.newActionResponseBuilder()
.setNotification(CardService.newNotification()
.setText(notificationText))
.build(); // Don't forget to build the response!
}
Projektowanie skutecznych interakcji
Podczas projektowania kart interaktywnych pamiętaj o tych kwestiach:
Interaktywne widżety wymagają zwykle co najmniej 1 metody obsługi, aby zdefiniować ich działanie.
Jeśli masz adres URL i chcesz otworzyć go na karcie, użyj funkcji obsługi widżetu setOpenLink().
Dzięki temu nie trzeba definiować obiektu Action ani funkcji wywołania zwrotnego. Jeśli przed otwarciem adresu URL musisz najpierw utworzyć adres URL lub wykonać inne dodatkowe czynności, zdefiniuj zmienną Action i użyj jej zamiast zmiennej setOnClickOpenLinkAction().
Jeśli używasz funkcji obsługi widżetu setOpenLink() lub setOnClickOpenLinkAction(), musisz podać obiekt OpenLink, aby określić, który adres URL ma zostać otwarty. Możesz też użyć tego obiektu do określenia zachowania otwierania i zamykania za pomocą enumeracji OpenAs i OnClose.
W jednym widżecie może być używany ten sam obiekt Action.
Jeśli jednak chcesz podać inną funkcję wywołania zwrotnego, musisz zdefiniować inne obiekty Action.
Funkcje wywołania zwrotnego powinny być proste. Aby zapewnić dodatkom odpowiednią responsywność, usługa kart ogranicza czas wykonywania funkcji wywołania zwrotnego do maksymalnie 30 sekund. Jeśli wykonanie trwa dłużej, interfejs dodatku może nie zaktualizować prawidłowo wyświetlania karty w odpowiedzi na Action .
Jeśli stan danych na zapleczu usługi zewnętrznej zmieni się w wyniku interakcji użytkownika z interfejsem dodatku, zalecamy ustawienie bitu „stan zmieniony” na true, aby wyczyścić istniejące pamięci podręczne po stronie klienta. Więcej informacji znajdziesz w opisie metody ActionResponseBuilder.setStateChanged().
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: 2024-12-22 UTC.
[null,null,["Ostatnia aktualizacja: 2024-12-22 UTC."],[[["\u003cp\u003eCard-based add-ons use interactive widgets like buttons and menus to collect user input and enhance user interactions.\u003c/p\u003e\n"],["\u003cp\u003eWidgets are made interactive by linking them to actions, which trigger callback functions to execute specific behaviors when interacted with.\u003c/p\u003e\n"],["\u003cp\u003eWhen defining widget actions, you can specify a callback function and any necessary parameters using the \u003ccode\u003eAction\u003c/code\u003e object and appropriate handler functions.\u003c/p\u003e\n"],["\u003cp\u003eFor opening URLs, \u003ccode\u003esetOpenLink()\u003c/code\u003e or \u003ccode\u003esetOnClickOpenLinkAction()\u003c/code\u003e can be used with an \u003ccode\u003eOpenLink\u003c/code\u003e object to define the URL and behavior.\u003c/p\u003e\n"],["\u003cp\u003eKeep callback functions concise, as they have execution time limits, and consider using \u003ccode\u003esetStateChanged()\u003c/code\u003e to update the UI when backend data changes due to user interactions.\u003c/p\u003e\n"]]],["Card-based add-ons use interactive widgets like buttons to gather user input or provide controls. Widgets are made interactive by linking them to actions via a callback function. To configure a widget, create an `Action` object with the callback function and parameters, link it using a widget handler function, and implement the callback function. For opening URLs directly, `setOpenLink()` avoids defining an `Action`. Ensure callbacks are simple (under 30 seconds), and for backend data changes, use `setStateChanged()`.\n"],null,["# Building interactive cards\n\nMost add-ons, in addition to presenting data, require the user to enter\ninformation. When you build a card-based add-on, you can use\ninteractive [widgets](/workspace/add-ons/concepts/widgets) such as buttons,\ntoolbar menu items, or checkboxes to ask the user for data that your add-on\nneeds or provide other interaction controls.\n\nAdding actions to widgets\n-------------------------\n\nFor the most part, you make widgets interactive by linking them to\nspecific *actions* and implementing the required behavior in a callback\nfunction. See [add-on actions](/workspace/add-ons/concepts/actions) for details.\n\nIn most cases, you can follow this general procedure to configure a widget to\ntake a specific action when selected or updated:\n\n1. Create an [`Action`](/apps-script/reference/card-service/action) object, specifing the callback function that should execute, along with any required parameters.\n2. Link the widget to the `Action` by calling the appropriate [widget handler function](/workspace/add-ons/concepts/actions#widget_handler_functions).\n3. Implement the [callback function](/workspace/add-ons/concepts/actions#callback_functions) to enact the required behavior.\n\nExample\n-------\n\nThe following example sets a button that displays a user notification\nafter it is clicked. The click triggers the `notifyUser()` callback function\nwith an argument that specifies the notification text. Returning a built\n[`ActionResponse`](/apps-script/reference/card-service/action-response)\nresults in a displayed notification. \n\n /**\n * Build a simple card with a button that sends a notification.\n * @return {Card}\n */\n function buildSimpleCard() {\n var buttonAction = CardService.newAction()\n .setFunctionName('notifyUser')\n .setParameters({'notifyText': 'Button clicked!'});\n var button = CardService.newTextButton()\n .setText('Notify')\n .setOnClickAction(buttonAction);\n\n // ...continue creating widgets, then create a Card object\n // to add them to. Return the built Card object.\n }\n\n /**\n * Callback function for a button action. Constructs a\n * notification action response and returns it.\n * @param {Object} e the action event object\n * @return {ActionResponse}\n */\n function notifyUser(e) {\n var parameters = e.parameters;\n var notificationText = parameters['notifyText'];\n return CardService.newActionResponseBuilder()\n .setNotification(CardService.newNotification()\n .setText(notificationText))\n .build(); // Don't forget to build the response!\n }\n\nDesign effective interactions\n-----------------------------\n\nWhen designing interactive cards, keep the following in mind:\n\n- Interactive widgets usually need at least one handler method to define their\n behavior.\n\n- Use the [`setOpenLink()`](/workspace/add-ons/concepts/actions#setOpenLink) widget\n handler function when you have a URL and just want to open it in a tab.\n This avoids the need to define an\n [`Action`](/apps-script/reference/card-service/action) object and callback\n function. If you need to build the URL first, or take any other additional\n steps before opening the URL, define an\n [`Action`](/apps-script/reference/card-service/action) and use\n [`setOnClickOpenLinkAction()`](/workspace/add-ons/concepts/actions#setOnClickOpenLinkAction)\n instead.\n\n- When using the [`setOpenLink()`](/workspace/add-ons/concepts/actions#setOpenLink)\n or [`setOnClickOpenLinkAction()`](/workspace/add-ons/concepts/actions#setOnClickOpenLinkAction)\n widget handler functions, you need to provide an\n [`OpenLink`](/apps-script/reference/card-service/open-link)\n object to define which URL to open. You can also use this object\n to specify opening and closing behavior using the\n [`OpenAs`](/apps-script/reference/card-service/open-as) and\n [`OnClose`](/apps-script/reference/card-service/on-close) enums.\n\n- It is possible for more than one widget to use the same\n [`Action`](/apps-script/reference/card-service/action) object.\n However, you need to define different\n [`Action`](/apps-script/reference/card-service/action) objects if you want\n to provide the callback function different parameters.\n\n- Keep your callback functions simple. To keep the add-ons responsive, the\n [Card service](/apps-script/reference/card-service/card-service) limits callback functions to a maximum of 30 seconds of\n execution time. If the execution takes longer than that, your add-on UI may\n not update its card display properly in response to the\n [`Action`](/apps-script/reference/card-service/action) .\n\n- If a data status on a third-party backend changes as the result of a user\n interaction with your add-on UI, it is recommended that the add-on set\n a 'state changed' bit to `true` so that any existing client side cache is\n cleared. See the\n [`ActionResponseBuilder.setStateChanged()`](/apps-script/reference/card-service/action-response-builder#setStateChanged(Boolean))\n method description for additional details."]]
