위젯

위젯은 다음 중 하나 이상을 제공하는 UI 요소입니다.

  • 카드 및 섹션과 같은 다른 위젯의 구조,
  • 텍스트 및 이미지와 같은 사용자에게 제공되는 정보 또는
  • 버튼, 텍스트 입력란 또는 체크박스와 같은 작업을 위한 어포던스

카드 섹션에 추가된 위젯 세트는 전체 부가기능 UI를 정의합니다. 위젯은 웹 및 모바일 기기에서 동일한 모양과 기능을 갖습니다. 참조 문서 에서는 위젯 세트를 빌드하는 여러 방법을 설명합니다.

위젯 유형

부가기능 위젯은 일반적으로 구조 위젯, 정보 위젯, 사용자 상호작용 위젯의 세 그룹으로 분류됩니다.

구조 위젯

구조 위젯은 UI에 사용되는 다른 위젯을 위한 컨테이너와 구성을 제공합니다.

  • 버튼 세트: 하나 이상의 텍스트 또는 이미지 버튼 모음으로, 가로 행으로 함께 그룹화됩니다.
  • 카드: 하나 이상의 카드 섹션이 포함된 단일 컨텍스트 카드입니다. 카드 탐색을 구성하여 사용자가 카드 간에 이동하는 방법을 정의합니다.
  • 카드 헤더: 지정된 카드의 헤더입니다. 카드 헤더에는 제목, 부제목, 이미지가 있을 수 있습니다. 카드 작업범용 작업은 사용되는 경우 카드 헤더에 표시됩니다.
  • 카드 섹션: 가로 규칙으로 다른 카드 섹션과 구분되고 섹션 헤더가 선택적으로 있는 위젯의 수집된 그룹입니다. 각 카드에는 카드 섹션이 하나 이상 있어야 합니다. 카드 섹션에 카드 또는 카드 헤더를 추가할 수 없습니다.

구조적 위젯을 보여주는 카드의 예

컨테이너 중 하나에 위젯을 추가하면 해당 위젯의 사본이 생성되고 추가됩니다. 위젯을 추가한 후 변경해도 변경사항이 인터페이스에 반영되지 않습니다. 위젯을 추가하기 전에 위젯이 완료되었는지 확인하세요. 위젯을 추가한 후 변경해야 하는 경우 전체 카드 섹션 또는 카드를 다시 빌드하세요. 자세한 내용은 카드 구성을 참고하세요.

이러한 기본 구조 위젯 외에도 Google Workspace 부가기능에서 카드 서비스를 사용하여 현재 카드와 겹치는 구조(고정 바닥글 및 카드 미리보기)를 만들 수 있습니다.

카드 하단에 고정된 버튼 행을 추가할 수 있습니다. 이 행은 나머지 카드 콘텐츠와 함께 이동하거나 스크롤되지 않습니다.

고정된 바닥글 위젯 예시

다음 코드 발췌문은 고정 바닥글의 예를 정의하고 이를 카드에 추가하는 방법을 보여줍니다.

var fixedFooter = CardService.newFixedFooter()
    .setPrimaryButton(
        CardService.newTextButton()
            .setText("Primary")
            .setOpenLink(CardService.newOpenLink()
                .setUrl("https://www.google.com")))
    .setSecondaryButton(
        CardService.newTextButton()
            .setText("Secondary")
            .setOnClickAction(
                CardService.newAction()
                    .setFunctionName(
                        "secondaryCallback")));

var card = CardService.newCardBuilder()
    // (...)
    .setFixedFooter(fixedFooter)
    .build();

카드 미리보기

엿보기 카드 알림의 예

Gmail 메시지 열기와 같은 사용자 작업으로 새 컨텍스트 콘텐츠가 트리거되면 새 컨텍스트 콘텐츠를 즉시 표시하거나(기본 동작) 사이드바 하단에 카드 미리보기 알림을 표시할 수 있습니다. 컨텍스트 트리거가 활성 상태인 동안 사용자가 뒤로 를 클릭하여 홈페이지로 돌아가면 사용자가 컨텍스트 콘텐츠를 다시 찾을 수 있도록 카드 미리보기가 표시됩니다.

새 컨텍스트 콘텐츠를 사용할 수 있을 때 카드 미리보기를 표시하려면 .setDisplayStyle(CardService.DisplayStyle.PEEK) 클래스에 CardBuilder 추가하세요. 카드 미리보기는 컨텍스트 트리거와 함께 단일 카드 객체가 반환되는 경우에만 표시됩니다. 그렇지 않으면 반환된 카드가 현재 카드를 대체합니다.

카드 미리보기의 헤더를 맞춤설정하려면 컨텍스트 카드를 빌드할 때 표준 CardHeader 객체와 함께 .setPeekCardHeader 메서드를 추가하세요. 기본적으로 카드 미리보기 헤더에는 부가기능의 이름만 포함됩니다. 맞춤설정된 엿보기 카드 예시

Cats Google Workspace 부가기능 빠른 시작을 기반으로 다음 코드는 카드 미리보기로 새 컨텍스트 콘텐츠를 사용자에게 알리고 선택한 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 위젯에는 버튼 또는 스위치 위젯도 포함될 수 있습니다. 추가된 스위치 는 전환 버튼 또는 체크박스일 수 있습니다. 콘텐츠 텍스트 는 HTML 형식을 사용할 수 있습니다. 상단 및 하단 라벨은 일반 텍스트를 사용해야 합니다.
  • 텍스트 단락: HTML 형식 요소가 포함될 수 있는 텍스트 단락입니다.

카드에 있는 정보 위젯의 예

사용자 상호작용 위젯

사용자 상호작용 위젯을 사용하면 부가기능이 사용자 작업에 응답할 수 있습니다. 작업 응답으로 이러한 위젯을 구성하여 다른 카드를 표시하거나, URL을 열거나, 알림을 표시하거나, 초안 이메일을 작성하거나, 다른 Apps Script 함수를 실행합니다. 자세한 내용은 대화형 카드 빌드 가이드를 참고하세요.

카드 작업을 보여주는 메뉴의 예 카드에 있는 사용자 상호작용 위젯의 예

DecoratedText 체크박스

버튼 또는 바이너리 전환 버튼 대신 체크박스가 연결된 DecoratedText 위젯을 정의할 수 있습니다. 전환 버튼과 마찬가지로 체크박스의 값은 작업 이벤트 객체 로 전달되는 Action에 연결된 이 DecoratedTextsetOnClickAction 메서드로 포함됩니다.

장식된 텍스트 체크박스 위젯 예시

다음 코드 발췌문은 카드에 추가할 체크박스 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 a 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 a 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 a date and 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/workspace/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("Lucian R.")
  .setSubtitle("Chief Information Officer")
  .setImage(imageComponent);

var cropStyle = CardService.newImageCropStyle()
  .setImageCropType(CardService.ImageCropType.RECTANGLE_4_3);

var imageComponent = CardService.newImageComponent()
  .setImageUrl("https://developers.google.com/workspace/
      images/cymbal/people/person1.jpeg")
  .setCropStyle(cropStyle)

var grid = CardService.newGrid()
  .setTitle("Recently viewed")
  .addItem(gridItem)
  .setNumColumns(2)
  .setOnClickAction(CardService.newAction()
    .setFunctionName("handleGridItemClick"));

텍스트 서식 지정

일부 텍스트 기반 위젯은 기본 텍스트 HTML 서식 지정을 지원합니다. 이러한 위젯의 텍스트 콘텐츠를 설정할 때는 상응하는 HTML 태그를 포함하세요.

지원되는 태그와 그 목적은 다음 표에 나와 있습니다.

형식 렌더링된 출력
굵게 "This is <b>bold</b>." This is bold.
기울임꼴 "This is <i>italics</i>." This is italics.
밑줄 "This is <u>underline</u>." This is underline.
취소선 "This is <s>strikethrough</s>." This is strikethrough.
글꼴 색상 "This is <font color=\"#FF0000\">red font</font>." This is red font.
Hyperlink "This is a <a href=\"https://www.google.com\">hyperlink</a>." This is a hyperlink.
시간 "This is a time format: <time>2023-02-16 15:00</time>." This is a time format: .
줄바꿈 "This is the first line. <br> This is a new line." This is the first line.
This is a new line.