このページは Cloud Translation API によって翻訳されました。

ウィジェット

ウィジェットは、以下の 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`	テスト