Como criar cards interativos

A maioria dos complementos, além de apresentar dados, exige que o usuário insira informações. Ao criar um complemento baseado em cards, é possível usar widgets interativos, como botões, itens de menu da barra de ferramentas ou caixas de seleção, para solicitar ao usuário dados necessários para o complemento ou fornecer outros controles de interação.

Como adicionar ações aos widgets

Na maioria das vezes, você torna os widgets interativos vinculando-os a ações específicas e implementando o comportamento necessário em uma função de callback. Consulte ações complementares para saber mais.

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, especifique a função de callback que será executada, junto com os parâmetros necessários.
2. Vincule o widget ao Action chamando a função de gerenciador de widgets apropriada.
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 o 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))
        .build();      // Don't forget to build the response!
  }

Criar interações eficazes

Ao projetar cards interativos, tenha em mente o seguinte:

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

• Use a função de gerenciador de widgets 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 realizar outras etapas antes de abrir o URL, defina um Action e use setOnClickOpenLinkAction().

• Ao usar as funções setOpenLink() ou setOnClickOpenLinkAction() do gerenciador de widgets, é necessário fornecer um objeto OpenLink para definir qual URL abrir. Você também pode usar esse objeto para especificar o comportamento de abertura e fechamento usando os tipos enumerados OpenAs e OnClose.

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

• Mantenha as funções de callback simples. Para manter a capacidade de resposta dos complementos, o serviço de cartão limita as funções de callback a um máximo de 30 segundos de tempo de execução. Se a execução demorar mais que isso, a interface do complemento pode não atualizar a exibição do cartão corretamente em resposta ao Action .

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