Caixas de diálogo e barras laterais para o complemento Editor

Para a maioria dos complementos do Editor, as janelas da caixa 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 é possível usar o modelo de comunicação entre cliente e 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 o complemento pode exibir apenas um de cada vez.

Quando você quiser impedir que o usuário interaja com o editor até que 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 do editor principal. As caixas de diálogo do Apps Script são modal. Enquanto estiverem 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 complementares 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 da caixa de diálogo, o CSS e o comportamento do JavaScript no lado do cliente. Ao definir a caixa de diálogo, consulte as Diretrizes de estilos de complementos 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 a represente. Como alternativa, se você estiver usando HTML modelo, vai poder chamar HtmlService.createTemplateFromFile(filename) para gerar um modelo e, em seguida, HtmlTemplate.evaluate() para os converter em um objeto HtmlOutput.
  3. Chame Ui.showModalDialog(htmlOutput, dialogTitle) para exibir 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 servidor usando google.script.run() e funções de gerenciador associadas. Para mais detalhes, consulte Comunicação entre clientes.

Caixas de diálogo de abertura de arquivo

As caixas de diálogo de abertura de arquivos são pré-criadas e permitem que os usuários selecionem arquivos do Google Drive. Você pode adicionar uma caixa de diálogo de abertura de arquivos ao seu complemento sem precisar desenvolvê-lo, mas é necessária uma configuração adicional. Você também precisa de acesso ao projeto do Cloud Platform do complemento para ativar a API Google Picker.

Veja mais detalhes em Caixas de diálogo para abrir 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, é possível continuar a interagir com os outros elementos da interface do editor enquanto uma barra lateral está aberta. As barras laterais têm largura fixa, mas você pode personalizar o conteúdo delas.

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

  1. Crie um arquivo de projeto de script que defina a estrutura HTML da barra lateral, o CSS e o comportamento do JavaScript do lado do cliente. 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 abrir a barra lateral, chame HtmlService.createHtmlOutputFromFile(filename) para criar um objeto HtmlOutput que representa a barra lateral. Como alternativa, se você estiver usando HTML modelo, vai poder chamar HtmlService.createTemplateFromFile(filename) para gerar um modelo e, em seguida, HtmlTemplate.evaluate() para os converter em um objeto HtmlOutput.

  3. Chame Ui.showSidebar(htmlOutput) para exibir 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 servidor usando google.script.run() e funções de gerenciador associadas. Para mais detalhes, consulte Comunicação entre clientes.