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 do 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ó pode 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 complemento da mesma maneira que as caixas de diálogo personalizadas do Apps Script. O procedimento geralmente 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 que a caixa de diálogo seja aberta, chame HtmlService.createHtmlOutputFromFile(filename) para criar um objeto HtmlOutput que represente a caixa de diálogo. Como alternativa, se você estiver usando HTML com modelo, chame HtmlService.createTemplateFromFile(filename) para gerar um modelo e, em seguida, HtmlTemplate.evaluate() para convertê-lo em um objeto HtmlOutput.
  3. Chame Ui.showModalDialog(htmlOutput, dialogTitle) para mostrar a caixa de diálogo usando 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 gerenciador associadas. Para mais detalhes, consulte Comunicação do cliente para o servidor.

Caixas de diálogo de abertura de arquivos

As caixas de diálogo de abertura de arquivo são caixas de diálogo predefinidas que permitem que os usuários selecionem arquivos no Google Drive. É possível adicionar uma caixa de diálogo de abertura de arquivo ao seu complemento sem precisar projetá-la, mas isso exige mais configuração. Você também precisa ter 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 arquivo.

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 interagendo 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 barra lateral. Ao definir a barra lateral, consulte as diretrizes de estilo do complemento do editor.

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

  3. Chame Ui.showSidebar(htmlOutput) para mostrar a barra lateral usando 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 gerenciador associadas. Para mais detalhes, consulte Comunicação do cliente para o servidor.