Esta página foi traduzida pela API Cloud Translation.

Guia de estilo da interface para complementos do Editor

Os complementos do editor criam interfaces do usuário (menus, barras laterais e caixas de diálogo) usando o serviço de HTML do Apps Script. Como as interfaces são desenvolvidas em HTML e CSS, elas são altamente personalizáveis. No entanto, ao criar a interface do complemento, você precisa projetá-la para oferecer uma ótima experiência ao usuário.

Os melhores complementos estendem cada editor naturalmente usando controles e comportamentos conhecidos. Ao criar um novo complemento:

Use o pacote CSS de complementos nas páginas de serviço HTML.
Em caso de dúvida sobre o design, encontre uma caixa de diálogo ou barra lateral semelhante no editor e copie o estilo dela ou consulte um Guia de início rápido do complemento.
Siga este guia de estilo para criar uma experiência perfeita.

Texto

Nome do complemento

É necessário definir o nome do complemento ao publicá-lo. O nome aparece em vários lugares, como na loja de complementos e nos menus.

Use letras maiúsculas no título.
Evite usar pontuação, especialmente parênteses, a menos que faça parte da sua marca.
Mantenha-o curto: 30 caracteres ou menos é o ideal. Nomes longos podem ser truncados automaticamente.
Não inclua o nome do produto do Google para o complemento (ou use a palavra "Google").
Não inclua informações de versão.
Verifique se o nome publicado do complemento é o mesmo do nome do arquivo do projeto de script. O nome do projeto aparece na caixa de diálogo de autorização.

O que não fazer	O que fazer

Estilo de escrita

Você não precisa escrever muito. A maioria das ações precisa ser clara por meio de iconografia, layout e rótulos curtos. Se você achar que uma parte do seu complemento precisa de uma explicação mais extensa do que os rótulos curtos podem oferecer, é recomendável criar uma página da Web separada que descreva o complemento e criar um link para ele.

Ao escrever texto da interface:

Use letras maiúsculas e minúsculas (especialmente para botões, rótulos e itens de menu).
Prefira textos curtos e simples, sem jargões ou acrônimos.

O que não fazer	O que fazer

Dica pós-instalação

A dica pós-instalação aparece logo depois que alguém instala o complemento e também é exibida na Ajuda. Você tem algumas frases para ajudar os usuários a começar rapidamente.

Comece com uma palavra de ação.
Descreva a primeira etapa para usar o complemento.
Se você tiver uma interface principal, como uma barra lateral, explique como abri-la.
Não promova seu complemento aqui, porque ele já está instalado.

O que não fazer	O que fazer

Itens do menu

Ao contrário dos projetos comuns do Apps Script, os complementos não aparecem no editor de script ou no gerenciador de script. Os usuários não podem executar scripts de complemento diretamente. Em vez disso, cada complemento recebe um lugar no menu de complementos. O menu (e possivelmente uma caixa de diálogo ou barra lateral) permite que os usuários interajam com o complemento.

O menu é uma parte importante da forma como os usuários controlam seu complemento. Por isso, projete a estrutura e a redação com cuidado.
Evite itens de menu que simplesmente repitam o nome do seu complemento. Em vez disso, comece com uma palavra de ação.
Se o item do menu principal iniciar um fluxo de trabalho e não houver um único verbo que descreva o que ele faz, chame-o de "Start". Esse padrão é usado no guia de início rápido do complemento do app Documentos.
A menos que seu menu tenha mais de seis itens, tente não usar submenus. Eles podem ser complicados e difíceis de selecionar.
Descreva a tarefa, não o componente da interface que o item de menu mostra.

O que não fazer	O que fazer

Mensagens de erro

Quando algo dá errado, é importante usar linguagem simples. Explique o problema do ponto de vista do usuário e sugira como corrigi-lo.

Não permita que o usuário veja as exceções geradas pelo código. Em vez disso, use instruções try...catch para interceptar exceções e mostrar uma mensagem de erro fácil de entender com texto inline estilizado na classe error do pacote CSS de complementos ou uma caixa de diálogo alert.
Antes de publicar, verifique se o complemento não registra informações de depuração no console do JavaScript. Use o registro do Stackdriver em vez disso.

O que não fazer	O que fazer

Conteúdo Help

O menu de cada complemento inclui uma caixa de diálogo de ajuda automática. Se você fornecer um URL de ajuda ao publicar, o botão "Saiba mais" vai direcionar para essa página. A menos que o complemento seja autoexplicativo, forneça uma página que explique como usá-lo.

Quando possível, mostre as instruções em uma lista com marcadores ou numerada. Mostre aos usuários o resultado final, com referências claras a elementos de interface nomeados.
As instruções precisam explicar claramente todos os requisitos, como configurar uma planilha de determinada maneira.
Você também pode vincular o conteúdo de ajuda à sua interface principal do usuário. Se o complemento criar um documento novo, você também poderá mostrar instruções no corpo do documento.

Interfaces do usuário personalizadas

Alguns complementos simples do Editor podem ser controlados inteiramente pelo menu, mas a maioria mostra uma barra lateral ou caixa de diálogo com conteúdo personalizado.

As barras laterais são melhores para ferramentas persistentes que as pessoas provavelmente vão usar repetidamente ao se referir ao conteúdo do documento ou da planilha.
As caixas de diálogo são ideais para ferramentas de uso único, páginas de configurações e mensagens importantes.

Texto da interface

Em qualquer caixa de diálogo ou barra lateral, considere que as pessoas só leem o título e os rótulos dos botões. A pessoa ainda consegue entender o que a interface faz e fazer uma boa escolha?

Use um título e rótulos de botão independentes.
Evite blocos longos de texto descritivo.

Caixas de diálogo

As caixas de diálogo são ótimas para ferramentas que as pessoas usam uma vez e depois seguem em frente. Por exemplo, se o complemento permitir que as pessoas insiram um gráfico, você poderá mostrar uma caixa de diálogo com opções de o que inserir e fechar a caixa de diálogo quando o gráfico for inserido. As caixas de diálogo também são úteis para mostrar as configurações do complemento ou para comunicar uma mensagem importante.

Não abra uma caixa de diálogo (incluindo um alerta ou solicitação) de outra caixa de diálogo. Mostre apenas uma por vez.
Para o título da caixa de diálogo, use uma palavra ou frase curta, começando com a palavra mais importante.
Os rótulos dos botões precisam estar relacionados ao título da caixa de diálogo.
Prefira dois botões, geralmente uma ação principal e "Cancelar". Para casos especiais que exigem um terceiro botão, considere o canto inferior direito.
Coloque botões no canto inferior esquerdo da caixa de diálogo. O botão principal azul deve estar à esquerda, com os botões secundários cinza à direita.

O que não fazer	O que fazer

Barras laterais

As barras laterais permitem que as pessoas consultem o documento, a planilha, a apresentação ou o formulário enquanto fazem escolhas. Eles também permitem que as pessoas usem seu complemento repetidamente. Sempre que uma nova barra lateral é aberta, a anterior é fechada automaticamente. Elas são melhores para modos temporários que o usuário sai quando termina.

Os usuários podem ter outros complementos com as próprias barras laterais. Se dois complementos tentarem abrir as barras laterais simultaneamente, apenas um será mostrado.
Não mostrar uma barra lateral ou caixa de diálogo quando um documento for aberto pela primeira vez.
Somente complementos que operam em AuthMode.FULL podem abrir barras laterais ou caixas de diálogo. Você pode usar um item de menu para abrir uma barra lateral, já que isso solicita que o usuário forneça a autorização completa.

Controles

As interfaces de complementos excelentes deixam espaço para os controles respirarem. Margens e padding adequados são muito importantes, enquanto controles densos podem parecer esmagadores. Em caso de dúvida, use um layout do próprio editor. Por exemplo, analise as caixas de diálogo existentes nos Documentos Google, como Arquivo > Formatação da página, ao criar a sua.

A documentação do pacote CSS de complementos oferece exemplos de marcação para cada um dos tipos de controles abaixo.

Botões

Use botões para controlar as ações principais da interface do usuário em vez de links simples ou outros elementos.

Evite mostrar mais de um botão azul, vermelho ou verde por vez. Botões cinza podem aparecer repetidamente.
A maioria dos rótulos de botões precisa seguir as regras de maiúsculas e minúsculas e começar com um verbo. Os botões vermelhos, geralmente para criar ações, devem usar todas as letras maiúsculas.

O que não fazer	O que fazer

Caixas de seleção e botões de opção

Use caixas de seleção quando as pessoas puderem selecionar várias opções ou nenhuma. Use botões de opção (ou um menu de seleção) quando exatamente uma opção precisa ser selecionada.

Não mude o comportamento das caixas de seleção para imitar botões de opção.
Não faça nada imediatamente quando eles forem verificados. As pessoas cometem erros. Aguarde até que os usuários cliquem em um botão para confirmar as escolhas.

Menus de seleção

As opções são uma ótima maneira de oferecer uma lista curta de alternativas.

Ordene as opções em ordem alfabética ou por um esquema lógico que todos os usuários possam entender (como dias da semana, começando pelo domingo).
Se a lista ficar muito longa, use outro controle. Por exemplo, você pode mostrar uma lista rolável para dar mais espaço ao menu e facilitar a navegação.

Áreas de texto

Se as pessoas precisarem digitar mais do que algumas palavras, use uma área de texto.

Crie áreas de texto com pelo menos duas linhas de altura para que sejam mais fáceis de usar e não se pareçam com campos de texto.
Coloque os rótulos na parte de cima.

Campos de texto

Use campos de texto se as pessoas precisarem digitar apenas uma ou duas palavras.

A largura de um campo de texto precisa sugerir o que você espera que as pessoas digitem nele.
Evite usar texto de marcador de posição como rótulo, porque ele desaparece quando recebe o foco. O texto do marcador de posição é útil para dar exemplos ou detalhes extras.
Coloque os rótulos na parte de cima, mas sinta-se à vontade para posicionar campos de texto curtos lado a lado.

Branding

No complemento

Se você quiser incluir a marca, mantenha-a breve e leve. Isso ajuda as pessoas a se concentrarem na interface e faz com que o complemento pareça parte do editor.

Todos os aspectos do seu complemento precisam seguir as diretrizes de marca.
Não inclua a palavra "Google" nem use ícones de produtos do Google.
O texto não pode ter mais do que algumas palavras e precisa ter estilo na classe gray do pacote CSS de complementos.
Os gráficos precisam ter um plano de fundo branco e não podem ter mais de 200 x 60 pixels.
Para caixas de diálogo, a marca precisa estar no canto inferior direito.
Para barras laterais, a marca pode estar na parte de cima ou de baixo.

Na loja

Para publicar um complemento do Editor, você precisa de um número de recursos de imagem. Esses recursos são usados para criar a página "Detalhes do app" do complemento.

Todos os aspectos da página "Detalhes do app" precisam seguir as diretrizes de marca.
Para mais detalhes sobre as imagens que você precisa enviar, consulte as diretrizes de imagem.

Acessibilidade

Todos devem poder aproveitar seu complemento, seja para pessoas que enxergam cores diferentes, usam um leitor de tela ou têm outras necessidades. A acessibilidade é um tópico amplo que não pode ser totalmente abordado neste guia de estilo. Um recurso útil é o site Google Acessibilidade. Mas aqui estão algumas dicas para começar:

Verifique se você consegue navegar até todos os controles da interface com o teclado. Adicione tabindex=0 a controles personalizados (como aqueles feitos com <div>) para que as pessoas possam usar a guia. Considere se outras teclas também precisam de suporte, como setas para uma lista.
Algumas pessoas podem usar um leitor de tela com seu complemento. Portanto, as imagens precisam ter um atributo alt, e os controles personalizados precisam ter atributos ARIA para descrever o uso deles.
Não dependa apenas da cor para comunicar o estado. Use ícones e texto também.

Se você usa controles da Web padrão, como os descritos anteriormente neste guia, facilitar o acesso ao seu complemento é mais fácil.