微件

微件是一个简单的界面元素,提供以下一项或多项:

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

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

使用 Google Workspace 插件设计套件

为了节省插件的设计时间,设计人员可以使用 Figma 上提供的 Google Workspace 插件界面设计套件。您可以创建 Figma 帐号,也可以向组织管理员申请许可。

浏览组件并使用内置模板来创建和直观呈现微件。

获取设计套件

微件类型

插件微件通常分为三组:结构微件、信息微件和用户互动微件。

结构微件

结构微件可为 AI 中使用的其他微件提供容器和组织方式。

结构微件

  • 按钮集 - 一个或多个文本或图片按钮的集合,按水平行分组。
  • 卡片 - 包含一个或多个卡片部分的单个上下文卡片。您可以通过配置卡片导航来定义用户如何在卡片之间移动。
  • 卡片标题 - 给定卡片的标题。卡片标题可以有标题、字幕和图片。如果插件使用卡片操作通用操作,它们会在卡片标头中显示。
  • 卡片部分 - 一组卡片微件,通过水平规则与其他卡片部分进行划分,并视需要包含一个部分标题。每张卡片都必须至少有一个卡片部分。您不能向卡片部分添加卡片或卡片标题。

除了以下基本结构微件之外,在 Google Workspace 插件中,您还可以使用卡片服务创建与当前卡片重叠的结构:固定页脚提示卡

现在,您可以在卡片底部添加固定的一行按钮。此行不会随着卡片内容的剩余部分移动或滚动。以下代码片段显示了如何定义固定页脚示例并将其添加到卡片中:

var fixedFooter = CardService.newFixedFooter()
    .setPrimaryButton(
        CardService.newTextButton()
            .setText("help")
            .setOpenLink(CardService.newOpenLink()
                .setUrl("https://www.google.com")))
    .setSecondaryButton(
        CardService.newTextButton()
            .setText("submit")
            .setOnClickAction(
                CardService.newAction()
                    .setFunctionName(
                        "submitCallback")));

var card = CardService.newCardBuilder()
    // (...)
    .setFixedFooter(fixedFooter)
    .build();
      

 

修复了页脚微件示例

提示卡

提示卡示例

当用户操作(例如打开 Gmail 邮件)触发新的上下文内容时,您可以立即显示新的上下文内容(默认行为),也可以在边栏底部显示提示卡通知。如果用户在上下文触发器处于活动状态时点击“返回” 以返回到您的首页,系统就会显示一张提示卡,以帮助用户再次找到上下文内容。

如需在有新的上下文内容时显示提示卡,请不要将新的上下文内容立即显示,而是将 .setDisplayStyle(CardService.DisplayStyle.PEEK) 添加到您的 CardBuilder 类中。提示卡仅在与您的上下文触发器一起返回时显示一个卡片对象;否则,返回的卡片会立即替换当前卡片。

如需自定义提示卡的标题,请在构建上下文卡片时添加带有标准 CardHeader 对象的 .setPeekCardHeader() 方法。默认情况下,Peek 卡标头仅包含插件的名称。

以下代码基于 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 - 一种文本内容字符串,可与其他元素(例如顶部和底部文本标签)以及图片或图标配对。DecoratedText 微件还可以包含 ButtonSwitch 微件。添加的开关可以是简单的切换开关或复选框。DecoratedText 微件的内容文本可以使用 HTML 格式;顶部和底部标签必须使用纯文本。
  • 文本段落 - 简单的文本段落,可以包含 HTML 格式的元素。




用户互动微件

卡片操作微件

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

用户互动微件

  • 卡片操作 - 插件标题栏菜单中的菜单项。标题栏菜单还可以包含定义为通用操作的项目,这些项目会显示在插件定义的每张卡片上。
  • 日期选择器 - 允许用户选择日期和/或时间的微件。如需了解详情,请参阅下文的日期和时间选择器
  • 图片按钮 - 使用图片而非文本的按钮。您可以使用多个预定义图标中的一个,也可以使用由其网址指示的公开托管图片。
  • 选择输入 - 表示选项集合的输入字段。选择输入微件显示为复选框、单选按钮或下拉选择框。
  • 开关 - 一个切换微件。您只能将开关与 DecoratedText 微件配合使用。默认情况下,这些屏幕显示为切换开关,但您可以使其显示为复选框
  • 文本按钮 - 带有文本标签的按钮。您可以为文本按钮指定背景颜色填充效果(默认为透明)。您还可以根据需要停用该按钮。
  • 文本输入 - 文本输入字段。微件可以包含标题文本、提示文本和多行文本。该微件可在文本值发生更改时触发操作。
  • 网格 - 多列布局,表示一系列项。您可以使用图片、标题、副标题以及一系列自定义选项(如边框和剪裁样式)表示内容。

DecoratedText 复选框

您可以定义一个带有复选框(而非按钮或二进制切换开关)的 DecoratedText 微件。与开关一样,复选框的值包含在操作事件对象中,该对象由 setOnClickAction(action) 方法附加到此 DecoratedTextAction

以下代码片段显示了如何定义复选框 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 the 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 the 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 the date and time in EDT 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”且日期时间选择器微件中表示用户选择的日期时间的格式并记录该字符串:

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

 

下表显示了桌面设备和移动设备上的选择器选择界面的示例。选择此选项后,日期选择器会打开一个基于月的日历界面,以便用户快速选择新日期。

用户在桌面设备上选择时间选择器时,系统会打开一个下拉菜单,其中的时间列表以 30 分钟为增量供用户选择。用户也可以输入特定时间。在移动设备上,选择时间选择器会打开内置的移动“时钟”时间选择器。

桌面设备 移动平台
日期选择器选择示例 移动设备日期选择器示例
时间选择器选择示例 移动时间选择器选择示例

网格

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

您可以使用标识符(以参数的形式返回网格项)在网格中定义的操作。

var gridItem = CardService.newGridItem()
  .setIdentifier("item_001")
  .setTitle("A grid item")
  .setSubtitle("with a subtitle")
  .setImage(imageComponent);

var cropStyle = CardService.newImageCropStyle()
  .setImageCropType(CardService.ImageCropType.SQUARE);

var borderStyle = CardService.newBorderStyle()
  .setType(CardService.BorderType.STROKE)
  .setCornerRadius(8)
  .setStrokeColor("#00FF00FF");

var imageComponent = CardService.newImageComponent()
  .setImageUrl("https://cataas.com/cat?0.001")
  .setCropStyle(cropStyle)
  .setBorderStyle(borderStyle);

var grid = CardService.newGrid()
  .setTitle("My first grid")
  .addItem(gridItem)
  .setNumColumns(2)
  .setOnClickAction(CardService.newAction()
    .setFunctionName("handleGridItemClick"));
      

 

“网格”微件示例

文本格式

某些基于文本的微件可以支持简单的文本 HTML 格式。设置这些微件的文本内容时,只需添加相应的 HTML 标记即可。支持以下格式:

格式 示例 渲染结果
粗体 <b>test</b> test
斜体 <i>test</i> test
下划线 <u>test</u> test
删除线 <s>test</s> test
字体颜色 <font color="#ea9999">test</font> test
超链接 <a href="http://www.google.com">google</a> Google
时间 <time>2020-02-16 15:00</time> 2020 年 2 月 16 日 15:00
换行符 test <br> test 测试
测试