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

Como adicionar ações a 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 os detalhes em ações complementares.

Na maioria dos casos, você pode seguir este procedimento geral e 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 e todos os parâmetros necessá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 exibe uma notificação do usuário depois do clique. 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!
  }

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 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 seguir outras etapas antes de abrir o URL, defina um Action e use setOnClickOpenLinkAction().

• Ao usar as funções de gerenciador 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 tipos enumerados OpenAs e OnClose.

• É possível mais de um widget usar o mesmo objeto Action. No entanto, você precisa definir objetos Action diferentes se 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 interface do complemento não atualize a exibição do cartão corretamente em resposta ao Action .

• Se o status dos 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" como true para que o cache atual do lado do cliente seja limpado. Consulte a descrição do método ActionResponseBuilder.setStateChanged() para mais detalhes.