Como criar cards interativos

A maioria dos complementos, além da apresentação de dados, exige que o usuário insira informações. Ao criar um complemento baseado em cartão, você pode usar widgets interativos, como botões, itens de menu da barra de ferramentas ou caixas de seleção, para solicitar ao usuário dados de que o complemento precisa ou fornecer outros controles de interação.

Como adicionar ações a widgets

Na maioria dos casos, os widgets são interativos porque são vinculados a ações específicas e a implementação do comportamento necessário em uma função de callback. Veja mais detalhes em Ações do complemento.

Na maioria dos casos, é possível seguir este procedimento geral para configurar um widget para realizar uma ação específica quando selecionado ou atualizado:

1. Crie um objeto Action, especificando a função de callback que será executada, com todos os parâmetros obrigatórios.
2. Vincule o widget ao Action chamando a função de gerenciador de widget adequada.
3. Implemente a função de callback para ativar o comportamento necessário.

Exemplo

O exemplo a seguir define um botão que mostra uma notificação do usuário após um clique. O clique aciona a função de callback notifyUser() com um argumento que especifica o texto da notificação. O retorno de um ActionResponse criado resulta em uma notificação exibida.

  /**
   * 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)
            .setType(CardService.NotificationType.INFO))
        .build();      // Don't forget to build the response!
  }

Crie interações eficazes

Ao criar cards interativos, lembre-se do seguinte:

• Os widgets interativos geralmente precisam de pelo menos um método de gerenciador para definir o comportamento.

• Use a função de gerenciador de widget setOpenLink() quando tiver um URL e quiser abri-lo em uma guia. Isso evita a necessidade de definir um objeto Action e uma função de callback. Se você precisar criar o URL primeiro ou seguir outras etapas antes de abrir o URL, defina um Action e use setOnClickOpenLinkAction().

• Ao usar as funções de gerenciador de widgets setOpenLink() ou setOnClickOpenLinkAction(), você precisa fornecer um objeto OpenLink para definir qual URL será aberto. Também é possível usar esse objeto para especificar o comportamento de abertura e fechamento usando as enumerações OpenAs e OnClose.

• É possível que mais de um widget use o mesmo objeto Action. No entanto, você precisa definir objetos Action diferentes se quiser fornecer parâmetros diferentes à função de callback.

• Simplifique as funções de callback. Para manter os complementos responsivos, o serviço de cartões limita as funções de callback a um máximo de 30 segundos do tempo de execução. Se a execução levar mais tempo, a IU do complemento pode não atualizar a exibição do cartão corretamente em resposta à Action.

• Se um status de dados em um back-end de terceiros mudar como resultado de uma interação do usuário com a IU do complemento, é recomendável que o complemento defina um bit de "estado alterado" como true para que todo o cache do lado do cliente seja apagado. Consulte a descrição do método ActionResponseBuilder.setStateChanged() para mais detalhes.