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, 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 os dados de que seu complemento precisa ou fornecer outros controles de interação.

Como adicionar ações a widgets

Na maioria das vezes, os widgets se tornam interativos, vinculando-os a ações específicas e implementando o comportamento necessário em uma função de callback. Consulte mais detalhes em Ações de complementos.

Na maioria dos casos, siga este procedimento geral para configurar um widget para executar uma ação específica quando selecionado ou atualizado:

1. Crie um objeto Action, especificando a função de callback que precisa ser executada, além de todos os parâmetros necessários.
2. Vincule o widget ao Action chamando a função do gerenciador de widgets apropriada.
3. Implemente a função de callback para gerar o comportamento necessário.

Exemplo

O exemplo a seguir define um botão que exibe uma notificação do usuário depois de ser clicado. O clique aciona a função de callback notifyUser() com um argumento que especifica o texto da notificação. O retorno de uma ActionResponse criada 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!
  }

Crie interações eficazes

Ao criar cards interativos, tenha em mente o seguinte:

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

• Use a função gerenciadora de widgets setOpenLink() quando tiver um URL e só 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 abri-lo, defina um Action e use setOnClickOpenLinkAction().

• Ao usar as funções do gerenciador de widgets setOpenLink() ou setOnClickOpenLinkAction(), é 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, será necessário definir objetos Action diferentes se você quiser fornecer parâmetros diferentes à função de callback.

• Mantenha suas funções de callback simples. Para manter os complementos responsivos, 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 do que isso, talvez a IU do complemento não atualize a exibição do card corretamente em resposta a 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 "estado alterado" como true para que qualquer cache do lado do cliente seja limpado. Consulte a descrição do método ActionResponseBuilder.setStateChanged() para mais detalhes.