ウィジェット

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

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

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

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

Google Workspace アドオン設計キットを使用する

デザイナーは、アドオンのウィジェットの設計にかかる時間を節約するために、Figma で入手できる Google Workspace アドオン UI デザインキットを使用できます。Figma アカウントを作成するか、組織の管理者にライセンスをリクエストします。

コンポーネントを確認し、組み込みテンプレートを使用してウィジェットを作成して可視化します。

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

ウィジェットのタイプ

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

構造ウィジェット

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

構造ウィジェット

  • ボタンセット - 1 つ以上のテキストボタンまたは画像ボタンの集まり。1 つの行にまとめられます。
  • Card - 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 クラスに追加します。ピークカードは、コンテキスト トリガーを使用して単一のカード オブジェクトが返される場合にのみ表示されます。それ以外の場合は、現在のカードが直ちに置き換えられます。

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

次のコードは、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);
      

 

カスタマイズされたピークカードの例

情報ウィジェット

情報ウィジェット

情報ウィジェットはユーザーに情報を表示します。

  • Image - ホストされている一般公開の 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 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"));
      

 

カスタマイズされたピークカードの例

日時選択ツール ウィジェット ハンドラ関数の例を以下に示します。このハンドラでは、日時選択ツールを 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 分間隔で時間のリストとして表示されます。特定の時刻を入力することもできます。モバイル デバイスで時刻選択ツールを選択すると、組み込みのモバイル時刻選択ツールが開きます。

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

グリッド

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

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

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

形式 レンダリングされた結果
太字 <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-02-16 15:00
改行 test <br> test テスト