ウィジェット

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

ウィジェットは、次のうち 1 つ以上を提供するシンプルな UI 要素です。

  • カードやセクションなど、他のウィジェットの構造
  • ユーザーへの情報(テキストや画像など)
  • ボタン、テキスト入力フィールド、チェックボックスなどのアクションによるアフォーダンス

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

Google Workspace アドオンのデザインキットを使用する

デザイナーは、Figma で利用可能な Google Workspace アドオンの UI デザインキットを使用して、アドオンのウィジェットを設計できます。Figma アカウントを作成するか、組織の管理者にライセンスをリクエストできます。

コンポーネントを参照し、組み込みのテンプレートを使用してウィジェットを作成および可視化します。

デザインキットを入手する

ウィジェットのタイプ

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

構造ウィジェット

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

構造ウィジェット

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

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 メッセージを開くなどのユーザー アクションによって新しいコンテキスト コンテンツがトリガーされると、新しいコンテキスト コンテンツを直ちに表示する(デフォルトの動作)か、サイドバーの下部にピークカード通知を表示できます。コンテキスト トリガーが有効になっているときに、ユーザーが戻る をクリックしてホームページに戻ると、ユーザーがコンテキスト コンテンツをもう一度検索できるようピークカードが表示されます。

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

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

Cats Google Workspace アドオンのクイックスタートに基づいて、次のコードは、Peek カードを使用して新しいコンテキスト コンテンツをユーザーに通知し、選択した Gmail のメッセージ スレッドのサブジェクトを表示するため、Peek カードのヘッダーをカスタマイズします。

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 と公開 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 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"));
      

 

カスタマイズされたカード情報の例

日時選択ツール ウィジェット ハンドラ関数の例を次に示します。このハンドラは、ユーザーが選択した日時を表す文字列を、日時選択ツール ウィジェット内に「&DateTimetPickerWidgetID"」という ID でフォーマットしてログに記録します。

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 分ごとの時間のリストがプルダウン メニューに表示され、その中からユーザーが選択できます。特定の時刻を入力することもできます。モバイル デバイスで時間選択ツールを選択すると、組み込みのモバイル時計アイコンが開きます。

パソコン モバイル
日付選択ツールの選択例 モバイルでの日付選択ツールの選択例
時間選択ツールの選択例 モバイル時間選択ツールの選択例

Grid

グリッド ウィジェットで複数列レイアウトのアイテムを表示します。各アイテムには画像、タイトル、サブタイトルを表示できます。追加の構成オプションを使用して、グリッド アイテム内の画像に対するテキストの位置を設定します。

グリッドに定義されたアクションのパラメータとして返される識別子を使用して、グリッド アイテムを構成できます。

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 タグのみを含めます。 次の形式がサポートされています。

Format レンダリングされた結果
太字 <b>test</b> test
斜体 <i>test</i> test
下線 <u>test</u> test
取り消し線 <s>test</s> test
フォントの色 <font color="#ea9999">test</font> test
ハイパーリンク <a href="http://www.google.com">google</a> Google
時間 <time>2020-02-16 15:00</time> 2020 年 2 月 16 日 15:00
改行 test <br> test
件のテスト