Como criar cards interativos

A maioria dos complementos, além da apresentação de dados, exige que o usuário insira informações imprecisas ou inadequadas. 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 que seu complemento 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 implementação do comportamento necessário em um callback função. Consulte os detalhes em ações complementares.

Na maioria dos casos, você pode 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 retorno de chamada que deve ser executada, juntamente com quaisquer parâmetros obrigatórios.
2. Vincule o widget ao Action chamando o método função do gerenciador de widgets.
3. Implementar a função de callback para aplicar o comportamento necessário.

Exemplo

O exemplo a seguir define um botão que exibe uma notificação do usuário depois de clicar nele. O clique aciona a função de callback notifyUser(). por um argumento que especifica o texto da notificação. Como retornar um ActionResponse 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 do seu modelo.

• Usar o widget setOpenLink() quando você tem um URL e quer abri-lo em uma guia. Isso evita a necessidade de definir Objeto Action e callback função. Se você precisar criar o URL primeiro ou fazer qualquer outra antes de abrir o URL, defina um Action e usar setOnClickOpenLinkAction() como alternativa.

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

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

• Mantenha suas funções de callback simples. Para manter os complementos responsivos, o O serviço de cartão limita as funções de callback a no máximo 30 segundos de no ambiente de execução. Se a execução demorar mais do que isso, a interface do complemento poderá não atualiza a exibição do cartão corretamente em resposta ao Action

• Se o status dos dados em um back-end de terceiros for alterado como resultado da ação interação com a interface do complemento, é recomendável que o conjunto de complementos um "estado alterado" bit a true para que qualquer cache existente do lado do cliente seja limpos. Consulte a ActionResponseBuilder.setStateChanged() a descrição do método para mais detalhes.