Índice

HTML

CSS

前端 HTML-CSS 规范

Regla de oro

¡Un proyecto debe seguir siempre el mismo conjunto de estándares de codificación!

No importa cuántas personas participen en el mismo proyecto, asegúrate de que cada línea de código parezca escrita por la misma persona.

HTML

Sintaxis

  • Usa dos espacios en lugar de tabulaciones (tab): es la única forma de garantizar una representación consistente en todos los entornos.
  • Los elementos anidados deben sangrarse una vez (es decir, dos espacios).
  • Para la definición de atributos, asegúrate de usar siempre comillas dobles, nunca comillas simples.
  • No añadas una barra diagonal al final de los elementos autocerrados (self-closing):La especificación de HTML5establece explícitamente que esto es opcional.
  • No omitas las etiquetas de cierre opcionales (closing tag) (por ejemplo,</li>o</body>）。
<!DOCTYPE html>
<html>
  <head>
    <title>Page title</title>
  </head>
  <body>
    <img src="images/company-logo.png.html" alt="Company">
    <h1 class="hello-world">Hello, world!</h1>
  </body>
</html>

HTML5 doctype

Añade la declaración de modo estándar (standard mode) en la primera línea de cada página HTML para garantizar una representación consistente en todos los navegadores.

<!DOCTYPE html>
<html>
  <head>
  </head>
</html>

Atributo de idioma

Según la especificación de HTML5:

Se recomienda encarecidamente especificar el atributo lang en el elemento raíz html para establecer el idioma correcto del documento. Esto ayuda a las herramientas de síntesis de voz a determinar la pronunciación que deben usar y a las herramientas de traducción a determinar las reglas que deben seguir al traducir, entre otras cosas.

Más información sobrelangel atributo se puede consultar enesta especificaciónpara conocer más.

Aquí se enumeranla tabla de códigos de idioma。

<html lang="zh-CN">
  <!-- ... -->
</html>

Modo de compatibilidad de IE

IE admite mediante una etiqueta específica<meta>etiqueta para determinar la versión de IE que se debe usar para representar la página actual. A menos que haya una necesidad especial, lo mejor es configurarla comoedge mode, de modo que IE utilice el modo más reciente que soporta.

Lee este artículo de Stack Overflowpara obtener más información útil.

<meta http-equiv="X-UA-Compatible" content="IE=Edge">

Codificación de caracteres

Al declarar explícitamente la codificación de caracteres, se garantiza que el navegador pueda determinar rápida y fácilmente cómo renderizar el contenido de la página. Esto tiene la ventaja de evitar el uso de entidades de caracteres (character entity) en HTML, de modo que todo sea coherente con la codificación del documento (generalmente UTF-8).

<head>
  <meta charset="UTF-8">
</head>

Incluir archivos CSS y JavaScript

Según la especificación de HTML5, al incluir archivos CSS y JavaScript generalmente no es necesario especificartypeel atributo, porquetext/cssytext/javascriptson sus valores predeterminados respectivamente.

HTML5 spec links

<!-- External CSS -->
<link rel="stylesheet" href="code-guide.css.html">

<!-- In-document CSS -->
<style>
  /* ... */
</style>

<!-- JavaScript -->
<script src="code-guide.js.html"></script>

La practicidad ante todo

Intenta seguir los estándares y la semántica de HTML, pero no a costa de la practicidad. Usa siempre la menor cantidad de etiquetas posible y mantén la complejidad al mínimo.

Orden de los atributos

Los atributos HTML deben ordenarse según el orden que se indica a continuación para garantizar la legibilidad del código.

  • class
  • id, name
  • data-*
  • src, for, type, href
  • title, alt
  • aria-*, role

class se usa para identificar componentes altamente reutilizables, por lo que debe ir primero. id se usa para identificar componentes específicos y debe usarse con precaución (por ejemplo, marcadores dentro de la página), por lo que va en segundo lugar.

<a class="..." id="..." data-modal="toggle" href="../index.html">
  Example link
</a>

<input class="form-control" type="text">

<img src="....html" alt="...">

Atributos booleanos

Los atributos booleanos pueden declararse sin asignarles un valor. La especificación de XHTML exige asignarles un valor, pero la de HTML5 no lo requiere.

Para más información, consultaWhatWG section on boolean attributes：

Un atributo booleano de un elemento es true si tiene valor, y false si no lo tiene.

Sirealmentetienes que asignarle un valor, consulta la especificación de WhatWG:

Si el atributo existe, su valor debe ser una cadena vacía o el nombre canónico del atributo [...] y no debe contener espacios en blanco al final.

En pocas palabras, no necesita un valor.

<input type="text" disabled>

<input type="checkbox" value="1" checked>

<select>
  <option value="1" selected>1</option>
</select>

Reducir el número de etiquetas

Al escribir código HTML, evita en lo posible los elementos padre innecesarios. En muchos casos, esto requiere iteración y refactorización. Mira el siguiente ejemplo:

<!-- Not so great -->
<span class="avatar">
  <img src="....html">
</span>

<!-- Better -->
<img class="avatar" src="....html">

Etiquetas generadas por JavaScript

Las etiquetas generadas mediante JavaScript hacen que el contenido sea difícil de encontrar y editar, y además reducen el rendimiento. Evítalas siempre que sea posible.

CSS

Sintaxis

  • Usa dos espacios en lugar de tabulaciones (tab): es la única forma de garantizar una representación consistente en todos los entornos.
  • Al agrupar selectores, coloca cada selector individual en una línea separada.
  • Para mayor legibilidad del código, añade un espacio antes de la llave de apertura de cada bloque de declaración.
  • La llave de cierre del bloque de declaración debe ir en una línea separada.
  • Tras los dos puntos de cada declaración:se debe insertar un espacio.
  • Para obtener informes de error más precisos, cada declaración debe ocupar una sola línea.
  • Todas las declaraciones deben terminar con un punto y coma. El punto y coma después de la última declaración es opcional, pero si lo omites, tu código puede ser más propenso a errores.
  • Para los valores de propiedades separados por comas, se debe insertar un espacio después de cada coma (por ejemplo,box-shadow）。
  • Norgb()、rgba()、hsl()、hsla()orect()del valorinteriorse debe insertar un espacio después de la coma. Esto ayuda a distinguir entre los valores de propiedades (que van separados por coma y espacio) y los valores de color (que solo usan coma, sin espacio).
  • Para valores de propiedad o parámetros de color, omite el 0 antes de los decimales menores que 1 (por ejemplo,.5en lugar de0.5；-.5pxen lugar de-0.5px）。
  • Los valores hexadecimales deben estar en minúsculas, por ejemplo,#fff. Al escanear un documento, los caracteres en minúsculas son más fáciles de distinguir, ya que sus formas se diferencian mejor.
  • Usa valores hexadecimales abreviados siempre que sea posible; por ejemplo, usa#fffen lugar de#ffffff。
  • Añade comillas dobles a los atributos de los selectores, por ejemplo,input[type="text"]。es opcional solo en ciertos casos, pero por consistencia del código, se recomienda añadirlas siempre.
  • Evita especificar unidades para valores 0; por ejemplo, usamargin: 0;en lugar demargin: 0px;。

¿Tienes dudas sobre los términos usados aquí? Consulta el artículo de Wikipedia sobresyntax section of the Cascading Style Sheets article。

/* Bad CSS */
.selector, .selector-secondary, .selector[type=text] {
  padding:15px;
  margin:0px 0px 15px;
  background-color:rgba(0, 0, 0, 0.5);
  box-shadow:0px 1px 2px #CCC,inset 0 1px 0 #FFFFFF
}

/* Good CSS */
.selector,
.selector-secondary,
.selector[type="text"] {
  padding: 15px;
  margin-bottom: 15px;
  background-color: rgba(0,0,0,.5);
  box-shadow: 0 1px 2px #ccc, inset 0 1px 0 #fff;
}

Orden de las declaraciones

Las declaraciones de propiedades relacionadas deben agruparse y ordenarse de la siguiente manera:

  1. Positioning
  2. Box model
  3. Typographic
  4. Visual

Dado que el posicionamiento puede sacar elementos del flujo normal del documento y también puede sobrescribir estilos relacionados con el modelo de caja (box model), va primero. El modelo de caja va segundo, porque determina el tamaño y la posición del componente.

Los demás atributos solo afectan alinterior (inside)o no afectan a los dos grupos anteriores, por lo que se colocan al final.

Consulta la lista completa de propiedades y su orden enRecess。

.declaration-order {
  /* Positioning */
  position: absolute;
  top: 0;
  right: 0;
  bottom: 0;
  left: 0;
  z-index: 100;

  /* Box-model */
  display: block;
  float: right;
  width: 100px;
  height: 100px;

  /* Typography */
  font: normal 13px "Helvetica Neue", sans-serif;
  line-height: 1.5;
  color: #333;
  text-align: center;

  /* Visual */
  background-color: #F5F5F5;
  border: 1px solid #E5E5E5;
  border-radius: 3px;

  /* Misc */
  opacity: 1;
}

No usar@import

y<link>en comparación con la etiqueta@importLa directiva es mucho más lenta, no solo aumenta el número de solicitudes adicionales, sino que también puede causar problemas impredecibles. Las alternativas son las siguientes:

  • Usar varios<link>elementos
  • Mediante preprocesadores de CSS como Sass o Less, compila varios archivos CSS en un solo archivo.
  • Mediante la funcionalidad de combinación de archivos CSS disponible en Rails, Jekyll u otros sistemas.

Consulteel artículo de Steve Souderspara obtener más información.

<!-- Use link elements -->
<link rel="stylesheet" href="core.css.html">

<!-- Avoid @imports -->
<style>
  @import url("more.css");
</style>

Posición de las media queries

Coloque las consultas de medios lo más cerca posible de las reglas relacionadas. No las empaquete en un solo archivo de estilos ni las coloque al final del documento. Si las separa, caerán en el olvido. A continuación, un ejemplo típico.

.element { ... }
.element-avatar { ... }
.element-selected { ... }

@media (min-width: 480px) {
  .element { ...}
  .element-avatar { ... }
  .element-selected { ... }
}

Propiedades con prefijo

Al usar propiedades con prefijo de un proveedor específico, alinee verticalmente los valores de cada propiedad mediante sangrías para facilitar la edición en varias líneas.

En Textmate, useText → Edit Each Line in Selection(⌃⌘A). En Sublime Text 2, useSelection → Add Previous Line(⌃⇧↑) ySelection → Add Next Line (⌃⇧↓).

/* Prefixed properties */
.selector {
  -webkit-box-shadow: 0 1px 2px rgba(0,0,0,.15);
          box-shadow: 0 1px 2px rgba(0,0,0,.15);
}

Declaraciones de reglas en una sola línea

En el caso deestilos que contienen una sola declaración, para facilitar la lectura y la edición rápida, se recomienda colocar la declaración en la misma línea. Para los estilos con múltiples declaraciones, las declaraciones deben dividirse en varias líneas.

El factor clave de esto es la detección de errores; por ejemplo, el validador de CSS indica un error de sintaxis en la línea 183. Si es una sola declaración en una línea, no ignorará el error; si son múltiples declaraciones en una sola línea, deberá analizar cuidadosamente para no pasar por alto el error.

/* Single declarations on one line */
.span1 { width: 60px; }
.span2 { width: 140px; }
.span3 { width: 220px; }

/* Multiple declarations, one per line */
.sprite {
  display: inline-block;
  width: 16px;
  height: 15px;
  background-image: url(../img/sprite.png);
}
.icon           { background-position: 0 0; }
.icon-home      { background-position: 0 -20px; }
.icon-account   { background-position: 0 -40px; }

Declaraciones abreviadas de propiedades

Cuando sea necesario establecer explícitamente todos los valores, se debe limitar el uso de declaraciones de propiedades abreviadas. Los abusos comunes de las declaraciones abreviadas son los siguientes:

  • padding
  • margin
  • font
  • background
  • border
  • border-radius

En la mayoría de los casos, no necesitamos especificar todos los valores en las declaraciones de propiedades abreviadas. Por ejemplo, los elementos de encabezado (heading) de HTML solo necesitan establecer los valores de margen superior e inferior; por lo tanto, cuando sea necesario, basta con sobrescribir esos dos valores. El uso excesivo de declaraciones de propiedades abreviadas puede causar confusión en el código y provocar sobrescrituras innecesarias de los valores de las propiedades, lo que genera efectos secundarios inesperados.

MDN (Mozilla Developer Network) presenta un muy buen artículo sobreshorthand propertiesque es muy útil para los usuarios que no estén familiarizados con las declaraciones de propiedades abreviadas y su comportamiento.

/* Bad example */
.element {
  margin: 0 0 10px;
  background: red;
  background: url("image.jpg");
  border-radius: 3px 3px 0 0;
}

/* Good example */
.element {
  margin-bottom: 10px;
  background-color: red;
  background-image: url("image.jpg");
  border-top-left-radius: 3px;
  border-top-right-radius: 3px;
}

Anidamiento en Less y Sass

Evite el anidamiento innecesario. Aunque se puede usar el anidamiento, no significa que deba usarse. Utilícelo solo cuando sea necesario restringir los estilos al elemento padre (es decir, un selector descendiente) y existan varios elementos que necesiten anidarse.

// Without nesting
.table > thead > tr > th { … }
.table > thead > tr > td { … }

// With nesting
.table > thead > tr {
  > th { … }
  > td { … }
}

Comentarios

El código es escrito y mantenido por personas. Asegúrese de que su código sea autodescriptivo, esté bien comentado y sea fácil de entender para otros. Los buenos comentarios transmiten el contexto y el propósito del código. No se limite a repetir el nombre del componente o de la clase.

Para comentarios largos, escriba oraciones completas; para anotaciones generales, puede usar frases concisas.

/* Bad example */
/* Modal header */
.modal-header {
  ...
}

/* Good example */
/* Wrapping element for .modal-title and .modal-close */
.modal-header {
  ...
}

Nombrado de clases

  • En los nombres de clase solo deben aparecer letras minúsculas y guiones (dash) (no guiones bajos ni nomenclatura camelCase). Los guiones deben usarse para nombrar clases relacionadas (similar a un espacio de nombres) (por ejemplo,.btny.btn-danger）。
  • Evite abreviaturas demasiado arbitrarias..btnrepresentabutton, pero.sno expresa ningún significado.
  • Los nombres de clase deben ser lo más cortos posible y con un significado claro.
  • Use nombres significativos. Use nombres organizados o basados en el propósito, no nombres de tipo presentacional.
  • Use la clase principal más cercana o la clase base como prefijo de las nuevas clases.
  • Use.js-*clases para identificar el comportamiento (a diferencia del estilo) y no incluya estas clases en el archivo CSS.

Al nombrar variables de Sass y Less, también puede consultar las especificaciones enumeradas anteriormente.

/* Bad example */
.t { ... }
.red { ... }
.header { ... }

/* Good example */
.tweet { ... }
.important { ... }
.tweet-header { ... }

Selectores

  • Use clases para elementos genéricos, ya que esto favorece la optimización del rendimiento del renderizado.
  • Para componentes frecuentes, evite usar selectores de atributo (por ejemplo,[class^="..."]). El rendimiento del navegador puede verse afectado por estos factores.
  • Los selectores deben ser lo más cortos posible y limite el número de elementos que los componen; se recomienda no superar 3.
  • Solorestrinja la clase al elemento padre más cercano cuando sea necesario (es decir, un selector descendiente) (por ejemplo, cuando no se usen clases con prefijo; el prefijo es similar a un espacio de nombres).

Lectura adicional:

/* Bad example */
span { ... }
.page-container #stream .stream-item .tweet .tweet-header .username { ... }
.avatar { ... }

/* Good example */
.avatar { ... }
.tweet-header .username { ... }
.tweet .avatar { ... }

Organización del código

  • Organice los bloques de código por componentes.
  • Establezca convenciones de comentarios coherentes.
  • Use espacios en blanco consistentes para separar el código en bloques, lo que facilita el escaneo de documentos grandes.
  • Si usa varios archivos CSS, divídalos por componentes en lugar de por páginas, porque las páginas pueden reorganizarse, mientras que los componentes solo se mueven.
/*
 * Component section heading
 */

.element { ... }


/*
 * Component section heading
 *
 * Sometimes you need to include optional context for the entire component. Do that up here if it's important enough.
 */

.element { ... }

/* Contextual sub-component or modifer */
.element-heading { ... }

Configuración del editor

Configure su editor con las siguientes opciones para evitar inconsistencias y diferencias comunes en el código:

  • Use dos espacios en lugar de tabuladores (soft-tab, es decir, usar espacios para representar el tabulador).
  • Al guardar archivos, elimine los espacios en blanco al final.
  • Configure la codificación del archivo como UTF-8.
  • Agregue una línea en blanco al final del archivo.

Consulte la documentación y agregue esta información de configuración al.editorconfigarchivo del proyecto. Por ejemplo:Ejemplo de .editorconfig en Bootstrap. Para obtener más información, consulteabout EditorConfig。