Compartir a través de

Usar Office UI Fabric Core y Office UI Fabric React en SharePoint Framework

  • Artículo

Office UI Fabric es el marco front-end oficial para crear experiencias en Office 365 y SharePoint. SharePoint proporciona una integración perfecta con Fabric que permite a Microsoft ofrecer un lenguaje de diseño sólido y coherente en varias experiencias de SharePoint, como sitios de equipo modernos, páginas modernas y listas modernas. Además, office UI Fabric está disponible para los desarrolladores de la SharePoint Framework al compilar soluciones personalizadas de SharePoint.

Microsoft usa Fabric Core y Fabric React en SharePoint. Microsoft inserta periódicamente actualizaciones en SharePoint Online que también pueden actualizar las versiones de Fabric Core y Fabric React. Puede que estas actualizaciones entren en conflicto con soluciones de terceros compiladas con versiones anteriores de Fabric Core y Fabric React, lo que puede producir excepciones en las personalizaciones. El motivo principal de estos tipos de interrupciones es el uso de estilos CSS globales en las dos bibliotecas de Fabric. Este tipo de conflictos deben evitarse a toda costa.

El desafío de los estilos de CSS globales se explica en la presentación siguiente en el contexto de React y JavaScript: React y CSS en JS.

Para lograr una mayor confiabilidad, uno de los principales problemas que hay que resolver es el de los estilos CSS globales. Se plantea la posibilidad de no usar nombres de clase globales en formato HTML y usar en su lugar mixins y variables de Fabric Core en el archivo de declaraciones SASS. Esto implica importar las declaraciones SASS de Fabric Core en el archivo de SASS y luego usar las variables y los mixins correctamente.

Objetivos

Uno de los objetivos de SharePoint Framework es permitir a Microsoft y a los clientes compilar experiencias de usuario completas, atractivas y coherentes con SharePoint.

Según estos objetivos, seguidamente se muestran los principios clave de diseño:

  • Los clientes deben poder usar Fabric Core y Fabric React con confianza y sin problemas en sus soluciones.
  • Microsoft distribuirá experiencias actualizadas que usen versiones actualizadas de Fabric Core y Fabric React en SharePoint que no entren en conflicto con las soluciones del cliente.
  • Los clientes pueden personalizar y reemplazar los estilos, los diseños y los componentes predeterminados para adaptarlos a las necesidades de la solución.

Hay dos componentes de Office UI Fabric que están disponibles para que los usen los desarrolladores:

  • Office UI Fabric Core. Conjunto de estilos básicos, tipografía, cuadrícula con capacidad de respuesta, animaciones, iconos y otros bloques de creación fundamentales del lenguaje de diseño global.

  • Office UI Fabric React. Conjunto de componentes de React creado con el lenguaje de diseño Fabric para su uso en proyectos basados en React.

Paquete de Office UI Fabric Core

El paquete npm de Fabric Core de SharePoint Framework (@microsoft/sp-office-ui-fabric-core) contiene un subconjunto de estilos de Fabric Core admitidos que puedan usarse de forma segura en un componente de SharePoint Framework.

Se admiten los siguientes estilos básicos en el paquete:

  • Tipografía
  • Diseños
  • Colores
  • Temas
  • Localización

No se admite lo siguiente en el paquete:

  • Animaciones
  • Iconos

A partir de la versión 1.3.4 del generador de Yeoman de SharePoint Framework, las plantillas predeterminadas de proyecto (elementos web y extensiones) se incluyen en la instalación del nuevo paquete @microsoft/sp-office-ui-fabric-core y usan estilos básicos del paquete en lugar de estilos CSS globales.

Actualizar proyectos existentes

Para usar el paquete de Fabric Core en el proyecto existente, instale el paquete como dependencia:

npm install @microsoft/sp-office-ui-fabric-core --save

Una vez instalado, puede importar las declaraciones SASS de Fabric Core en el archivo de definición SASS y usar las variables y los mixins tal y como se describe en la sección siguiente.

Usar estilos de Fabric Core

Para usar los estilos de Fabric Core, debe importar primero las declaraciones SPFabricCore en el archivo de SASS.

Nota:

Asegúrese de tener instalado el paquete npm @microsoft/sp-office-ui-fabric-core.

@import '~@microsoft/sp-office-ui-fabric-core/dist/sass/SPFabricCore.scss';

Ahora, puede usar los estilos básicos como mixins y variables.

.row {
  @include ms-Grid-row;
  @include ms-fontColor-white;
  background-color: $ms-color-themeDark;
  padding: 20px;
}

Office UI Fabric React

Se recomienda usar las versiones del paquete Office UI Fabric React que se incluye en el proyecto en el generador Yeoman de SharePoint Framework. Por ejemplo, la versión de SharePoint Framework v1.7.0 usa Fabric React v5.131.0

Nota:

Las versiones 2.x o anteriores de Fabric React no se admiten en SharePoint Framework.

Cuando se haya instalado el paquete de Fabric React, puede importar los componentes necesarios desde la agrupación de Fabric React.

//import Button component from Fabric React Button bundle
import { Button } from 'office-ui-fabric-react/lib/Button';

//use it in your component
render() {
  ...
  <div>
    <Button>click me</Button>
  </div>
  ...
}

El paquete de Fabric React incluye los estilos de Fabric Core admitidos que se usan en los componentes de Fabric React. Le recomendamos que importe los estilos de Fabric Core del paquete de Fabric React y no del paquete @microsoft/sp-office-ui-fabric-core para asegurarse de que se usan los estilos correctos en el componente.

Dado que el generador de Yeoman ya ha instalado el paquete @microsoft/sp-office-ui-fabric-core en la solución, le recomendamos que desinstale ese paquete si decide usar los componentes de Fabric y reducir el tamaño de la agrupación de componentes.

npm uninstall @microsoft/sp-office-ui-fabric-core --save

Luego, puede importar los estilos básicos de las declaraciones SASS disponibles en el paquete de Fabric React.

@import '~office-ui-fabric-react/dist/sass/_References.scss';

Descripción de este enfoque y sus puntos débiles

Los componentes de Fabric de la solución se bloquean para la versión concreta de Fabric React que haya instalado. Tiene que actualizar el paquete de Fabric React para obtener los nuevos componentes que estén disponibles en una versión más reciente del paquete. Dado que los componentes de Fabric se incluyen en la agrupación de componentes, es posible que aumente el tamaño de esta. Pero este es el único enfoque que se admite oficialmente cuando se usa Office UI Fabric React en soluciones de SharePoint Framework.

El desafío de CSS con Office UI Fabric

Los siguientes conceptos y referencias ofrecen información sobre el desafío del uso de Office UI Fabric en el contexto de elementos web del lado cliente.

Estilos CSS globales

Cómo evitar los estilos CSS globales a toda costa es un problema importante. Hoy en día, tanto Fabric Core como Fabric React tienen estilos globales. La falta de soluciones nativas del explorador para administrar el ámbito de estilo hace que sea un problema muy difícil.

  • Se está empezando a debatir sobre scope CSS.
  • Los iFrame no son una buena opción para aislar los estilos.
  • Web Components es otro estándar que trata de los estilos con ámbito, pero todavía se está trabajando en ello.
  • En la discusión sobre React: CSS en JS se explica el problema de manera detallada.

Hay una gran cantidad de documentación en Internet sobre las soluciones a la amenaza de espacio de nombres global.

Especificidad de CSS

Cómo se aplica la especificidad de CSS a la interfaz de usuario web. Los estilos con mayor especificidad reemplazan a aquellos de especificidad inferior, pero la clave para comprender su funcionamiento es cómo se aplican las reglas de especificidad. En general, el orden de prioridad de mayor a menor es el siguiente:

  • El atributo de estilo (por ejemplo, style="background:red;").
  • Los selectores de identificadores (por ejemplo, #myDiv { }).
  • Los selectores de clase (.myCssClass{}), los selectores de atributos ([type="radio"]) y las pseudoclases (:hover).
  • Los selectores de tipo (por ejemplo, h1).

Orden de carga. Si se aplican dos clases en un elemento y tienen la misma especificidad, la clase que se carga posteriormente tiene prioridad. Como se muestra en el siguiente código, el botón se muestra de color rojo. Si se cambia el orden de las etiquetas de estilo, el botón se muestra de color verde. Se trata de un concepto importante y, si no se usa correctamente, la experiencia del usuario puede convertirse en dependiente del orden de carga (es decir, incoherente).

<style>
  .greenButton { color: green; }
</style>
<style>
  .redButton { color: red; }
</style>
<body>
  <button class="greenButton redButton"></button>
</body>

Otros enfoques que se han considerado y descartado

A continuación se recopilan algunas ideas adicionales sobre los demás métodos que se han considerado, pero descartado, ya que no cumplían los objetivos clave para que los desarrolladores de terceros pudieran usar estilos de Office UI Fabric de manera segura.

Office UI Fabric Core

No sería necesario que el desarrollador del elemento web hiciera nada explícitamente para que el ámbito funcione. Teníamos la intención de resolver este problema a través de la especificidad de CSS y selectores descendientes. El equipo de Fabric Core incluiría varias copias del CSS de Fabric Core (por ejemplo, fabric-6.css, fabric-6-scoped.css, fabric-6.0.0.css y fabric-6.0.0-scoped.css).

Todos los estilos de los archivos CSS con ámbito estarían dentro de un selector descendiente, como .ms-Fabric--v6-0-0 .ms-Icon--List. Las herramientas en tiempo de compilación recopilarían la versión de Office UI Fabric Core con la que se compiló el elemento web. Esta versión podría ser la que se incluyera en SharePoint Framework. Por otra parte, los desarrolladores de elementos web podrían especificar una dependencia explícita en una versión específica de Office UI Fabric Core en el archivo package.json.

El elemento web div se asignaría a este ámbito, es decir, <div data-sp-webpart class="ms-Fabric--v6-0-0">. El marco cargaría la versión principal específica del archivo CSS con ámbito de Fabric Core. Si el elemento web se compiló con la versión 6.0.0 del CSS de Fabric Core, Framework descargaría fabric-6-scoped.css cuando se cargase el elemento web.

El resto de la página contendría estilos de Office UI Fabric Core sin ámbito. De este modo, según las reglas de la especificidad CSS, el CSS con ámbito prevalecería dentro del elemento web div. El elemento web entero y su contenido se alinearían con una versión específica de Office UI Fabric Core elegida por el desarrollador.

Reemplazar estilos de Fabric Core no se admitiría.

// Sample of how the scoping would work.
import { SPComponentLoader } from '@microsoft/sp-loader';

export default class MyWebPart {
    constructor() {
        super();

        SPComponentLoader.loadCss('https://static2.sharepointonline.com/files/fabric/office-ui-fabric-core/6.0.0/css/fabric-6.0.0.scoped.css');
    }
}

protected render(): void {
  <div className="ms-Fabric--v6-0-0">
    { // Rest of the web part UI }
  </div>
}

Inconvenientes de esta estrategia

Después de analizar esta estrategia detalladamente, se decidió que el enfoque de selector descendiente tiene dos inconvenientes graves que impiden compilar un elemento web que nunca se interrumpa.

Falta de compatibilidad fiable con el anidamiento

Este enfoque solo funciona si la experiencia del usuario de Microsoft (es decir, la página y los elementos web propios) usa una versión de Office UI Fabric Core sin ámbito (como ms-Icon--List), mientras que los elementos web de terceros usan solo el ámbito CSS de Office UI Fabric Core, como se explicó anteriormente.

La razón es que la especificidad de CSS con ámbito aplicado en el elemento web reemplaza el CSS sin ámbito en la página. Tenga en cuenta que, como se explicó anteriormente, si la especificidad de CSS de las dos clases es la misma, el orden de carga influye en la aplicación de las clases CSS. La clase que se cargue en último lugar tiene prioridad. Por lo tanto, la especificidad superior del CSS con ámbito es importante para obtener una experiencia coherente.

Además, varias extensiones, una contenida en la otra, no pueden usar diferentes versiones de Fabric Core. En el ejemplo siguiente, solo se aplicaría ms-Fabric--v6-0-0:

<div className="ms-Fabric--v6-0-0">
  { // Rest of the web part UI }
    { // inside of this SPExtension trying to use different Fabric core version does not work }
    <div className="ms-Fabric--v8-0-0">
    </div>
</div>

Aquí se ofrece un ejemplo más simple que muestra el desafío:

<html>
<head>
  <title>CSS specifity test</title>
  <style>
  .myButton {
      background-color: brown;
      color: brown;
      height: 20px;
      width: 40px;
  }
  </style>
  <style>
  .scope2 .myButton {
      background-color: green;
      color: green;
  }
  </style>
  <style>
  .scope3 .myButton {
      background-color: yellow;
      color: yellow;
  }
  </style>
  <style>
  .scope1 .myButton {
      background-color: red;
      color: red;
  }
  </style>
</head>
<body>
  <div>
    <span>These tests demonstrate descendant selectors, nesting and load order problems.</span>

    <div>
      <br/>
      <span>This test depicts that a descendant selector with the same specificity does not allow nesting.
      All buttons below do not take the innermost scope (i.e. they should be different colors), but they are all red.
      Further, if you change the ordering of the style tags, the colors will change. (i.e. the UI is load order dependant.)</span>
      <div class='scope1'>
        <button class='myButton'</button>
        <div class='scope2'>
          <button class='myButton'></button>
          <div class='scope3'>
            <button class='myButton'></button>
          </div>
        </div>
      </div>
    </div>
  </div>
</body>
</html>

Pérdida de clases sin ámbito

Los selectores descendientes causan otro problema. En el ejemplo anterior, los estilos de height y width de la clase sin ámbito myButton se aplican a todos los botones. Esto implica que un cambio en ese estilo podría interrumpir el código HTML de manera accidental mediante un marcado con ámbito.

Por ejemplo, supongamos que decidimos por alguna razón establecer la altura en 0 px en la clase myButton al nivel de la aplicación. Esto causa que todos los elementos web de terceros que usan la clase myButton tengan un valor de 0 px para height. En otras palabras, se producirá un paso atrás grave en la experiencia del usuario.

Usar de forma segura estilos de Office UI Fabric heredados (después de SPFx v1.8.2)

Importante

Las siguientes instrucciones se aplican a SharePoint Framework >= 1.8.2

Asegúrese de que el manifiesto del elemento web exige que los estilos de Fabric Core heredados se carguen en la página. Esto se realiza especificando loadLegacyFabricCss: true en el manifiesto de la solución.

Antes del lanzamiento de SPFx v1.8.2, estaba presente un error de página de host donde los estilos de Fabric Core heredados se cargaban sin ámbito. Por lo tanto, si otra solución exigía los estilos, el resto de las soluciones de la página podían usarlos. Esto llevó a que las soluciones funcionaran "por casualidad" cuando no se representaban en forma de aislamiento.

Para solucionar este error, el ámbito de clase .ms-SPLegacyFabricBlock se aplicó a los estilos y a las soluciones de SPFx que exigen que se cargue la hoja de estilos Fabric Core. Para proporcionar una ruta de migración para las soluciones que dependen del efecto secundario anterior, la clase .ms-SPLegacyFabricBlock se aplica a todos los <div>expuestos a soluciones de terceros. Durante ese tiempo, modifique las soluciones afectadas para declarar la dependencia en los estilos de Fabric Core heredados.

Importante

Finalmente, la referencia explícita a .ms-SPLegacyFabricBlockse quitará del DOM para las soluciones que no declaran su dependencia. Este cambio se comunicará de forma amplia a través de los canales existentes antes de quitar esta clase.

En el caso de una solución que se ejecute en los elementos del DOM no proporcionados por SPFx (lo que generalmente no es compatible), tendrá que aplicar la clase .ms-SPLegacyFabricBlock usted mismo.

Uso de los iconos de Office UI Fabric en componentes de SPFx

Hay cambios sobre cómo usar los iconos de Office UI Fabric en la representación de las soluciones de SharePoint Framework desde SharePoint Framework v 1.8.2.

Modo heredado de utilizar iconos (antes de SPFx 1.8.2)

<i className={css('ms-Icon', 'ms-Icon--RecurringEvent')}></i>

Modo actualizado de usar iconos (después de SPFx 1.8.2)

Crear soluciones con la opción no JavaScript framework.

  1. Agregue el paquete @uifabric/styling a su package.json
  2. Realice cambios de código similar al siguiente código para insertar el icono necesario en el código:
import { getIconClassName } from '@uifabric/styling';

return `<i class="${getIconClassName('Mail')}" />`;

Crear soluciones con la opción React o con React en general.

  1. Agregue el paquete office-ui-fabric-react a su package.json, si no está ya agregado.
  2. Realice cambios de código similar al siguiente código para insertar el icono necesario en el código:
import { Icon } from 'office-ui-fabric-react/lib/Icon';

<Icon iconName='Mail' />

Vea también