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

Na maioria dos complementos do Editor, as janelas de caixa de diálogo e os painéis da barra lateral são as principais interfaces do usuário dos complementos. 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 ele pode exibir apenas uma por vez.

Quando quiser impedir que o usuário interaja com o editor até que ele faça alguma 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 modais. Enquanto estão abertas, o usuário não pode interagir com 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 JavaScript do lado do cliente da caixa de diálogo. Ao definir a caixa de diálogo, consulte as Diretrizes de estilo dos 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 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 exibir 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 gerenciador associadas. Para mais detalhes, consulte Comunicação cliente para servidor.

Caixas de diálogo abertas no arquivo

As caixas de diálogo abertas são caixas de diálogo pré-criadas que permitem que os usuários selecionem arquivos no Google Drive. Você pode adicionar uma caixa de diálogo aberta ao arquivo ao complemento sem precisar projetá-la, 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 arquivos abertos.

As barras laterais são painéis que aparecem à direita da interface do editor e são o tipo mais comum de interface de complementos. 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. Elas 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 JavaScript do cliente da barra lateral. Ao definir a barra lateral, consulte as Diretrizes de estilo dos complementos 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 represente a barra lateral. Como alternativa, 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.

Elas 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 cliente para servidor.