widget

widget 是一种界面元素，可提供以下一项或多项功能：

其他 widget 的结构 ，例如卡片和部分，
向用户显示信息 ，例如文本和图片，或
操作功能 ，例如按钮、文本输入字段或复选框。

添加到卡片部分的 widget 集定义了附加功能的整体界面。微件在 Web 设备和移动设备上具有相同的外观和功能。参考文档介绍了构建 widget 集的几种方法。

附加功能 widget 通常分为三类：结构 widget、信息 widget 和用户互动 widget。

结构 widget

结构 widget 为界面中使用的其他 widget 提供容器和组织。

按钮集：一个或多个文本或图片按钮的集合，以水平行分组在一起。
卡片：包含一个或多个卡片部分的单个上下文卡片。通过配置卡片导航，定义用户如何在卡片之间移动。
卡片标题：给定卡片的标题。卡片标题可以包含标题、副标题和图片。卡片操作和通用操作如果使用，会显示在卡片标题中。
卡片部分：收集的一组 widget，通过水平规则与其他卡片部分分开，并且可以选择包含部分标题。每张卡片都必须至少包含一个卡片部分。您无法向卡片部分添加卡片或卡片标题。

显示结构化 widget 的卡片示例

向其中一个容器添加 widget 时，您会创建并添加该 widget 的副本。如果您在添加 widget 后对其进行更改，相应更改不会反映在界面中。请确保 widget 完整无误，然后再添加。如果您需要在添加 widget 后对其进行更改，请重建整个卡片部分或卡片。如需了解详情，请参阅构建卡片。

除了这些基本的结构微件之外，在 Google Workspace 附加功能中，您还可以使用 Card 服务创建与当前卡片重叠的结构： 固定页脚和预览卡片：

固定页脚

您可以向卡片底部添加一个固定的按钮行。此行不会随卡片内容的其余部分移动或滚动。

固定页脚 widget 示例

以下代码段展示了如何定义示例固定页脚并将其添加到卡片：

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

信息 widget 向用户显示信息。

图片：由托管且可公开访问的网址指示的图片。
DecoratedText：您可以与其他元素（例如顶部和底部标签，以及图片或图标）配对的文本内容字符串。DecoratedText widget 还可以包含 Button 或 Switch widget。添加的开关可以是切换开关或复选框。内容文本可以使用 HTML 格式；顶部和底部标签必须使用纯文本。
文本段落：A 文本段落，可以包含 HTML 格式的元素。

卡片中的信息类微件示例

用户互动 widget

用户互动 widget 允许附加功能响应用户操作。使用操作响应配置这些微件，以显示不同的卡片、打开网址、显示通知、撰写草稿电子邮件或运行其他 Apps 脚本函数。如需了解详情，请参阅构建互动卡片指南。

卡片操作：放置在附加功能标题栏菜单中的菜单项。标题栏菜单还可以包含定义为通用操作的项，这些项会显示在附加功能定义的每张卡片上。
**DateTime 选择器**：widget 允许用户选择日期、时间或两者。如需了解详情，请参阅日期和时间选择器。
图片按钮：使用图片而非文本的按钮。使用几个预定义图标之一或公开托管的图片。
**选择输入**：表示选项集合的输入字段。选择输入微件以复选框、单选按钮或下拉选择框的形式呈现。
Switch：与 DecoratedText widget 一起使用的切换 widget。默认情况下，这些 widget 显示为切换开关，但您可以将其显示为复选框。
文本按钮：带有文本标签的按钮。为文本按钮指定背景颜色填充（默认值为透明）。您还可以根据需要停用该按钮。
文本输入：文本输入字段。widget 可以包含标题文本、提示文本和多行文本。当文本值发生变化时，widget 可以触发操作。
网格：多列布局。使用图片、标题、副标题和自定义选项（例如边框和剪裁样式）表示项。

`DecoratedText` 复选框

您可以定义一个附加了复选框（而不是按钮或二进制切换开关）的 DecoratedText widget。与切换开关类似，复选框的值包含在传递给此 DecoratedText 的 Action 的操作事件对象中，该 Action 由 setOnClickAction 方法附加。

带装饰文本的复选框 widget 示例

以下代码段展示了如何定义要添加到卡片的复选框 DecoratedText widget：

var decoratedText = CardService.newDecoratedText()
    // (...)
    .setSwitch(CardService.newSwitch()
        .setFieldName('form_input_switch_key')
        .setValue('switch_is_on')
        .setControlType(
            CardService.SwitchControlType.CHECK_BOX));

日期和时间选择器

定义允许用户选择时间、日期或两者的 widget。使用 setOnChangeAction 分配 widget 处理函数，以便在选择器的值发生变化时执行。

自定义预览卡片示例

以下代码段展示了如何定义仅限日期的选择器、仅限时间的选择器以及日期和时间选择器以添加到卡片：

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 的日期和时间选择器 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 分钟为增量分隔的时间列表。用户还可以输入特定时间。在移动设备上，选择时间选择器会打开内置的移动“时钟”时间选择器。

桌面设备	移动设备

网格

使用网格 widget 以多列布局显示项。每个项都可以显示图片、标题和副标题。使用其他配置选项设置网格项中文字相对于图片的位置。

使用标识符配置网格项，该标识符作为参数返回给在网格上定义的操作。

显示联系信息的网格 widget 示例

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 bold.
斜体	`"This is <i>italics</i>."`	This is italics.
下划线	`"This is <u>underline</u>."`	This is underline.
删除线	`"This is <s>strikethrough</s>."`	This is ~~strikethrough~~.
字体颜色	`"This is <font color=\"#FF0000\">red font</font>."`	This is red font.
Hyperlink	`"This is a <a href=\"https://www.google.com\">hyperlink</a>."`	This is a hyperlink.
时间	`"This is a time format: <time>2023-02-16 15:00</time>."`	This is a time format: 2023-02-16 15:00.
换行符	`"This is the first line. <br> This is a new line.`"	This is the first line. This is a new line.