Guía de estilo de la IU para complementos de editor

Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.

Los complementos de Editor compilan interfaces de usuario (menús, barras laterales y diálogos) mediante el servicio HTML de Apps Script. Debido a que las interfaces se desarrollan en HTML y CSS, son altamente personalizables. Sin embargo, cuando compiles tu interfaz de complemento, debes diseñarla para brindar una excelente experiencia del usuario.

Los mejores complementos extienden cada editor de forma natural mediante controles y comportamientos conocidos. Cuando compilas un nuevo complemento:

Texto

Nombre del complemento

Debes configurar el nombre de tu complemento cuando lo publiques. El nombre aparece en muchos lugares, como en la tienda de complementos y en menús.

  • Usa mayúsculas en todas las palabras principales.
  • Evite los signos de puntuación, especialmente los paréntesis, a menos que sean parte de su marca.
  • Sé breve: lo mejor es 30 caracteres o menos. Los nombres largos se pueden truncar de forma automática.
  • No incluyas el nombre del producto de Google para el que es el complemento (o usa la palabra Google).
  • Omitir la información de la versión
  • Asegúrate de que el nombre publicado del complemento sea el mismo que el nombre de archivo del proyecto de secuencia de comandos. El nombre del proyecto aparece en el diálogo de autorización.
Qué no hacer Sugerencias
Nombres de complementos incorrectos Bueno nombres de complementos

Estilo de escritura

No deberías tener que escribir mucho. La mayoría de las acciones deben ser claras a través de la iconografía, el diseño y las etiquetas cortas. Si descubres que una parte de tu complemento necesita una explicación más extensa de lo que pueden proporcionar las etiquetas cortas, te recomendamos que crees una página web aparte que describa tu complemento y el vínculo a él.

Cuando escribas texto de la IU, ten en cuenta lo siguiente:

  • Usa mayúscula inicial (especialmente para botones, etiquetas y elementos de menú).
  • Prefiera textos cortos y simples sin jerga ni acrónimos.
Qué no hacer Sugerencias

Sugerencia posterior a la instalación

La sugerencia posterior a la instalación aparecerá inmediatamente después de que alguien instale tu complemento y también aparecerá en la Ayuda. Tienes un par de oraciones para ayudar a los usuarios a comenzar rápidamente.

  • Comienza con una palabra de acción.
  • Describa el primer paso para usar su complemento.
  • Si tienes una IU principal, como una barra lateral, explica cómo abrirla.
  • No promociones tu complemento aquí, ya está instalado.
Qué no hacer Sugerencias
Sugerencia incorrecta posterior a la instalación Una buena sugerencia después de la instalación

A diferencia de los proyectos normales de Apps Script, los complementos no aparecen en el editor de secuencias de comandos ni en el administrador de secuencias de comandos; los usuarios no pueden ejecutar secuencias de comandos de complementos directamente. En cambio, cada complemento obtiene un espacio en el menú Complementos. El menú (y tal vez un diálogo o una barra lateral) permite a los usuarios interactuar con el complemento.

  • El menú es una parte clave de la forma en que los usuarios controlan tu complemento, por lo que debes diseñar su estructura y redacción cuidadosamente.
  • Evita los elementos del menú que simplemente repiten el nombre del complemento. En su lugar, comience con una palabra de acción.
  • Si tu elemento de menú principal inicia un flujo de trabajo y no hay un solo verbo que describa lo que hace, llámalo "Start". Este patrón se usa en la guía de inicio rápido del complemento de Documentos.
  • A menos que el menú tenga más de seis elementos, intenta no usar los submenús. Pueden ser complicados y difíciles de seleccionar.
  • Describe la tarea, no el componente de la IU que muestra el elemento de menú.
Qué no hacer Sugerencias
Etiquetas de elementos de menú incorrectas Etiquetas del elemento del menú adecuadas

Mensajes de error

Cuando algo sale mal, es importante usar un lenguaje simple. Explica el problema desde el punto de vista del usuario y sugiere cómo solucionarlo.

  • No permitas que el usuario vea ninguna excepción con el código. En su lugar, usa las declaraciones try...catch para interceptar excepciones y, luego, muestra un mensaje de error frito para el usuario con texto intercalado con estilo en la clase error del paquete de CSS de complementos o un diálogo de alerta.
  • Antes de publicar, verifica que tu complemento no registre información de depuración en la consola de JavaScript; en su lugar, usa el registro de Stackdriver.
Qué no hacer Sugerencias
Mensaje de error erróneo Buen mensaje de error

Contenido de ayuda

El menú de cada complemento incluye un diálogo de ayuda automático. Si proporcionas una URL de ayuda cuando la publicas, el botón "Más información" se vincula a esa página. A menos que tu complemento sea evidente, proporciona una página que explique cómo usarlo.

  • Cuando sea posible, muestra instrucciones en una lista numerada o con viñetas. Explica a los usuarios hasta el resultado final, con referencias claras a los elementos de la IU con nombre.
  • Asegúrate de que las instrucciones expliquen claramente cualquier requisito, como configurar una hoja de cálculo de una manera determinada.
  • No dudes en incluir vínculos a tu contenido de ayuda desde la interfaz de usuario principal. Si tu complemento crea un documento nuevo, también puedes mostrar instrucciones en el cuerpo del documento.

Interfaces de usuario personalizadas

Algunos complementos simples de editor se pueden controlar por completo desde el menú, pero la mayoría muestra una barra lateral o diálogo con contenido personalizado.

  • Las barras laterales son mejores para las herramientas persistentes que es probable que las personas usen de forma repetida mientras hacen referencia al contenido de su documento o hoja de cálculo.
  • Los diálogos son más adecuados para las herramientas de uso único, las páginas de configuración y los mensajes importantes.

Texto de la IU

En cualquier diálogo o barra lateral, supongamos que las personas solo leen las etiquetas de título y botón. ¿Aún puede descubrir lo que hace su interfaz y tomar una buena decisión?

  • Usa etiquetas de título y botón que sean independientes.
  • Evita los bloques largos de texto descriptivo.

Diálogos

Los diálogos son ideales para las herramientas que los usuarios usan una vez y, luego, continúan. Por ejemplo, si tu complemento permite que las personas inserten un gráfico, es posible que veas un diálogo con opciones de qué insertar y luego cerrarlo cuando lo insertes. Los diálogos también son útiles para mostrar la configuración de tu complemento o para comunicar un mensaje importante.

  • No abras un diálogo (que incluya una alerta o un mensaje) desde otro diálogo; solo muestra uno a la vez.
  • Para el título del diálogo, usa una palabra o frase corta que comience con la palabra más importante.
  • Las etiquetas de los botones deben estar relacionadas con el título del diálogo.
  • Se prefieren dos botones, que suelen ser una acción principal y "Cancelar". Para los casos especiales que requieren un tercer botón, considera la esquina inferior derecha.
  • Coloca los botones en la esquina inferior izquierda del cuadro de diálogo. El botón azul principal debe estar a la izquierda, con cualquier botón secundario gris a la derecha.
Qué no hacer Sugerencias
Título de diálogo incorrecto Título de diálogo correcto

Las barras laterales permiten que las personas consulten su documento, hoja de cálculo, presentación o formulario mientras toman decisiones. También permiten que las personas usen tu complemento varias veces. Cada vez que se abre una nueva barra lateral, cualquier barra lateral anterior se cierra automáticamente. Son mejores para los modos temporales que el usuario sale cuando termina.

  • Los usuarios pueden tener otros complementos con sus propias barras laterales. Si dos complementos intentan abrir barras laterales de forma simultánea, solo se muestra uno.
  • No mostrar una barra lateral o diálogo cuando se abre un documento por primera vez
  • Solo los complementos que operan en AuthMode.FULL pueden abrir barras laterales o diálogos. Puedes usar un elemento de menú para abrir una barra lateral, ya que esto le solicita al usuario proporcionar autorización total.

Controles

Las IU de complementos geniales dejan sus controles en la respiración. Los márgenes y el padding adecuados son muy importantes, mientras que los controles densos pueden parecer abrumadores. Si tienes dudas, usa un diseño del editor. Por ejemplo, revisa los diálogos existentes en Documentos de Google, como Archivo > Configuración de la página, cuando crees el tuyo.

La documentación del paquete de CSS de complementos proporciona lenguaje de marcado de muestra para cada uno de los tipos de controles que aparecen a continuación.

Botones

Usa los botones para controlar las acciones principales de tu interfaz de usuario en lugar de vínculos sin formato u otros elementos.

  • Evita mostrar más de un botón azul, rojo o verde a la vez. Los botones grises pueden aparecer varias veces.
  • La mayoría de las etiquetas de botones deben estar en mayúscula inicial y comenzar con un verbo. Los botones rojos, en general para crear acciones, deben usar mayúsculas.
Qué no hacer Sugerencias

Casillas de verificación y botones de selección

Utilice casillas de verificación cuando las personas puedan seleccionar varias opciones o ninguna. Usa botones de selección (o un menú de selección) cuando se deba seleccionar solo una opción.

  • No cambies el comportamiento de las casillas de verificación para imitar botones de selección.
  • No hagas nada de inmediato después de revisarlas. Las personas cometen errores. Espera hasta que tus usuarios hagan clic en un botón para confirmar sus elecciones.

Seleccionar menús

Las selecciones son una excelente manera de ofrecer una lista breve de alternativas.

  • Ordena las opciones alfabéticamente o según un esquema lógico que todos los usuarios puedan comprender (como días de la semana, a partir del domingo).
  • Si la lista crece demasiado, considere usar un control diferente. Por ejemplo, puedes mostrar una lista desplazable para dar más espacio al menú y facilitar la navegación.

Áreas de texto

Si las personas necesitan escribir varias palabras, usa un área de texto.

  • Haz que las áreas de texto tengan al menos dos líneas de altura, para que sean más fáciles de usar y no parezcan campos de texto.
  • Coloca etiquetas encima.

Campos de texto

Usa campos de texto si las personas solo necesitan escribir una o dos palabras.

  • El ancho de un campo de texto debería sugerir lo que esperas que las personas escriban en él.
  • Evita usar texto de marcador de posición como etiqueta, ya que desaparece en el enfoque. El texto de marcador de posición es útil para dar ejemplos o detalles adicionales.
  • Coloca etiquetas encima, pero no dudes en colocar campos de texto cortos uno al lado del otro.

Desarrollo de la marca

En tu complemento

Si quieres incluir elementos de desarrollo de la marca, hazlo breve y claro. Esto ayuda a las personas a enfocarse en tu IU y hace que tu complemento se sienta como parte del editor.

  • Todos los aspectos de tu complemento deben seguir los lineamientos para el desarrollo de la marca.
  • No incluya la palabra “Google” ni utilice íconos de productos de Google.
  • El texto debe tener solo algunas palabras y tener el estilo de la clase gray desde el paquete de complementos de CSS.
  • Los gráficos deben estar sobre un fondo blanco y no deben superar los 200 px × 60 px.
  • Para los diálogos, el desarrollo de la marca debe estar en la esquina inferior derecha.
  • En el caso de las barras laterales, el desarrollo de la marca puede estar en la parte superior o inferior.

En la tienda

Para publicar un complemento de editor, necesitas varios elementos de imagen. Estos elementos se usan para crear la ficha de Play Store complementaria.

Accesibilidad

Todos deberían poder disfrutar del complemento, ya sea que vean los colores de otra manera, que usen un lector de pantalla o que tengan otras necesidades. La accesibilidad es un tema amplio que no se aborda por completo en esta guía de estilo. Un recurso útil es el sitio Google Accessibility. Estas son algunas sugerencias para comenzar:

  • Asegúrate de poder navegar a todos los controles de la IU con el teclado. Agrega tabindex=0 a los controles personalizados (como los creados con <div>) para que las personas puedan acceder a ellos. Considera si otras claves también deberían ser compatibles, como las flechas para una lista.
  • Es posible que algunas personas usen un lector de pantalla con tu complemento. Por lo tanto, las imágenes deben tener un atributo alt y los controles personalizados deben tener atributos ARIA para describir su uso.
  • No dependas únicamente del color para comunicar el estado. Usa también íconos y texto.

Si usas controles web estándar, como los que se describieron antes en esta guía, es más fácil hacer que tu complemento sea accesible.