构建互动卡片

除了显示数据之外，大多数插件还需要用户输入信息。构建基于卡片的插件时，您可以使用交互式微件（例如按钮、工具栏菜单项或复选框）向用户索要插件所需的数据，或提供其他互动控件。

向微件添加操作

在大多数情况下，您可以通过将 widget 关联到特定的操作并在回调函数中实现所需的行为，使 widget 具有交互性。如需了解详情，请参阅插件操作。

在大多数情况下，您可以按照以下一般步骤配置 widget，以便在被选择或更新时执行特定操作：

  1. 创建一个 Action 对象，指定应执行的回调函数以及任何必需的参数。
  2. 通过调用适当的微件处理程序函数，将微件关联到 Action。
  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!
  }

设计有效的互动

设计交互式卡片时，请注意以下几点：

  • 交互式 widget 通常需要至少一个处理脚本方法来定义其行为。

  • 如果您有一个网址，只想在标签页中打开它，请使用 setOpenLink() widget 处理脚本函数。这样就无需定义 Action 对象和回调函数。如果您需要先构建网址，或者在打开网址之前执行任何其他额外步骤，请定义 Action 并改用 setOnClickOpenLinkAction()。

  • 使用 setOpenLink() 或 setOnClickOpenLinkAction() widget 处理程序函数时，您需要提供 OpenLink 对象来定义要打开的网址。您还可以使用此对象使用 OpenAs 和 OnClose 枚举指定打开和关闭行为。

  • 多个 widget 可以使用相同的 Action 对象。不过，如果您想为回调函数提供不同的参数，则需要定义不同的 Action 对象。

  • 回调函数应尽量简单。为了确保插件能够快速响应，卡片服务会将回调函数的执行时间限制为最多 30 秒。如果执行时间超过该时间，您的插件界面可能无法正确更新其卡片显示，以响应 Action。

  • 如果第三方后端的数据状态因用户与您的插件界面互动而发生变化，建议插件将“状态已更改”位设置为 true，以清除所有现有的客户端缓存。如需了解更多详情，请参阅 ActionResponseBuilder.setStateChanged() 方法说明。