위젯은 다음 중 하나 이상을 제공하는 간단한 UI 요소입니다.
- 카드, 섹션 등 기타 위젯의 구조
- 사용자에게 제공하는 정보(예: 텍스트, 이미지)
- 버튼, 텍스트 입력란, 체크박스와 같은 작업 어포던스
카드 섹션에 추가된 위젯 집합은 전체 부가기능 UI를 정의합니다. 위젯은 웹과 휴대기기에서 모양과 기능이 동일합니다. 참조 문서에서는 위젯 세트를 빌드하는 여러 방법을 설명합니다.
Google Workspace 부가기능 디자인 키트 사용하기
디자이너는 부가기능 위젯을 설계하는 시간을 절약하기 위해 Figma에서 제공하는 Google Workspace 부가기능 UI 디자인 키트를 사용할 수 있습니다. Figma 계정을 만들거나 조직 관리자에게 라이선스를 요청할 수 있습니다.
구성요소를 탐색하고 기본 제공 템플릿을 사용하여 위젯을 만들고 시각화합니다.
위젯 유형
부가기능 위젯은 일반적으로 구조 위젯, 정보 위젯, 사용자 상호작용 위젯이라는 세 가지 그룹으로 분류됩니다.
구조 위젯
구조 위젯은 AI에 사용되는 다른 위젯을 위한 컨테이너와 구성을 제공합니다.
- 버튼 세트 - 하나 이상의 텍스트 또는 이미지 버튼 모음으로 가로 행으로 그룹화됩니다.
- 카드: 카드 섹션이 하나 이상 포함된 단일 컨텍스트 카드입니다. 카드 탐색을 구성하여 사용자가 카드 간에 이동하는 방식을 정의합니다.
- 카드 헤더: 지정된 카드의 헤더입니다. 카드 헤더에는 제목, 부제목, 이미지가 포함될 수 있습니다. 부가기능에서 사용하는 경우 카드 작업 및 범용 작업이 카드 헤더에 표시됩니다.
- 카드 섹션 - 가로 카드 규칙으로 다른 카드 섹션으로 나뉘며 선택적으로 섹션 헤더가 있는 수집된 위젯 그룹입니다. 각 카드에는 카드 섹션이 하나 이상 있어야 합니다. 카드 섹션에는 카드나 카드 헤더를 추가할 수 없습니다.
이러한 기본 구조 위젯 외에도 Google Workspace 부가기능에서 카드 서비스를 사용하여 현재 카드와 겹치는 구조(고정 바닥글 및 미리보기 카드)를 만들 수 있습니다.
고정 바닥글
이제 카드 하단에 고정 버튼 행을 추가할 수 있습니다. 이 행은 나머지 카드 콘텐츠와 함께 이동하거나 스크롤하지 않습니다. 다음 코드 발췌 부분은 고정 바닥글 예를 정의하고 이를 카드에 추가하는 방법을 보여줍니다.
var fixedFooter = CardService.newFixedFooter()
.setPrimaryButton(
CardService.newTextButton()
.setText("help")
.setOpenLink(CardService.newOpenLink()
.setUrl("https://www.google.com")))
.setSecondaryButton(
CardService.newTextButton()
.setText("submit")
.setOnClickAction(
CardService.newAction()
.setFunctionName(
"submitCallback")));
var card = CardService.newCardBuilder()
// (...)
.setFixedFooter(fixedFooter)
.build();
|
|
카드 미리보기
Gmail 메시지 열기와 같은 사용자 작업에 의해 새로운 문맥 콘텐츠가 트리거되면 새로운 상황별 콘텐츠를 즉시 표시하거나(기본 동작) 사이드바 하단에 미리보기 카드 알림을 표시할 수 있습니다. 문맥 트리거가 활성화된 상태에서 사용자가 뒤로 를 클릭하여 홈페이지로 돌아가면 사용자가 컨텍스트 콘텐츠를 다시 찾을 수 있도록 미리보기 카드가 표시됩니다.
새 문맥 콘텐츠를 사용할 수 있을 때 미리보기 카드를 표시하려면 새로운 문맥 콘텐츠를 즉시 표시하는 대신 CardBuilder 클래스에 .setDisplayStyle(CardService.DisplayStyle.PEEK)를 추가합니다. 미리보기 카드는 단일 카드 객체가 컨텍스트 트리거와 함께 반환되는 경우에만 표시되며, 그렇지 않으면 반환된 카드가 현재 카드를 즉시 대체합니다.
미리보기 카드의 헤더를 맞춤설정하려면 컨텍스트 카드를 빌드할 때 .setPeekCardHeader() 메서드를 표준 CardHeader 객체로 추가합니다. 기본적으로 Peek 카드 헤더에는 부가기능의 이름만 포함됩니다.
Cats Google Workspace 부가기능 빠른 시작에 기반한 다음 코드는 Peek 카드를 사용하여 사용자에게 새로운 문맥 콘텐츠를 알리고 Peek 카드의 헤더를 맞춤설정하여 선택한 Gmail 메시지 대화목록의 제목을 표시합니다.
var peekHeader = CardService.newCardHeader()
.setTitle('Contextual Cat')
.setImageUrl('https://www.gstatic.com/images/
icons/material/system/1x/pets_black_48dp.png')
.setSubtitle(text);
. . .
var card = CardService.newCardBuilder()
.setDisplayStyle(CardService.DisplayStyle.PEEK)
.setPeekCardHeader(peekHeader);
|
|
정보 위젯
정보 위젯은 사용자에게 정보를 표시합니다.
- 이미지 - 사용자가 호스팅하고 공개적으로 액세스할 수 있는 URL로 표시된 이미지입니다.
- DecoratedText—상단 및 하단 텍스트 라벨, 이미지 또는 아이콘과 같은 다른 요소와 페어링할 수 있는 텍스트 콘텐츠 문자열입니다. DecoratedText 위젯에는 버튼 또는 스위치 위젯도 포함될 수 있습니다. 추가된 스위치는 간단한 전환 버튼 또는 체크박스일 수 있습니다. DecoratedText 위젯의 콘텐츠 텍스트는 HTML 형식 지정을 사용할 수 있습니다. 상단 및 하단 라벨은 일반 텍스트를 사용해야 합니다.
- 텍스트 단락 - HTML 형식 요소를 포함할 수 있는 간단한 텍스트 단락입니다.
사용자 상호작용 위젯
사용자 상호작용 위젯을 사용하면 부가기능에서 사용자가 수행한 작업에 응답할 수 있습니다. 이러한 위젯을 작업 응답으로 구성하여 다양한 카드 표시, URL 열기, 알림 표시, 이메일 초안 작성 또는 기타 Apps Script 함수를 실행할 수 있습니다. 자세한 내용은 양방향 카드 빌드 가이드를 참고하세요.
- 카드 작업 - 부가기능 헤더 바 메뉴에 배치되는 메뉴 항목입니다. 헤더 표시줄 메뉴에는 부가기능이 정의하는 모든 카드에 표시되는 범용 작업으로 정의된 항목도 포함될 수 있습니다.
- DateTime 선택 도구: 사용자가 날짜, 시간 또는 둘 다를 선택할 수 있는 위젯 자세한 내용은 아래의 날짜 및 시간 선택 도구를 참고하세요.
- 이미지 버튼 - 텍스트 대신 이미지를 사용하는 버튼입니다. 사전 정의된 여러 아이콘 중 하나를 사용하거나 URL로 표시된 공개 호스팅 이미지를 사용할 수 있습니다.
- 선택 입력 - 옵션 모음을 나타내는 입력 필드입니다. 선택 입력 위젯은 체크박스, 라디오 버튼, 드롭다운 선택 상자로 표시됩니다.
- 스위치 - 전환 위젯입니다. 스위치는 DecoratedText 위젯과 함께만 사용할 수 있습니다. 기본적으로 이러한 컨트롤은 전환 스위치로 표시되지만, 대신 체크박스로 표시할 수 있습니다.
- 텍스트 버튼 - 텍스트 라벨이 있는 버튼. 텍스트 버튼의 배경 색상 채우기를 지정할 수 있습니다. 기본값은 투명합니다. 필요에 따라 버튼을 사용 중지할 수도 있습니다.
- 텍스트 입력 - 텍스트 입력 필드입니다. 위젯에는 제목 텍스트, 힌트 텍스트, 여러 줄 텍스트가 포함될 수 있습니다. 텍스트 값이 변경되면 위젯에서 작업을 트리거할 수 있습니다.
- 그리드—항목 모음을 나타내는 다중 열 레이아웃 이미지, 제목, 부제목, 테두리/자르기 스타일 등 다양한 맞춤설정 옵션으로 항목을 표현할 수 있습니다.
DecoratedText 체크박스
버튼이나 바이너리 전환 스위치 대신 체크박스가 연결된 DecoratedText 위젯을 정의할 수 있습니다. 스위치와 마찬가지로 체크박스의 값은 setOnClickAction(action) 메서드에 의해 이 DecoratedText에 연결된 Action에 전달되는 작업 이벤트 객체에 포함됩니다.
다음 코드 발췌 부분은 체크박스 DecoratedText 위젯을 정의하는 방법을 보여줍니다. 이 위젯을 카드에 추가할 수 있습니다.
var decoratedText = CardService.newDecoratedText()
// (...)
.setSwitch(CardService.newSwitch()
.setFieldName('form_input_switch_key')
.setValue('switch_is_on')
.setControlType(
CardService.SwitchControlType.CHECK_BOX));
|
|
날짜 및 시간 선택 도구
사용자가 시간, 날짜 또는 둘 다를 선택할 수 있는 위젯을 정의할 수 있습니다.
선택 도구 값이 변경되면 실행할 위젯 핸들러 함수를 setOnChangeAction()에 사용할 수 있습니다.
다음 코드 발췌 부분은 날짜 전용 선택 도구, 시간 전용 선택 도구, 날짜-시간 선택 도구를 정의하는 방법을 보여줍니다. 이러한 선택 항목은 카드에 추가할 수 있습니다.
var dateOnlyPicker = CardService.newDatePicker()
.setTitle("Enter the date.")
.setFieldName("date_field")
// Set default value as May 24 2019. Either a
// number or string is acceptable.
.setValueInMsSinceEpoch(1558668600000)
.setOnChangeAction(CardService.newAction()
.setFunctionName("handleDateChange"));
var timeOnlyPicker = CardService.newTimePicker()
.setTitle("Enter the time.")
.setFieldName("time_field")
// Set default value as 23:30.
.setHours(23)
.setMinutes(30)
.setOnChangeAction(CardService.newAction()
.setFunctionName("handleTimeChange"));
var dateTimePicker = CardService.newDateTimePicker()
.setTitle("Enter the date and time in EDT time.")
.setFieldName("date_time_field")
// Set default value as May 24 2019 03:30 AM UTC.
// Either a number or string is acceptable.
.setValueInMsSinceEpoch(1558668600000)
// EDT time is 4 hours behind UTC.
.setTimeZoneOffsetInMins(-4 * 60)
.setOnChangeAction(CardService.newAction()
.setFunctionName("handleDateTimeChange"));
|
|
다음은 날짜-시간 선택 도구 위젯 함수의 예시입니다. 이 핸들러는 ID가 'myDateTimePickerWidgetID'인 날짜-시간 선택 도구 위젯에서 사용자가 선택한 날짜-시간을 나타내는 문자열의 형식을 지정하고 기록합니다.
function handleDateTimeChange(event) {
var dateTimeInput =
event.commonEventObject.formInputs["myDateTimePickerWidgetID"];
var msSinceEpoch = dateTimeInput.msSinceEpoch;
var hasDate = dateTimeInput.hasDate;
var hasTime = dateTimeInput.hadTime;
// The following requires you to configure the add-on to read user locale
// and timezone.
// See https://developers.google.com/apps-script/add-ons/how-tos/access-user-locale
var userTimezoneId = event.userTimezone.id;
// Format and log the date-time selected using the user's timezone.
var formattedDateTime;
if (hasDate && hasTime) {
formattedDateTime = Utilities.formatDate(
new Date(msSinceEpoch), userTimezoneId, "yyy/MM/dd hh:mm:ss");
} else if (hasDate) {
formattedDateTime = Utilities.formatDate(
new Date(msSinceEpoch), userTimezoneId, "yyy/MM/dd")
+ ", Time unspecified";
} else if (hasTime) {
formattedDateTime = "Date unspecified, "
+ Utilities.formatDate(
new Date(msSinceEpoch), userTimezoneId, "hh:mm a");
}
if (formattedDateTime) {
console.log(formattedDateTime);
}
}
아래 표는 데스크톱 및 휴대기기의 선택 도구 선택 UI의 예를 보여줍니다. 이 옵션을 선택하면 날짜 선택 도구가 월 기반 캘린더 UI를 열어 사용자가 새 날짜를 빠르게 선택할 수 있도록 합니다.
사용자가 데스크톱 기기에서 시간 선택 도구를 선택하면 30분 단위로 구분된 시간 목록이 포함된 드롭다운 메뉴가 열립니다. 사용자가 특정 시간을 입력할 수도 있습니다. 휴대기기에서 시간 선택 도구를 선택하면 내장된 모바일 '시계' 시간 선택 도구가 열립니다.
| 데스크톱 | 모바일 |
|---|---|
|
|
|
|
그리드
그리드 위젯을 사용하여 항목을 다중 열 레이아웃으로 표시합니다. 각 항목에는 이미지, 제목, 부제목이 표시될 수 있습니다. 추가 구성 옵션을 사용하여 그리드 항목의 이미지를 기준으로 텍스트의 위치를 설정합니다.
그리드에 정의된 작업의 매개변수로 반환되는 식별자를 사용하여 그리드 항목을 구성할 수 있습니다.
var gridItem = CardService.newGridItem()
.setIdentifier("item_001")
.setTitle("A grid item")
.setSubtitle("with a subtitle")
.setImage(imageComponent);
var cropStyle = CardService.newImageCropStyle()
.setImageCropType(CardService.ImageCropType.SQUARE);
var borderStyle = CardService.newBorderStyle()
.setType(CardService.BorderType.STROKE)
.setCornerRadius(8)
.setStrokeColor("#00FF00FF");
var imageComponent = CardService.newImageComponent()
.setImageUrl("https://cataas.com/cat?0.001")
.setCropStyle(cropStyle)
.setBorderStyle(borderStyle);
var grid = CardService.newGrid()
.setTitle("My first grid")
.addItem(gridItem)
.setNumColumns(2)
.setOnClickAction(CardService.newAction()
.setFunctionName("handleGridItemClick"));
|
|
텍스트 서식 지정
일부 텍스트 기반 위젯은 간단한 텍스트 HTML 형식을 지원할 수 있습니다. 이러한 위젯의 텍스트 콘텐츠를 설정할 때는 해당하는 HTML 태그만 포함하면 됩니다.
다음 표에는 지원되는 태그와 그 용도가 나와 있습니다.
| 형식 | 예 | 렌더링된 결과 |
|---|---|---|
| 굵게 | "This is <b>bold</b>." |
굵은 글꼴입니다. |
| 기울임꼴 | "This is <i>italics</i>." |
기울임꼴입니다. |
| 밑줄 | "This is <u>underline</u>." |
밑줄입니다. |
| 취소선 | "This is <s>strikethrough</s>." |
이 경우 |
| 글꼴 색상 | "This is <font color=\"#FF0000\">red font</text>." |
이는 빨간색 글꼴입니다. |
| 하이퍼링크 | "This is a <a href=\"https://www.google.com\">hyperlink</a>." |
하이퍼링크입니다. |
| 시간 | "This is a time format: <time>2023-02-16 15:00</time>." |
시간 형식은 입니다. |
| 줄바꿈 | "This is the first line. <br> This is a new line." |
첫 번째 줄입니다. 새 줄입니다. |