ウィジェット

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

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

カード セクションに追加されたウィジェットのセットでは、 できます。ウィジェット ウェブとモバイル デバイスで同じデザインと機能を使用できます。「 リファレンス ドキュメント では、ウィジェット セットを作成するためのいくつかのメソッドについて説明しています。

ウィジェットのタイプ

アドオン ウィジェットは大きく 3 つに分類される グループ: 構造ウィジェット、 情報ウィジェット、ユーザー操作ウィジェットです

構造ウィジェット

構造用ウィジェットは他のウィジェットのコンテナと整理を行う UI で使用されます。

  • ボタンセット - A 1 つ以上のテキストまたは画像のボタンのコレクションで、 選択します。
  • カード - 単一のコンテキスト 1 つまたは複数のカード セクションを含むカード。管理者は、ユーザーがリソースをどのように移動できるかを カード間を切り替えることができます。 カード ナビゲーション
  • カードヘッダー - 表示されます。カードのヘッダーには、タイトル、サブタイトル、 説明します。カード アクションユニバーサル アクションは カードヘッダー(アドオンで使用されている場合)
  • カード セクション - A ウィジェットのグループで、他のカード セクションから 必要に応じてセクションヘッダーも設定できます。各カードには 少なくとも 1 つのカード セクションが必要です。カードやカードヘッダーをカードに追加することはできません 。

構造ウィジェット

これらの基本的な構造ウィジェットに加えて、 Google Workspace アドオンを使って Card サービス: 現在のカードに重ねる構造を作成します。 固定フッターピークカード:

カードの下部に、固定された列のボタンを追加できます。この行 他のカード コンテンツと一緒に移動したりスクロールしたりしない。

固定フッター ウィジェットの例

次の コードの抜粋は、固定されたフッターの例を定義してカードに追加する方法を示しています。

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();

カードを見る

ピークカードの例

新しいコンテキスト コンテンツが ページを開くなどのユーザー操作によって 新しいコンテキスト コンテンツを直ちに表示することも、 (デフォルトの動作)、または画面の下部にピークカード通知を表示するか、 クリックします。ユーザーが戻るアイコン をクリックした場合 ホームページに コンテキスト トリガーが有効な場合、 使用します。

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

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

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

次のコードは、 Cats Google Workspace アドオンのクイックスタート ピークカードで新しいコンテキスト コンテンツをユーザーに通知し、カスタマイズ 選択した 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);

情報ウィジェット

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

  • イメージ - 画像 アクセスできます。
  • DecoratedText - A テキスト トップやボトムなどの他の要素と組み合わせることができるコンテンツの文字列。 テキストラベル、画像、アイコンなどですDecoratedText ウィジェットには、 ボタンまたは Switch ウィジェット追加されたスイッチ 切り替えボタンまたはチェックボックスを使用できます。コンテンツ テキスト DecoratedText ウィジェットでは HTML フォーマットトップ ボトムラベルには書式なしテキストを使用する必要があります
  • テキスト段落 - A たとえば、テキスト、段落、 HTML 形式要素。

情報ウィジェット

ユーザー操作ウィジェット

ユーザー操作ウィジェットにより、アドオンはユーザー操作ウィジェットによって できます。アクション レスポンスを含むウィジェットを構成できます。 さまざまなカードの表示、URL を開く、通知の表示、メールの下書きの作成、 その他の Apps Script 関数の実行も可能です。詳しくは、 インタラクティブ カードの作成ガイド 表示されます。

  • カード アクション - メニュー アドオンのヘッダーバー メニューに配置されたアイテム。ヘッダーバーのメニューには ユニバーサル アクションとして定義された項目を含む このカードはアドオンで定義されるすべてのカードに表示されます。
  • 日時選択ツール - ウィジェット ユーザーが日付、時刻、またはその両方を選択できます。詳しくは、 日時選択ツール ご覧ください。
  • 画像ボタン - A テキストの代わりに画像を使用したボタンです。Google Cloud の 事前定義されたアイコンや、その URL で指定される一般公開の画像を使用できます。
  • 選択入力 - 入力フィールドです。選択入力ウィジェット チェックボックス、ラジオボタン、またはプルダウン選択ボックスとして表示されます。
  • スイッチ - 切り替えボタン 追加します。スイッチは、 DecoratedText ウィジェット。デフォルト 切り替えスイッチとして表示されますが、 チェックボックスを使用してください。
  • テキストボタン - A テキストラベルのボタンです。テキストの背景色を指定できます (デフォルトは透明)。このボタンを 必要ありません。
  • テキスト入力 - テキスト 表示されます。ウィジェットには、タイトル テキスト、ヒントテキスト、複数行テキストを含めることができます。 ウィジェットは、テキスト値が変更されたときにアクションをトリガーできます。
  • グリッド - 複数列 アイテムのコレクションを表すレイアウト。アイテムは、 画像、タイトル、サブタイトル、枠線などのさまざまなカスタマイズ オプション 切り抜きスタイルを設定します
カード アクション ウィジェット ユーザー操作ウィジェット

DecoratedText 個のチェックボックス

DecoratedText を定義して、 ボタンやバイナリの切り替えではなく、チェックボックスが接続されたウィジェット スイッチ。スイッチと同様に、チェックボックスの値は アクション イベント オブジェクト Action に渡される値 この DecoratedText に添付されています によって setOnClickAction(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/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 分間隔で区切られた時間のリストを利用できます。 選択します。特定の時刻を入力することもできます。モバイル デバイスの場合、 時刻選択ツールが開き、組み込みのモバイル「時計」が表示されます。時間選択ツールを使用します。

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

グリッド

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

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

グリッド ウィジェットの例

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 タグのみを含めます。

サポートされているタグとその目的は次のとおりです。 table:

形式 レンダリングされた結果
太字 "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. インチ これが 1 行目です。
これは新しい行です。