ウィジェット

ウィジェットは、次の 1 つ以上の機能を提供する UI 要素です。

カードやセクションなどの他のウィジェットの構造 、
テキストや画像などのユーザーへの情報 、
ボタン、テキスト入力フィールド、チェックボックスなどの操作の機能 。

カードセクションに追加されたウィジェットのセットによって、アドオン UI 全体が定義されます。ウィジェットは、ウェブとモバイルデバイスの両方で同じ外観と機能を持ちます。リファレンスドキュメントでは、ウィジェットセットを構築するいくつかの方法について説明しています。

アドオンウィジェットは通常、構造ウィジェット、情報ウィジェット、ユーザーインタラクションウィジェットの 3 つのグループに分類されます。

構造ウィジェット

構造ウィジェットは、UI で使用される他のウィジェットのコンテナと組織を提供します。

ボタンセット: 1 つ以上のテキストボタンまたは画像ボタンのコレクションで、水平方向にグループ化されています。
カード: 1 つ以上のカードセクションを含む単一のコンテキストカード。カードナビゲーションを構成して、ユーザーがカード間を移動する方法を定義します。
カードヘッダー: 特定のカードのヘッダー。カードヘッダーには、タイトル、サブタイトル、画像を含めることができます。カードアクションとユニバーサルアクションは、使用されている場合はカードヘッダーに表示されます。
カードセクション: ウィジェットの収集グループ。水平線で他のカードセクションと区切られ、必要に応じてセクションヘッダーを含めることができます。各カードには少なくとも 1 つのカードセクションが必要です。カードセクションにカードやカードヘッダーを追加することはできません。

構造ウィジェットを表示するカードの例

コンテナのいずれかにウィジェットを追加すると、そのウィジェットのコピーが作成されて追加されます。追加後にウィジェットを変更しても、変更はインターフェースに反映されません。ウィジェットを追加する前に、ウィジェットが完成していることを確認してください。追加後にウィジェットを変更する必要がある場合は、カードセクションまたはカード全体を再構築します。詳しくは、カードを構築するをご覧ください。

これらの基本的な構造ウィジェットに加えて、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 クラスに追加します。カードを見るは、コンテキストトリガーで単一のカードオブジェクトが返された場合にのみ表示されます。それ以外の場合、返されたカードは現在のカードに置き換わります。

カードを見るのヘッダーをカスタマイズするには、.setPeekCardHeader メソッドを標準の CardHeader オブジェクトを使用してコンテキストカードの作成時に追加します。デフォルトでは、カードを見るのヘッダーにはアドオンの名前のみが含まれます。カスタマイズされたピークカードの例

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 で示される画像。
DecoratedTextDecoratedText ウィジェットには、ボタンウィジェットまたはスイッチウィジェットを含めることもできます。追加されたスイッチは、切り替えまたはチェックボックスにできます。コンテンツテキストには HTML 形式を使用できます。上部ラベルと下部ラベルにはプレーンテキストを使用する必要があります。
テキスト段落: HTML 形式の要素を含めることができるテキスト段落。

カード内の情報ウィジェットの例

ユーザーインタラクションウィジェット

ユーザーインタラクションウィジェットを使用すると、アドオンはユーザー操作に応答できます。これらのウィジェットをアクションレスポンスで構成して、別のカードを表示したり、URL を開いたり、通知を表示したり、下書きメールを作成したり、他の Apps Script 関数を実行したりできます。詳しくは、インタラクティブカードの作成ガイドをご覧ください。

カードアクション: アドオンヘッダーバーメニューに配置されるメニュー項目。ヘッダーバーメニューには、ユニバーサルアクションとして定義された項目を含めることもできます。これは、アドオンが定義するすべてのカードに表示されます。
日時選択ツール: ユーザーが日付、時刻、またはその両方を選択できるウィジェット。詳しくは、日時選択ツールをご覧ください。
画像ボタン: テキストの代わりに画像を使用するボタン。事前定義されたアイコンのいずれか、または一般公開されているホストされた画像を使用します。
選択入力: オプションのコレクションを表す入力フィールド。選択入力ウィジェットは、チェックボックス、ラジオボタン、プルダウン選択ボックスとして表示されます。
DecoratedText ウィジェットで使用される切り替えウィジェット。デフォルトでは、これらは切り替えスイッチとして表示されますが、チェックボックスとして表示することもできます。
テキストボタン: テキストラベル付きのボタン。テキストボタンの背景色の塗りつぶしを指定します（デフォルトは透明です）。必要に応じてボタンを無効にすることもできます。
テキスト入力: テキスト入力フィールド。ウィジェットには、タイトルテキスト、ヒントテキスト、複数行のテキストを含めることができます。ウィジェットは、テキスト値が変更されたときにアクションをトリガーできます。
グリッド: 複数列のレイアウト。画像、タイトル、サブタイトル、カスタマイズオプション（ボーダーや切り抜きスタイルなど）を使用してアイテムを表します。

`DecoratedText` チェックボックス

ボタンまたはバイナリ切り替えスイッチの代わりに、チェックボックスが添付された DecoratedText ウィジェットを定義できます。切り替えスイッチと同様に、チェックボックスの値は、アクションイベントオブジェクト、この DecoratedText に渡される Action に渡される、setOnClickAction メソッドによって含まれます。

装飾テキストのチェックボックスウィジェットの例

次のコード抜粋は、カードに追加するチェックボックス 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: 2023-02-16 15:00.
改行	`"This is the first line. <br> This is a new line.`"	This is the first line. This is a new line.

ウィジェット コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。