부가기능 작업은 위젯에 대화형 동작을 제공합니다. 작업을 만들어 사용자가 위젯을 선택하거나 업데이트할 때 발생하는 작업을 정의합니다.
대부분의 경우 Apps Script 카드 서비스에서 제공하는 Action 객체를 사용하여 부가기능 작업을 정의할 수 있습니다.
각 Action를 만들 때 콜백 함수와 연결됩니다. 콜백 함수를 구현하여 사용자가 위젯과 상호작용할 때 원하는 단계를 실행합니다. 또한 Action 콜백을 트리거하는 상호작용의 유형을 정의하는 적절한 위젯 핸들러 함수를 사용하여 Action를 위젯에 연결해야 합니다.
다음 일반 프로세스를 사용하여 Action로 위젯을 구성합니다.
Action객체를 만들고 필요한 매개변수와 함께 실행해야 하는 콜백 함수를 지정합니다.Action객체를 사용하여 위젯에서 적절한 위젯 핸들러 함수를 호출합니다.- 콜백 함수를 구현하여 필요한 동작을 적용합니다.
위젯 핸들러 함수
위젯을 특정 Action 또는 다른 동작에 연결하려면 위젯 핸들러 함수를 사용합니다. 핸들러 함수는 작업 유형(예: 위젯 클릭 또는 텍스트 필드 수정)을 트리거하는 상호작용 유형을 결정합니다. 또한 핸들러 함수는 작업이 완료된 후 UI가 실행하는 단계(있는 경우)를 정의합니다.
다음 표에는 위젯의 다양한 핸들러 유형과 함께 사용되는 위젯이 나와 있습니다.
| 핸들러 함수 | 트리거 작업 | 관련 위젯 | 설명 |
|---|---|---|---|
setOnChangeAction() |
위젯 값이 변경됨 |
DatePickerDateTimePickerSelectionInputSwitchTextInput
TimePicker
|
사용자가 입력에 텍스트를 입력하고 Enter 키를 누르는 등 위젯에 포커스가 없을 때 Apps Script 함수를 실행하는 Action를 설정합니다. 핸들러는 이벤트 객체를 호출하는 함수에 자동으로 전달합니다.
원하는 경우 이 이벤트 객체에 추가 매개변수 정보를 삽입할 수 있습니다. |
setOnClickAction() |
사용자가 위젯을 클릭합니다. |
CardActionImageImageButtonDecoratedTextTextButton
|
사용자가 위젯을 클릭할 때 Apps Script 함수를 실행하는 Action를 설정합니다. 핸들러는 이벤트 객체를 호출하는 함수에 자동으로 전달합니다.
이 이벤트 객체에 선택적 매개변수 정보를 삽입할 수 있습니다. |
setComposeAction() |
사용자가 위젯을 클릭합니다. |
CardActionImageImageButtonDecoratedTextTextButton
|
Gmail 전용 이메일 초안을 작성한 다음 해당 초안을 Gmail UI 편지쓰기 창에서 사용자에게 표시하는 Action를 설정합니다. Gmail에서 초안을 새 메시지 또는
열린 메시지에 대한 답장으로 작성할 수 있습니다. 초안 빌드 콜백 함수를 호출할 때 이 콜백은 이벤트 객체를 콜백 함수에 전달합니다.
자세한 내용은 초안 메시지 작성을 참조하세요. |
setOnClickOpenLinkAction() |
사용자가 위젯을 클릭합니다. |
CardActionImageImageButtonDecoratedTextTextButton
|
사용자가 위젯을 클릭할 때 URL이 열리도록 Action를 설정합니다. URL을 구성해야 하거나 링크가 열리기 전에 다른 작업이 이루어져야 할 때 이 핸들러를 사용하세요. 그렇지 않으면 일반적으로 setOpenLink()를 사용하는 것이 더 간단합니다.
URL은 새 창에서만 열 수 있습니다. 닫을 때 UI에서 부가기능을 새로고침하도록 할 수 있습니다. |
setOpenLink() |
사용자가 위젯을 클릭합니다. |
CardActionImageImageButtonDecoratedTextTextButton
|
사용자가 위젯을 클릭하면 URL을 바로 엽니다. URL을 알고 있고 열어야 하는 경우에만 이 핸들러를 사용하세요. 그렇지 않으면 setOnClickOpenLinkAction()를 사용합니다.
URL은 새 창 또는 오버레이에서 열 수 있습니다. 닫을 경우 UI에서 부가기능을 새로고침하도록 할 수 있습니다. |
setSuggestionsAction() |
사용자가 입력에 텍스트를 입력합니다. |
TextInput
|
사용자가 텍스트 입력 위젯에 텍스트를 입력할 때 Apps Script 함수를 실행하는 Action를 설정합니다. 핸들러는 이벤트 객체를 호출하는 함수에 자동으로 전달합니다.
자세한 내용은 텍스트 입력에 대한 자동 완성 제안을 참조하세요. |
콜백 함수
콜백 함수는 Action가 트리거될 때 실행됩니다. 콜백 함수는 Apps Script 함수이므로 다른 스크립트 함수로 가능한 거의 모든 작업을 수행할 수 있습니다.
콜백 함수는 경우에 따라 특정 응답 객체를 반환합니다. 이러한 유형의 응답은 새 카드 표시 또는 자동 완성 추천 제시와 같이 콜백 실행이 완료된 후에 실행해야 하는 추가 작업을 나타냅니다. 콜백 함수가 특정 응답 객체를 반환해야 하는 경우 카드 서비스의 빌더 클래스를 사용하여 그 객체를 구성합니다.
다음 표에서는 콜백 함수가 특정 작업에 대해 특정 응답 객체를 반환해야 하는 경우를 보여줍니다. 이러한 작업은 모두 부가기능이 확장하는 특정 호스트 애플리케이션과는 별개입니다.
| 시도한 작업 | 콜백 함수는 |
|---|---|
| 카드 간 탐색 | ActionResponse |
Notification 표시 |
ActionResponse |
setOnClickOpenLinkAction()를 사용하여 링크 열기 |
ActionResponse |
| 자동 완성 추천 검색어 표시 | SuggestionResponse |
| 범용 작업 사용 | UniversalActionResponse |
| 기타 작업 | Nothing |
이러한 작업 외에도 각 호스트 애플리케이션에는 해당 호스트에서만 수행할 수 있는 자체 작업 집합이 있습니다. 자세한 내용은 다음 가이드를 참고하세요.
작업 이벤트 객체
부가기능에서 Action를 트리거하면 UI가 자동으로 JSON 이벤트 객체를 구성하고 Action 콜백 함수에 인수로 전달합니다. 이 이벤트 객체에는 표시된 카드의 모든 대화형 위젯의 현재 값과 같은 사용자의 현재 클라이언트 측 컨텍스트에 대한 정보가 포함됩니다.
작업 이벤트 객체에는 포함된 정보를 구성하는 특정 JSON 구조가 있습니다. 홈페이지 트리거가 홈페이지를 만들 때 또는 부가기능 디스플레이를 업데이트하기 위해 문맥 트리거가 실행될 때 동일한 구조가 사용됩니다.
이벤트 객체 구조에 대한 자세한 설명은 이벤트 객체를 참고하세요.