Guia de estilo da IU 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 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 fornecer uma ótima experiência do usuário.

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

Texto

Nome do complemento

É necessário definir o nome do complemento no momento da publicação. O nome aparece em muitos lugares, como na loja de complementos e nos menus.

  • Use letras maiúsculas apenas no título.
  • Evite pontuação, especialmente parênteses, a menos que faça parte da sua marca.
  • Escreva um texto curto. O ideal é usar 30 caracteres ou menos. Nomes longos podem ser truncados automaticamente.
  • Não inclua o nome do produto do Google a que o complemento se destina nem use a palavra "Google".
  • Não inclua as informações da versão.
  • Verifique se o nome publicado do complemento é igual ao nome do arquivo do projeto de script. O nome do projeto é exibido na caixa de diálogo de autorização.
O que não fazer O que fazer
Nomes de complementos ruins Bons complementos

Estilo de escrita

Você não precisa escrever muito. A maioria das ações precisa ficar clara com iconografia, layout e rótulos curtos. Se você perceber que uma parte do seu complemento precisa de explicações mais extensas do que rótulos curtos podem fornecer, uma prática recomendada é criar uma página da Web separada com a descrição e um link para ela.

Ao escrever o texto da IU:

  • Use letra maiúscula apenas na primeira palavra (especialmente para botões, rótulos e itens de menu).
  • Prefira textos curtos e simples, sem jargões ou siglas.
O que não fazer O que fazer

Dica pós-instalação

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

  • Comece com uma palavra de ação.
  • Descreva a primeira etapa para usar seu complemento.
  • Se você tiver uma IU principal, como uma barra lateral, explique como abri-la.
  • Não promova seu complemento aqui, ele já está instalado.
O que não fazer O que fazer
Dica ruim pós-instalação Boa dica pós-instalação

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

  • O menu é uma parte fundamental do controle dos usuários sobre seu complemento. Por isso, projete sua estrutura e texto com cuidado.
  • Evite itens de menu que simplesmente repitam o nome do 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 verbo único que descreve o que ele faz, chame-o de "Iniciar". Este padrão é usado no Guia de início rápido do complemento Documentos.
  • A menos que seu menu tenha mais de seis itens, tente não usar submenus. Eles podem ser minuciosos e difíceis de selecionar.
  • Descreva a tarefa, não o componente da IU que o item de menu exibe.
O que não fazer O que fazer
Rótulos de itens de menu incorretos Rótulos bons para itens de menu

Mensagens de erro

Quando algo dá errado, é importante usar uma 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 seu código. Em vez disso, use instruções try...catch para interceptar exceções e exiba uma mensagem de erro personalizada com texto inline estilizado na classe error do pacote CSS de complementos ou de uma caixa de diálogo alerta.
  • Antes de publicar, verifique se seu complemento não registra informações de depuração no Console JavaScript. Em vez disso, use o Stackdriver Logging.
O que não fazer O que fazer
Mensagem de erro inválida Mensagem de erro boa

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" será vinculado à página. A menos que seu complemento seja autoexplicativo, forneça uma página que explique como usá-lo.

  • Quando possível, mostre as instruções em uma lista numerada ou com marcadores. Guie os usuários até o resultado final, com referências claras a elementos de IU nomeados.
  • Certifique-se de que suas instruções expliquem claramente quaisquer requisitos, como configurar uma planilha de uma determinada maneira.
  • Você também pode criar links para seu conteúdo de ajuda na interface do usuário principal. Se o complemento criar um novo documento, você também poderá mostrar instruções no corpo do documento.

Interfaces do usuário personalizadas

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

  • As barras laterais são melhores para ferramentas persistentes que as pessoas costumam usar repetidamente ao consultar o conteúdo do documento ou da planilha.
  • As caixas de diálogo são melhores 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, suponha que as pessoas leiam apenas o título e os rótulos do botão. Eles ainda conseguem descobrir o que sua interface faz e fazer uma boa escolha?

  • Use um título e rótulos de botão que sejam independentes.
  • Evite grandes blocos de texto descritivo.

Caixas de diálogo

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, exiba uma caixa de diálogo com opções do conteúdo a ser inserido e feche a caixa quando o gráfico for inserido. Elas também são úteis para mostrar as configurações do complemento ou comunicar uma mensagem importante.

  • Não abra uma caixa de diálogo (incluindo um alerta ou prompt) de outra caixa de diálogo. Exiba apenas uma de cada 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, use o canto inferior direito.
  • Coloque os botões no canto inferior esquerdo da caixa de diálogo. O botão principal azul precisa estar à esquerda, com os botões secundários cinza à direita.
O que não fazer O que fazer
Título da caixa de diálogo inválido Título da caixa de diálogo bom

As barras laterais permitem que as pessoas consultem o documento, planilha, apresentação ou 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 os modos temporários em que o usuário sai quando terminar.

  • Os usuários podem ter outros complementos com as próprias barras laterais. Se dois complementos tentarem abrir barras laterais simultaneamente, apenas um será mostrado.
  • Não mostrar uma barra lateral ou uma caixa de diálogo quando um documento for aberto pela primeira vez.
  • Somente os 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 dê autorização total.

Controles

Ótimas IUs de complementos deixam os controles um pouco livres. Margens e preenchimento adequados podem ajudar muito, enquanto controles densos podem parecer sobrecarregados. Se tiver dúvida, use um layout do próprio editor. Por exemplo, analise as caixas de diálogo nos Documentos Google, como Arquivo > Configuração da página, ao criar uma.

A documentação do pacote CSS de complementos (link em inglês) fornece exemplos de marcação para cada um dos tipos de controles abaixo.

Botões

Use botões para controlar as principais ações 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. Os botões cinza podem aparecer repetidamente.
  • A maioria dos rótulos de botão precisa estar com a primeira letra maiúscula e começar com um verbo. Os botões vermelhos, geralmente para criar ações, precisam usar 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 opção. Use botões de opção (ou um menu de seleção) quando exatamente uma opção precisar ser selecionada.

  • Não altere o comportamento das caixas de seleção para imitar os botões de opção.
  • Não faça nada imediatamente após serem marcadas. As pessoas cometem erros. Aguarde até que os usuários cliquem em um botão para confirmar as escolhas.

Selecionar menus

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

  • Classifique 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 no domingo).
  • Se a lista aumentar muito, 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.

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

Campos de texto

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

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

Branding

No seu complemento

Se quiser incluir uma marca, seja breve e leve. Isso ajuda as pessoas a se concentrarem na IU e faz com que o complemento pareça parte do editor.

  • Todos os aspectos do complemento precisam seguir as diretrizes da promoção 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 é estilizado na classe gray do pacote CSS de complementos.
  • As imagens precisam estar em um fundo branco e não podem ultrapassar 200 x 60 pixels.
  • Para caixas de diálogo, o branding deve estar no canto inferior direito.
  • Nas barras laterais, o branding pode estar na parte superior ou inferior.

Na loja

Para publicar um complemento de editor, você precisa de vários recursos de imagem. Esses recursos são usados para criar a página "Detalhes do app" do complemento.

Acessibilidade

Todo mundo pode aproveitar seu complemento, seja vendo cores de forma diferente, usando um leitor de tela ou tiver outras necessidades. Acessibilidade é um tema amplo que não pode ser totalmente abordado neste guia de estilo. Um recurso útil é o site do Google Acessibilidade. Mas aqui estão algumas dicas para começar:

  • Verifique se é possível navegar para todos os controles de IU com o teclado. Adicione tabindex=0 a controles personalizados (como aqueles criados com <div>) para que as pessoas possam usar a tecla Tab. Considere se outras chaves também precisam ser compatíveis, como setas para uma lista.
  • Algumas pessoas podem usar um leitor de tela com seu complemento. Assim, as imagens precisam ter um atributo alt e os controles personalizados precisam ter atributos ARIA para descrever o uso.
  • Não confie apenas na cor para comunicar o estado. Use também ícones e texto.

Se você usa controles da Web padrão, como os descritos anteriormente neste guia, facilita a acessibilidade do seu complemento.