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 pedir ao usuário os dados necessários para o complemento ou fornecer outros controles de interação.

Adicionar ações aos widgets

Na maioria dos casos, 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 de complementos para mais detalhes.

Na maioria dos casos, siga este procedimento geral para configurar um widget e realizar 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 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 ao usuário depois que ele é clicado. O clique aciona a função de callback notifyUser() com um argumento que especifica o texto da notificação. Retornar 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 eficientes

Ao criar cards interativos, tenha em mente o seguinte:

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

• Use a função de manipulador do widget setOpenLink() quando tiver um URL e quiser apenas 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() em vez disso.

• Ao usar as funções de manipulador de widget 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 enums 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.

• Simplifique as funções de callback. Para manter a capacidade de resposta dos complementos, o serviço de card 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, a interface do complemento poderá não atualizar a exibição de cards 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 "estado mudou" como true para que qualquer cache do lado do cliente seja limpo. Consulte a descrição do método ActionResponseBuilder.setStateChanged() para mais detalhes.