此页面由 Cloud Translation API 翻译。

Switch to English

微件

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

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

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

使用 Google Workspace 插件设计套件

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

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

获取设计套件

微件类型

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

结构微件

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

结构微件

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

除了这些基本的结构微件之外，在 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 插件快速入门，使用 Peek 卡片向用户通知新的上下文内容，并自定义 Peek 卡片的标头，以显示所选 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);

信息微件

信息微件会向用户显示信息，

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

用户互动微件

卡片操作微件

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

用户互动微件

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

DecoratedText 复选框

您可以定义一个带有复选框（而不是按钮或二进制切换开关）的 DecoratedText widget。与开关一样，复选框的值包含在操作事件对象中，而该对象被 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));

日期和时间选择器

您可以定义 widget 以允许用户选择时间和/或日期。您可以使用 setOnChangeAction() 来分配 widget 处理程序函数，以便在选择器的值发生更改时执行该函数。

以下代码片段展示了如何定义仅限日期的选择器、仅限时间的选择器和日期时间选择器，然后将这些选择器添加到卡片中：

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 为“myDatePickerWidgetID”的日期时间选择器 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/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 格式。设置这些 widget 的文本内容时，只需添加相应的 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`	测试测试