微件是一种提供以下一项或多项内容的界面元素：
- 其他微件的结构，例如卡片和版块。
- 向用户提供的信息，例如文字和图片，或
- 操作的选项，例如按钮、文本输入字段或复选框。
添加到卡片部分的微件集可定义 插件界面。微件 在网页和移动设备上具有相同的外观和功能。通过 参考文档 介绍了几种构建微件集的方法。
微件类型
插件 widget 通常分为三类 组：结构性微件、 信息微件和用户互动微件
结构微件
结构 widget 可以为其他 widget 提供容器和组织方式 基本功能
- 按钮集 - A 一个或多个文本或图片按钮的集合，这些按钮会组合到一个 水平行。
- 卡片 - 单一上下文 包含一个或多个卡片部分的卡片。您可以定义用户的迁移方式 来配置卡片 卡片导航。
- 卡片标题 - 标头。卡片标题可以包含标题、字幕和 图片。卡片操作和 通用操作出现在 该 卡片标题。
- 卡片部分 - A 一组收集的小部件，将卡片与其他卡片部分 以及节标题（可选）。每张卡都必须 至少一个卡片部分。您无法向卡片添加卡片或卡片标题 部分。
除了这些基本的结构小部件之外， 可以使用的 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
类。只有在系统返回单个卡片对象时，才会显示提示卡片
内容相关触发器；否则，返回的卡片会立即替换掉
当前卡片。
如需自定义提示卡的标题，请添加 .setPeekCardHeader() 方法
标准的 CardHeader
对象。默认情况下，提示卡片标题
仅包含您的插件名称。
以下代码基于 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);
信息性微件
信息 widget 可向用户显示信息。
- 图片 - 图片 由您提供的托管且可公开访问的网址指明。
- DecoratedText - A 文本 可以与其他元素（如顶部和底部）配对的内容字符串 以及图片或图标DecoratedText 微件还可以 Button 或 切换微件。已添加的开关 可以是切换开关或复选框。内容文本 DecoratedText 微件可以使用 HTML 格式；顶部 和底部标签必须使用纯文本。
- 文本段落 - A 文本段落，包括 HTML 格式的元素。
用户互动微件
通过用户互动微件，该插件能够响应 用户。您可以通过操作响应来配置这些微件，以 显示不同的卡片, 打开网址, 显示通知, 撰写电子邮件草稿, 或运行其他 Apps 脚本函数。请参阅 制作互动式卡片指南 。
- 卡片操作 - 菜单 放到了插件标题栏菜单中。标题栏菜单 包含定义为通用操作的项， 显示在插件定义的每张卡片上
- 日期时间选择器 - widget 以便用户选择日期和/或时间请参阅 日期和时间选择器 。
- 图片按钮 - A 使用图片而非文字的按钮。您可以使用 预定义图标或由其网址指示的公开托管图片。
- 选择输入 - 表示一组选项的输入字段。“选择”输入微件 以复选框、单选按钮或下拉选择框的形式显示。
- 开关 - 切换开关 微件。开关只能与 DecoratedText 微件。默认情况下 这些按钮会以切换开关的形式显示，但您也可以将它们显示为 复选框。
- 文本按钮 - A 带有文本标签的按钮。您可以为文本指定背景颜色填充 按钮（默认为透明）。你还可以通过以下方式停用该按钮： 所需的资源。
- 文本输入 - 文本 输入字段。微件可以包含标题文本、提示文本和多行文本。 该 widget 可以在文本值发生更改时触发操作。
- 网格 - 多列 表示一组项的布局。您可以使用 图片、标题、副标题以及各种自定义选项（例如边框） 和剪裁样式
DecoratedText 个复选框
您可以定义一个 DecoratedText，
附加了复选框（而不是按钮或二进制切换开关）的 widget
。与开关一样，复选框的值也包含在
操作事件对象
传递给 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"));
以下是日期时间选择器 widget 处理程序函数的示例。这个 处理程序会设置并记录一个字符串，该字符串表示 ID 为“myDateTimePickerWidgetID”的日期时间选择器 widget 中的用户：
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);
}
}
下表显示了桌面设备和移动设备上的选择器选择界面示例 设备。选择此选项后，日期选择器会打开基于月份的日历界面 以便用户快速选择新日期。
用户在桌面设备上选择时间选择器后，系统会打开一个下拉菜单 以 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>." |
这是斜体。 |
| 下划线 | "This is <u>underline</u>." |
这是下划线。 |
| 删除线 | "This is <s>strikethrough</s>." |
这部分是 |
| 字体颜色 | "This is <font color=\"#FF0000\">red font</font>." |
这是红色字体。 |
| 超链接 | "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. 英寸 |
这是第一行。 另起一行。 |