widget

微件是一种提供以下一项或多项内容的界面元素：

• 其他微件的结构，例如卡片和版块。
• 向用户提供的信息，例如文字和图片，或
• 操作的选项，例如按钮、文本输入字段或复选框。

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

微件类型

插件 widget 通常分为三类 组：结构性微件、 信息微件和用户互动微件

结构微件

结构 widget 可以为其他 widget 提供容器和组织方式 基本功能

• 按钮集 - A 一个或多个文本或图片按钮的集合，这些按钮会组合到一个 水平行。
• 卡片 - 单一上下文 包含一个或多个卡片部分的卡片。您可以定义用户的迁移方式 来配置卡片 卡片导航。
• 卡片标题 - 标头。卡片标题可以包含标题、字幕和 图片。卡片操作和 通用操作出现在 卡片标题。
• 卡片部分 - A 一组收集的小部件，将卡片与其他卡片部分 以及节标题（可选）。每张卡都必须 至少一个卡片部分。您无法向卡片添加卡片或卡片标题 部分。

警告 ：向其中一个容器添加 widget 时， 添加该 widget 的副本。如果您在添加微件后对其进行了更改， 更改不会反映在界面中。因此，请始终确保 在添加之前，该微件如果您需要在此时间段 如果要添加，您必须重新构建整个卡片部分或卡片。请参阅 构造卡 了解详情。

除了这些基本的结构小部件之外， 可以使用的 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>."	时间格式如下：2023-02-16 15:00。
换行符	"This is the first line. <br> This is a new line. 英寸	这是第一行。 另起一行。