ウィジェットは、次のうち 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 メッセージを開くなどのユーザー操作によって新しいコンテキスト コンテンツがトリガーされると、新しいコンテキスト コンテンツをすぐに表示するか(デフォルトの動作)、サイドバーの下部にピークカード通知を表示できます。コンテキスト トリガーがアクティブな状態でユーザーが [戻る] をクリックしてホームページに戻ると、ユーザーがコンテキスト コンテンツを再度見つけるために役立つピークカードが表示されます。
新しいコンテキスト コンテンツが利用可能になったときにピークカードを表示するには、新しいコンテキスト コンテンツをすぐに表示するのではなく、.setDisplayStyle(CardService.DisplayStyle.PEEK)
を CardBuilder
クラスに追加します。ピークカードは、コンテキスト トリガーで単一のカード オブジェクトが返される場合にのみ表示されます。それ以外の場合は、返されたカードがすぐに現在のカードを置き換えます。
ピークカードのヘッダーをカスタマイズするには、コンテキスト カードを作成する際に、標準の CardHeader
オブジェクトを指定して .setPeekCardHeader()
メソッドを追加します。デフォルトでは、ピークカードのヘッダーにはアドオンの名前のみが含まれます。
次のコードは、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);
情報ウィジェット
情報ウィジェットは、ユーザーに情報を提示します。
- 画像 - ホストされ、一般公開されている URL で指定された画像。
- DecoratedText - 上部や下部のテキストラベル、画像やアイコンなどの他の要素とペアにできるテキスト コンテンツ文字列。DecoratedText ウィジェットには、Button ウィジェットや Switch ウィジェットを含めることもできます。追加されたスイッチは、切り替えボタンまたはチェックボックスです。DecoratedText ウィジェットのコンテンツ テキストには HTML フォーマットを使用できます。上下のラベルには書式なしテキストを使用する必要があります。
- テキスト段落 - HTML 形式の要素を含めることができるテキスト段落。
ユーザー操作ウィジェット
ユーザー操作ウィジェットを使用すると、アドオンはユーザーが行った操作に応答できます。アクション レスポンスを使ってこれらのウィジェットを構成して、さまざまなカードの表示、URL を開く、通知の表示、メールの下書きの作成、他の Apps Script 関数の実行などを行うことができます。詳しくは、インタラクティブなカードの作成ガイドをご覧ください。
- カード アクション - アドオンのヘッダーバー メニューに配置されるメニュー項目。ヘッダーバー メニューには、アドオンで定義されるすべてのカードに表示されるユニバーサル アクションとして定義された項目を含めることもできます。
- 日時選択ツール - ユーザーが日付、時刻、またはその両方を選択できるウィジェット。詳しくは、以下の日付と時刻の選択ツールをご覧ください。
- 画像ボタン - テキストではなく画像を使用するボタン。事前定義された複数のアイコンのいずれか、または URL で示される一般公開されている画像を使用できます。
- Selection input - オプションのコレクションを表す入力フィールド。チェックボックス、ラジオボタン、プルダウンの選択ボックスとして表示される選択入力ウィジェット。
- スイッチ - 切り替えウィジェット。スイッチは 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>." |
これは斜体です。 |
Underline | "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 行目です。 これは新しい行です。 |