构建互动卡片

大多数插件除了可以显示数据以外,还必须 信息。构建基于卡片的插件时,您可以使用 交互式微件,例如按钮, 工具栏菜单项,或是用于要求用户提供插件的数据的复选框 或提供其他互动控件。

向微件添加操作

在大多数情况下,您需要将微件与 特定操作并在回调中实现所需行为 函数。如需了解详情,请参阅附加操作

在大多数情况下,您可以按照以下常规步骤配置微件, 在选中或更新后执行特定操作:

  1. 创建一个 Action 对象, 指定应执行的回调函数以及 必需参数。
  2. 通过调用适当的方法来将 widget 关联到 Actionwidget 处理程序函数
  3. 实现回调函数 以实施所需的行为。

示例

以下示例设置了用于显示用户通知的按钮 。点击会触发 notifyUser() 回调函数 ,并指定通知文本的参数。返回构建的 ActionResponse 会显示一条通知。

  /**
   * Build a simple card with a button that sends a notification.
   * @return {Card}
   */
  function buildSimpleCard() {
    var buttonAction = CardService.newAction()
        .setFunctionName('notifyUser')
        .setParameters({'notifyText': 'Button clicked!'});
    var button = CardService.newTextButton()
        .setText('Notify')
        .setOnClickAction(buttonAction);

    // ...continue creating widgets, then create a Card object
    // to add them to. Return the built Card object.
  }

  /**
   * Callback function for a button action. Constructs a
   * notification action response and returns it.
   * @param {Object} e the action event object
   * @return {ActionResponse}
   */
  function notifyUser(e) {
    var parameters = e.parameters;
    var notificationText = parameters['notifyText'];
    return CardService.newActionResponseBuilder()
        .setNotification(CardService.newNotification()
            .setText(notificationText))
        .build();      // Don't forget to build the response!
  }

设计有效的互动

设计互动式卡片时,请注意以下几点:

  • 交互式微件通常需要至少一个处理程序方法来定义 行为

  • 使用 setOpenLink() widget 处理程序函数。 这样就无需定义 Action 对象和回调 函数。如果您需要先构建网址,或者需要通过其他方式 先定义一个 Action 并使用 setOnClickOpenLinkAction()

  • 使用 setOpenLink() 时 或 setOnClickOpenLinkAction() 微件处理程序函数,则需要提供一个 OpenLink 对象来定义要打开的网址。您还可以使用此对象 使用 OpenAsOnClose 枚举。

  • 多个 widget 可以使用同一个 Action 对象。 不过,您需要定义不同的 Action 对象(如果需要) 以便为回调函数提供不同的参数。

  • 保持回调函数的简易性。为了让插件能够迅速响应, 卡片服务将回调函数限制为最多 30 秒 执行时间。如果执行时间超过该时间,您的插件界面 未正确更新其卡片显示 Action

  • 如果第三方后端上的数据状态会因为用户的影响而发生变化 与您的插件界面进行互动时,建议将插件集 “状态已更改”位更改为 true,以便任何现有的客户端缓存 已清除。请参阅 ActionResponseBuilder.setStateChanged() 方法说明。