Caixas de diálogo e barras laterais do complemento do editor

Para a maioria dos complementos do editor, as janelas de diálogo e os painéis da barra lateral são as principais interfaces de usuário do complemento. Ambos são totalmente personalizáveis usando HTML e CSS padrão, e você pode usar o modelo de comunicação cliente-servidor do Apps Script para executar funções do Apps Script quando o usuário interage com a barra lateral ou a caixa de diálogo. Seu complemento pode definir várias barras laterais e caixas de diálogo, mas só é possível mostrar uma de cada vez.

Quando você quiser impedir que o usuário interaja com o editor até que ele faça uma escolha na interface do complemento, use uma caixa de diálogo. Caso contrário, use uma barra lateral.

Caixas de diálogo

As caixas de diálogo são painéis de janela que se sobrepõem ao conteúdo principal do editor. As caixas de diálogo do Apps Script são modais. Enquanto elas estão abertas, o usuário não pode interagir com os outros elementos da interface do editor. É possível personalizar o conteúdo e o tamanho das caixas de diálogo.

Você cria caixas de diálogo de complementos da mesma forma que as caixas de diálogo personalizadas do Apps Script. O procedimento geral recomendado é o seguinte:

  1. Crie um arquivo de projeto de script que defina a estrutura HTML, o CSS e o comportamento do JavaScript do lado do cliente da caixa de diálogo. Ao definir a caixa de diálogo, consulte as diretrizes de estilo do complemento do editor.
  2. No código do lado do servidor em que você quer abrir a caixa de diálogo, chame HtmlService.createHtmlOutputFromFile(filename) para criar um objeto HtmlOutput que representa a caixa de diálogo. Se você estiver usando HTML com modelo, chame HtmlService.createTemplateFromFile(filename) para gerar um modelo e depois HtmlTemplate.evaluate() para convertê-lo em um objeto HtmlOutput.
  3. Chame Ui.showModalDialog(htmlOutput, dialogTitle) para mostrar a caixa de diálogo usando esse HtmlOutput.

As caixas de diálogo não suspendem o script do lado do servidor enquanto estão abertas. O JavaScript do lado do cliente pode fazer chamadas assíncronas para o lado do servidor usando google.script.run() e funções de manipulador associadas. Para mais detalhes, consulte Comunicação entre cliente e servidor.

Caixas de diálogo de abertura de arquivos

As caixas de diálogo de abertura de arquivos são pré-criadas e permitem que os usuários selecionem arquivos do Google Drive. É possível adicionar uma caixa de diálogo de abertura de arquivo ao complemento sem precisar criar um design, mas isso exige algumas configurações adicionais. Você também precisa de acesso ao projeto do Cloud Platform do complemento para ativar a API Google Picker.

Para mais detalhes, consulte Caixas de diálogo de abertura de arquivos.

As barras laterais são painéis que aparecem à direita da interface do editor e são o tipo mais comum de interface de complemento. Ao contrário das caixas de diálogo, você pode continuar interagindo com os outros elementos da interface do editor enquanto uma barra lateral está aberta. As barras laterais têm uma largura fixa, mas você pode personalizar o conteúdo delas.

Você cria barras laterais de complementos da mesma forma que as barras laterais personalizadas do Apps Script. O procedimento geral recomendado é o seguinte:

  1. Crie um arquivo de projeto de script que defina a estrutura HTML, o CSS e o comportamento do JavaScript do lado do cliente da sua barra lateral. Ao definir a barra lateral, consulte as diretrizes de estilo do complemento do editor.

  2. No código do lado do servidor, onde você quer que a barra lateral seja aberta, chame HtmlService.createHtmlOutputFromFile(filename) para criar um objeto HtmlOutput que representa a barra lateral. Se você estiver usando HTML com modelo, chame HtmlService.createTemplateFromFile(filename) para gerar um modelo e depois HtmlTemplate.evaluate() para convertê-lo em um objeto HtmlOutput.

  3. Chame Ui.showSidebar(htmlOutput) para mostrar a barra lateral usando esse HtmlOutput.

As barras laterais não suspendem o script do lado do servidor enquanto estão abertas. O JavaScript do lado do cliente pode fazer chamadas assíncronas para o lado do servidor usando google.script.run() e funções de manipulador associadas. Para mais detalhes, consulte Comunicação entre cliente e servidor.