ウィジェット

ウィジェットは、次の 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 メールを開くなどのユーザー操作によって新しいコンテキスト コンテンツがトリガーされると、新しいコンテキスト コンテンツをすぐに表示するか(デフォルトの動作)、サイドバーの下部にピークカード通知を表示できます。コンテキスト トリガーが有効な状態で、ユーザーが戻るボタン をクリックしてホームページに戻ると、ピークカードが表示され、ユーザーがコンテキスト コンテンツを再び見つけられるようになります。

新しいコンテキスト コンテンツが利用可能になったときにピークカードを表示するには、新しいコンテキスト コンテンツをすぐに表示するのではなく、CardBuilder クラスに .setDisplayStyle(CardService.DisplayStyle.PEEK) を追加します。ピークカードは、コンテキスト トリガーで単一のカード オブジェクトが返された場合にのみ表示されます。それ以外の場合は、返されたカードが直ちに現在のカードを置き換えます。

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

次のコードは、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 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>." これは赤いフォントです。
Hyperlink "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. インチ これは最初の行です。
これは新しい行です。