이 페이지는 Cloud Translation API를 통해 번역되었습니다.

Switch to English

위젯

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

다른 위젯의 구조(예: 카드 및 섹션)
사용자에게 표시되는 정보(예: 텍스트, 이미지)
작업 어포던스(예: 버튼, 텍스트 입력란, 체크박스)

카드 섹션에 추가된 위젯 집합은 전체 부가기능 UI를 정의합니다. 위젯은 웹과 휴대기기에서 모양과 기능이 동일합니다. 참조 문서에서는 위젯 세트를 빌드하는 여러 메서드를 설명합니다.

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

구조 위젯

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

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

구조 위젯

이러한 기본 구조 위젯 외에도 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 메시지 열기와 같은 사용자 작업으로 새 문맥 콘텐츠가 트리거되면 새 문맥 콘텐츠를 즉시 표시하거나(기본 동작) 사이드바 하단에 미리보기 카드 알림을 표시할 수 있습니다. 문맥 트리거가 활성화된 상태에서 사용자가 뒤로 를 클릭하여 홈페이지로 돌아가면 사용자가 문맥 콘텐츠를 다시 찾을 수 있도록 미리보기 카드가 표시됩니다.

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

미리보기 카드의 헤더를 맞춤설정하려면 컨텍스트 카드를 빌드할 때 표준 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 위젯은 버튼 또는 스위치 위젯도 포함할 수 있습니다. 추가된 스위치는 전환 또는 체크박스일 수 있습니다. DecoratedText 위젯의 콘텐츠 텍스트는 HTML 형식 지정을 사용할 수 있습니다. 상단과 하단 라벨은 일반 텍스트를 사용해야 합니다.
텍스트 단락: 텍스트 단락으로, HTML 형식 요소를 포함할 수 있습니다.

정보 제공 위젯

사용자 상호작용 위젯

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

카드 작업: 부가기능 헤더 바 메뉴에 배치된 메뉴 항목입니다. 헤더 표시줄 메뉴에는 부가기능이 정의하는 모든 카드에 표시되는 범용 작업으로 정의된 항목도 포함될 수 있습니다.
날짜 시간 선택 도구—사용자가 날짜나 시간 또는 둘 다를 선택할 수 있는 위젯 자세한 내용은 아래의 날짜 및 시간 선택 도구를 참고하세요.
이미지 버튼: 텍스트 대신 이미지를 사용하는 버튼입니다. 여러 사전 정의된 아이콘 중 하나 또는 해당 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 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/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("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 <i>italics</i>."`	기울임꼴입니다.
밑줄	`"This is <u>underline</u>."`	밑줄입니다.
취소선	`"This is <s>strikethrough</s>."`	~~취소선~~입니다.
글꼴 색상	`"This is <font color=\"#FF0000\">red font</font>."`	빨간색 글꼴입니다.
하이퍼링크	`"This is a <a href=\"https://www.google.com\">hyperlink</a>."`	이 링크는 하이퍼링크입니다.
시간	`"This is a time format: <time>2023-02-16 15:00</time>."`	시간 형식은 2023-02-16 15:00입니다.
줄바꿈	`"This is the first line. <br> This is a new line.`"	첫 번째 줄입니다. 줄바꿈입니다.

위젯

위젯 유형

구조 위젯

고정 바닥글

카드 미리보기

정보 제공 위젯

사용자 상호작용 위젯

체크박스 DecoratedText개

날짜 및 시간 선택 도구

그리드

텍스트 서식 지정

체크박스 `DecoratedText`개