此页面由 Cloud Translation API 翻译。

用户输入信息

本指南介绍了如何接收和阅读用户在卡片消息和对话框中输入的信息。用户可以输入 Chat 应用接收、读取和响应的数据。允许用户输入信息的微件包括：

TextInput，用于输入同样支持建议的自由格式文本。
SelectionInput：用于列表项和菜单，例如复选框、单选按钮和下拉菜单。
DateTimePicker，用于日期和时间条目。

使用卡片构建器设计和预览 Chat 应用的 JSON 卡片消息：

打开卡片制作工具

接收用户输入的数据可让 Chat 应用执行以下操作：

更新客户服务请求。
创建工作订单。
使用网络服务进行身份验证。

接收数据的运作方式

Chat 应用以对话框或卡片消息的形式向用户呈现信息。在此示例中，对话框会要求用户使用 TextInput 和 SelectionInput widget 输入联系人的相关信息：

包含各种不同 widget 的对话框。

完成后，Chat 应用会收到用户在对话框中输入的 JSON 格式数据和互动事件，其中：

EventType为CARD_CLICKED。
DialogEventType 为 SUBMIT_DIALOG（仅适用于对话框）。

如需获取与用户输入的内容相关的数据，请使用事件载荷中的 Event.common.formInputs 字段。formInputs 字段是一个映射，其中的键是分配给每个 widget 的字符串 ID，值表示每个 widget 的用户输入。不同的对象代表不同的输入数据类型。例如，Event.common.formInputs.stringInputs 表示字符串输入。

应用可以访问 event.common.formInputs.NAME.stringInputs.value[0] 处的第一个用户输入的值，其中 NAME 是 TextInput widget 的 name 字段。

如果您的 Chat 应用是使用 Apps 脚本构建的，请改用 event.common.formInputs.NAME[""].stringInputs.value[0]。

接收来自卡片的数据

当用户在卡片消息中输入数据时，您的 Chat 应用会收到 Chat 应用互动事件，例如以下示例：

JSON

{
  "type": enum (EventType),
  "eventTime": string,
  "threadKey": string,
  "message": {
    object (Message)
  },
  "user": {
    object (User)
  },
  "space": {
    object (Space)
  },
  "action": {
    object (FormAction)
  },
  "configCompleteRedirectUrl": string,
  "common": {

    // Represents user data entered in a card.
    "formInputs": {

      // Represents user data entered for a specific field in a card.
      "NAME": {

        // Represents string data entered in a card, like text input fields
        // and check boxes.
        "stringInputs": {

          // An array of strings entered by the user in a card.
          "value": [
            string
          ]
        }
      }
    },
    "parameters": {
      string: string,
      ...
    },
    "invokedFunction": string
  }
}

从对话框中接收数据

当用户在对话框中提交数据时，您的 Chat 应用会收到另一个 Chat 应用互动事件，例如以下示例：

JSON

{
  "type": enum (EventType),
  "eventTime": string,
  "threadKey": string,
  "message": {
    object (Message)
  },
  "user": {
    object (User)
  },
  "space": {
    object (Space)
  },
  "action": {
    object (FormAction)
  },
  "configCompleteRedirectUrl": string,

  // Indicates that this event is dialog-related.
  "isDialogEvent": true,

  // Indicates that a user clicked a button, and all data
  // they entered in the dialog is included in Event.common.formInputs.
  "dialogEventType": "SUBMIT_DIALOG",
  "common": {
    "userLocale": string,
    "hostApp": enum (HostApp),
    "platform": enum (Platform),
    "timeZone": {
      object (TimeZone)
    },

    // Represents user data entered in a dialog.
    "formInputs": {

      // Represents user data entered for a specific field in a dialog.
      "NAME": {

        // Represents string data entered in a dialog, like text input fields
        // and check boxes.
        "stringInputs": {

          // An array of strings entered by the user in a dialog.
          "value": [
            string
          ]
        }
      }
    },
    "parameters": {
      string: string,
      ...
    },
    "invokedFunction": string
  }
}

响应从卡片消息或对话框中收集的数据

从卡片消息或对话框接收数据后，Chat 应用会通过确认收到或返回错误来进行响应，这两项操作都是通过返回 ActionResponse 来完成的：

如需确认接收成功，请使用包含 "actionStatus": "OK" 的 ActionResponse 参数进行响应。
如需返回错误，请使用包含 "actionStatus": "ERROR MESSAGE" 的 ActionResponse 参数进行响应。

示例

以下示例检查是否存在 name 值。如果不存在，应用会返回错误。如果存在，应用会确认已收到表单数据并关闭对话框。

Node.js

/**
 * Checks for a form input error, the absence of
 * a "name" value, and returns an error if absent.
 * Otherwise, confirms successful receipt of a dialog.
 *
 * Confirms successful receipt of a dialog.
 *
 * @param {Object} event the event object from Chat API.
 *
 * @return {object} open a Dialog in Google Chat.
 */
function receiveDialog(event) {

  // Checks to make sure the user entered a name
  // in a dialog. If no name value detected, returns
  // an error message.
  if (event.common.formInputs.WIDGET_NAME.stringInputs.value[0] == "") {
    res.json({
      "actionResponse": {
        "type": "DIALOG",
        "dialogAction": {
          "actionStatus": "Don't forget to name your new contact!"
        }
      }
    });

  // Otherwise the app indicates that it received
  // form data from the dialog. Any value other than "OK"
  // gets returned as an error. "OK" is interpreted as
  // code 200, and the dialog closes.
  } else {
    res.json({
      "actionResponse": {
        "type": "DIALOG",
        "dialogAction": {
          "actionStatus": "OK"
        }
      }
    });
  }
}

Apps 脚本

此示例通过返回卡片 JSON 来发送卡片消息。您也可以使用 Apps 脚本卡片服务。

/**
 * Checks for a form input error, the absence of
 * a "name" value, and returns an error if absent.
 * Otherwise, confirms successful receipt of a dialog.
 *
 * Confirms successful receipt of a dialog.
 *
 * @param {Object} event the event object from Chat API.
 *
 * @return {object} open a Dialog in Google Chat.
 */
function receiveDialog(event) {

  // Checks to make sure the user entered a name
  // in a dialog. If no name value detected, returns
  // an error message.
  if (event.common.formInputs.WIDGET_NAME[""].stringInputs.value[0] == "") {
    return {
      "actionResponse": {
        "type": "DIALOG",
        "dialogAction": {
          "actionStatus": "Don't forget to name your new contact!"
        }
      }
    };

  // Otherwise the app indicates that it received
  // form data from the dialog. Any value other than "OK"
  // gets returned as an error. "OK" is interpreted as
  // code 200, and the dialog closes.
  } else {
    return {
      "actionResponse": {
        "type": "DIALOG",
        "dialogAction": {
          "actionStatus": "OK"
        }
      }
    };
  }
}

Python

def receive_dialog(event: Mapping[str, Any]) -> Mapping[str, Any]:
  """Checks for a form input error, the absence of a "name" value, and returns
     an error if absent. Otherwise, confirms successful receipt of a dialog.

  Args:
      event (Mapping[str, Any]): the event object from Chat API.

  Returns:
      Mapping[str, Any]: the response.
  """

  if common := event.get('common'):
    if form_inputs := common.get('formInputs'):
      if contact_name := form_inputs.get('WIDGET_NAME'):
        if string_inputs := contact_name.get('stringInputs'):
          if name := string_inputs.get('value')[0]:
            return {
              'actionResponse': {
                'type': 'DIALOG',
                'dialogAction': {
                  'actionStatus': 'OK'
                }
              }
            }
          else:
            return {
              'actionResponse': {
                'type': 'DIALOG',
                'dialogAction': {
                  'actionStatus': 'Don\'t forget to name your new contact!'
                }
              }
            }

问题排查

当 Google Chat 应用或卡片返回错误时，Chat 界面会显示“出了点问题”或“无法处理您的请求”的消息。有时，Chat 界面不会显示任何错误消息，但 Chat 应用或卡片会产生意外结果；例如，卡片消息可能不会显示。

虽然 Chat 界面中可能不会显示错误消息，但当为 Chat 应用启用错误日志记录功能时，您可以借助描述性错误消息和日志数据修正错误。如需查看、调试和修正错误方面的帮助，请参阅排查并修正 Google Chat 错误。