Compartir a través de

Recomendaciones para trabajar con CSS en soluciones de SharePoint Framework

Al compilar soluciones de SharePoint Framework, puede usar CSS para definir la apariencia de la personalización y cómo debe comportarse. En este artículo, se describe cómo puede aprovechar al máximo las funciones que incluye SharePoint Framework y compilar los estilos CSS de forma eficaz.

Las personalizaciones de SharePoint Framework forman parte de la página

Al compilar las personalizaciones de SharePoint con el modelo de complementos, la solución está aislada de otros elementos de la página. Puede ejecutar el código en un iFrame como un elemento de complemento o como una aplicación envolvente que toma el control de toda la página. En ambos casos, el código no se ve afectado por otros elementos y estilos definidos en la página.

Las soluciones de SharePoint Framework forman parte de la página y se integran completamente con el DOM de la página. Aunque esta acción quita varias restricciones que vienen con el modelo de complementos, expone la solución a riesgos. Dado que forman parte de la página, a no ser que se aíslen de forma explícita, se le aplicarán todos los estilos CSS presentes en la página, lo que podría provocar una experiencia diferente de la que se planeaba. Para evitar estos riesgos, debe definir los estilos CSS de manera que no afecten a nada más en la página que no sea la personalización.

Organizar archivos CSS en la solución

A menudo, la interfaz de usuario de la solución se compone de varios bloques de creación. En muchas bibliotecas de JavaScript, estos bloques de creación se denominan componentes. Un componente puede ser sencillo y definir solo la presentación o puede ser más complejo e incluir el estado y otros componentes. Dividir una solución en varios componentes le permite simplificar el proceso de desarrollo y le ayuda a probar y volver a usar los componentes de la solución.

Dado que los componentes tienen una presentación, a menudo requieren estilos CSS. Lo ideal es que los componentes estén aislados y puedan usarse por sí mismos. Si se tiene esto en cuenta, tiene sentido que almacene los estilos CSS de un componente concreto junto con los demás archivos de recursos junto al componente. A continuación encontrará un ejemplo de estructura de una aplicación de React con varios componentes, cada uno con su propio archivo CSS.

todoWebPart\components
                      \todoList
                               \todoList.tsx
                               \todoList.module.scss
                      \todoItem
                               \todoItem.tsx
                               \todoItem.module.scss

Usar SASS

En SharePoint Framework, puede usar tanto CSS como SASS. SASS es un superconjunto de CSS y le ofrece varias características (por ejemplo, variables, anidamiento de selectores o mixins) y todas ellas simplifican el trabajo y la administración de estilos CSS a largo plazo.

Para obtener un conjunto completo de características, consulte el sitio web de SASS. Todo el CSS válido también es SASS válido, lo que resulta muy útil si no ha trabajado con SASS antes y quiere aprender sus funcionalidades de forma gradual.

Evitar el uso de identificadores en el marcado

Con SharePoint Framework, compila personalizaciones que los usuarios finales agregan a SharePoint. Es imposible saber por adelantado si esa personalización en cuestión se usa una sola vez en una página o si hay varias instancias de ella.

Para evitar problemas, debe asumir siempre que hay varias instancias de la personalización en la misma página. Teniendo esto en cuenta, debe evitar usar identificadores en el marcado. Los identificadores están diseñados para ser únicos en una página y, si un usuario agrega el elemento web a la página dos veces, infringe este supuesto, lo que posiblemente producirá errores.

Procedimiento no recomendado

// ...

export default class HelloWorldWebPart extends BaseClientSideWebPart<IHelloWorldWebPartProps> {

  public render(): void {
    this.domElement.innerHTML = `
      <div id="helloWorld">
        Hello world
      </div>`;
  }

  // ...
}

Procedimiento recomendado

// ...

export default class HelloWorldWebPart extends BaseClientSideWebPart<IHelloWorldWebPartProps> {

  public render(): void {
    this.domElement.innerHTML = `
      <div class="${styles.helloWorld}">
        Hello world
      </div>`;
  }

  // ...
}

Usar módulos CSS para evitar conflictos de estilo

SharePoint Framework soluciones forman parte de la página. Para asegurarse de que los estilos CSS de un componente no afectan a otros elementos de la página, debe definir los selectores CSS de forma que solo se apliquen al DOM de la solución. Es tedioso y propenso a errores hacerlo manualmente, pero SharePoint Framework puede hacerlo automáticamente.

Para ayudarle a evitar los conflictos de estilo, SharePoint Framework usa módulos CSS. Al compilar el proyecto, la cadena de herramientas de SharePoint Framework procesa todos los archivos con la extensión .module.scss. Para cada archivo, lee todos los selectores de clases y les anexa un valor de hash único. Cuando ha terminado, escribe los selectores actualizados en los archivos CSS intermedios que se incluyen en la agrupación de elementos web generada.

Siguiendo el ejemplo anterior, suponga que tenía los dos archivos SASS siguientes:

todoList.module.scss

.todoList {
  margin: 1em 0;

  .text {
    font-weight: bold;
    font-size: 1.5em;
  }
}

todoItem.module.scss

.todoItem {
  padding: 0.5em 1em;

  .text {
    font-size: 0.9em;
  }
}

Después de generar el proyecto, en la carpeta lib verá los dos siguientes archivos CSS generados (se han agregado saltos de línea y sangría para mejorar la legibilidad):

todoList.module.css

.todoList_3e9d35f0 {
  margin:1em 0
}

.todoList_3e9d35f0 .text_3e9d35f0 {
  font-weight:700;
  font-size:1.5em
}

todoItem.module.css

.todoItem_f7081cc4 {
  padding:.5em 1em
}

.todoItem_f7081cc4 .text_f7081cc4 {
  font-size:.9em
}

Aunque en los dos archivos Sass se definió una clase .text, observe cómo en los archivos CSS generados tiene dos valores hash diferentes anexados, convirtiéndose en un nombre de clase único específico de cada componente.

Los nombres de clase CSS de los módulos CSS se generan dinámicamente, lo que hace que sea imposible hacer referencia a ellos directamente en el código. En su lugar, al procesar módulos CSS, la cadena de herramientas de SharePoint Framework genera un archivo JavaScript con referencias a los nombres de clase generados.

todoList.module.scss.js

"use strict";
Object.defineProperty(exports, "__esModule", { value: true });
/* tslint:disable */
require('./todoList.module.css');
var styles = {
    todoList: 'todoList_3e9d35f0',
    text: 'text_3e9d35f0',
};
exports.default = styles;
/* tslint:enable */

//# sourceMappingURL=todoList.module.scss.js.map

Para usar los nombres de clase generados en el código, primero se importan los estilos del componente y, después, se usa la propiedad que apunta a la clase concreta:

import styles from './todoList.module.scss';
// ...

export default class TodoList extends React.Component<ITodoListProps, void> {
  public render(): React.ReactElement<ITodoListProps> {
    return (
      <div className={styles.todoList}>
        <div className={styles.text}>Hello world</div>
      </div>
    );
  }
}

Para que los módulos CSS funcionen correctamente, se deben cumplir las siguientes condiciones:

  • Los archivos SASS deben tener la extensión .module.scss. Si usa la extensión .scss sin .module, verá una advertencia en el proceso de compilación. El archivo SASS se transpila a un archivo CSS intermedio, pero los nombres de clase no serán únicos. En los casos en que necesite reemplazar estilos CSS de terceros, es posible que esto sea lo que se pretende.

  • Los nombres de clase CSS deben ser nombres de variables de JavaScript válidos. Por ejemplo, no pueden contener guiones: todoList es correcto, pero todo-list no lo es.

  • Le recomendamos que use nombres con mayúsculas y minúsculas combinadas para las clases, pero no es obligatorio.

Encapsular los estilos CSS en una clase con el nombre del componente

Mediante la combinación de módulos CSS con la compatibilidad de SASS con conjuntos de reglas anidados, se pueden simplificar los estilos CSS y asegurarse de que no afectan a otros elementos de la página.

Al compilar estilos CSS para un componente, encapsúlelos en una clase con el nombre del componente. En el componente, asigne esa clase al elemento raíz del componente.

todoList.module.scss

.todoList {
  a {
    display: block;
  }
}

TodoList.tsx

// ...

export default class TodoList extends React.Component<ITodoListProps, void> {
  public render(): React.ReactElement<ITodoListProps> {
    return (
      <div className={styles.todoList}>
        ...
      </div>
    );
  }
}

Después de la transpilación, el archivo CSS generado tiene un aspecto similar al siguiente:

.todoList_3e9d35f0 a {
  display: block;
}

Como el selector comienza con el nombre de clase único, específico del componente, la presentación alternativa solo se aplica a los hipervínculos dentro del componente.

Control del prefijo de proveedor CSS

En SharePoint Framework, no se requiere ninguna propiedad de estilo con prefijo de proveedor en los archivos SASS o CSS de un proyecto. Si alguno de los exploradores compatible con SharePoint Framework requiere prefijos, se han agregado automáticamente después de la compilación de SASS a CSS. Este método también se conoce como aplicación automática de prefijos y es una parte fundamental de la cadena de compilación de CSS en SharePoint Framework.

En caso de que un elemento web deba usar el nuevo modelo de cuadros definido por la declaración display: flex, algunas versiones anteriores basadas en WebKit y de Internet Explorer requieren un prefijo de proveedor determinado definido en la CSS.

.container{
  display: flex;
}

El código SASS del artefacto de SharePoint Framework no tiene que disponer de prefijos de proveedor incluidos. Después de la compilación de SASS a CSS, los que se han agregado automáticamente tienen como resultado la siguiente declaración CSS.

.container_7e976ae1 {
  display: -webkit-box; // older Safari on MacOS and iOS
  display: -ms-flexbox; // IE 10 - 11
  display: flex;
}

Si se quitan los prefijos ya aplicados, no solo el código del artefacto queda más claro, sino que también facilita la lectura y la preparación futura. Este proceso también se configura para admitir solo exploradores compatibles con SharePoint Framework y lo hace más seguro frente a errores.

Si un elemento web ya tiene prefijos de proveedor incluidos en los archivos SASS que no volverán a ser necesarios, el mismo proceso elimina esas declaraciones de forma automática.

En el ejemplo siguiente, se usa la propiedad border-radius, que no necesita prefijos de proveedor en los sistemas admitidos.

.container {
  /* Safari 3-4, iOS 1-3.2, Android 1.6- */
  -webkit-border-radius: 7px;
  /* Firefox 1-3.6 */
  -moz-border-radius: 7px;
  /* Opera 10.5, IE 9, Safari 5, Chrome, Firefox 4, iOS 4, Android 2.1+ */
  border-radius: 7px;
}

La CSS resultante en el paquete se convierte en el siguiente código.

.container_9e54c0b0 {
  border-radius: 7px
}

Para obtener más información sobre la aplicación automática de prefijos, vea el repositorio de GitHub autoprefixer. La base de datos para este proceso está disponible en Can I use__?

Integrar Office UI Fabric

Si hace que las personalizaciones se parezcan y comporten como la funcionalidad estándar de SharePoint y Office 365, será más fácil para los usuarios finales trabajar con ellas. Office UI Fabric ofrece un conjunto de controles y estilos para su uso en las personalizaciones a fin de integrarlas sin ningún problema con la experiencia del usuario existente.

Para obtener más información sobre cómo usar Office UI Fabric en SharePoint Framework, consulte Usar Office UI Fabric Core y Office UI Fabric React en SharePoint Framework.

Usar colores del tema

SharePoint permite a los usuarios elegir el color del tema de sus sitios. En las personalizaciones de SharePoint Framework, debe seguir el tema seleccionado por los usuarios para que la personalización tenga la misma apariencia que un elemento integral del sitio en lugar de destacar de forma innecesaria.

Dado que el tema lo establecen los usuarios en su sitio, no podrá saber con antelación qué colores debe usar la personalización, pero SharePoint Framework puede cargar dinámicamente la combinación de colores activa de forma automática.

Para obtener más información sobre esta función, consulte Usar colores del tema en las personalizaciones de SharePoint Framework.