Cadena de herramientas de SharePoint Framework
La cadena de herramientas de SharePoint Framework es el conjunto de herramientas de compilación, paquetes de marcos y otros elementos que administran la compilación e implementación de los proyectos del lado cliente.
La cadena de herramientas:
- Le ayuda a compilar componentes del lado cliente, como los elementos web.
- Le ayuda a probar estos componentes en su entorno de desarrollo local con herramientas como SharePoint Workbench.
- Le permite empaquetarlo e implementarlo en SharePoint.
- Le proporciona un conjunto de comandos de compilación que le ayudan a completar tareas de compilación clave, tales como compilar el código, empaquetar el proyecto del lado cliente en un paquete de aplicación de SharePoint y mucho más.
Importante
El área de trabajo local no admite el uso de Internet Explorer 11.
Usar paquetes de npm
Antes de profundizar en los diversos componentes de la cadena de herramientas, es importante comprender cómo usa SharePoint Framework npm para administrar los diferentes módulos del proyecto. npm es uno de los administradores de paquetes de fuente abierta preferidos para el desarrollo en el lado del cliente JavaScript.
Un paquete de npm habitual consta de uno o varios archivos de código JavaScript reutilizables, denominados módulos, junto con una lista de paquetes de dependencia. Al instalar el paquete, npm también instala esas dependencias.
El registro de npm oficial consta de cientos de paquetes que puede descargar para compilar la aplicación. También puede publicar sus propios paquetes en npm y compartirlos con otros desarrolladores. SharePoint Framework usa algunos de los paquetes de npm en la cadena de herramientas y también publica sus propios paquetes en el registro de npm.
Paquetes de SharePoint Framework
SharePoint Framework consta de varios paquetes de npm que funcionan conjuntamente para ayudar a compilar experiencias del lado del cliente en SharePoint.
Los siguientes paquetes de npm están en SharePoint Framework:
- @microsoft/generator-sharepoint. Un complemento de Yeoman para usar con SharePoint Framework. Con este generador, los desarrolladores pueden configurar rápidamente un nuevo proyecto de elementos web del lado cliente con procedimientos recomendados y valores predeterminados razonables.
- @microsoft/sp-client-base. Define las bibliotecas principales de las aplicaciones del lado cliente creadas mediante SharePoint Framework.
- @microsoft/sp-webpart-workbench. SharePoint Workbench es un entorno independiente para probar y depurar elementos web del lado cliente.
- @microsoft/sp-module-loader. Un cargador de módulos que administra el control de versiones y la carga de componentes, elementos web y otros activos del lado cliente. También proporciona servicios de diagnóstico básicos. Se basa en estándares conocidos como SystemJS y Webpack, y es la primera parte de SharePoint Framework que se carga en una página.
- @microsoft/sp-module-interfaces. Define varias interfaces de módulos que comparte el cargador de módulos de SharePoint Framework y también el sistema de compilación.
- @microsoft/sp-lodash-subset. Proporciona una agrupación personalizada de lodash para usar con el cargador de módulos de SharePoint Framework. Para mejorar el rendimiento del tiempo de ejecución, solo incluye un subconjunto de las funciones de lodash más esenciales.
- @microsoft/sp-tslint-rules. Define las reglas de tslint personalizadas para usarlas con proyectos del lado cliente de SharePoint.
- @microsoft/office-ui-fabric-react-bundle. Proporciona una agrupación personalizada de office-ui-fabric-react que está optimizada para usar con el cargador de módulos de SharePoint Framework.
Paquetes de herramientas de compilación comunes
Junto con los paquetes de SharePoint Framework, también se usa un conjunto común de herramientas de compilación para realizar tareas de compilación, como compilar código TypeScript a JavaScript y convertir SCSS a CSS.
Los siguientes paquetes de herramientas de compilación de npm comunes están en SharePoint Framework:
- @microsoft/sp-build-core-tasks. Una colección de tareas del sistema de compilación de SharePoint Framework, que se basa en Gulp. El paquete sp-build-core-tasks implementa operaciones específicas de SharePoint, como empaquetar soluciones y escribir manifiestos.
- @microsoft/sp-build-web. Importa y configura un conjunto de tareas de compilación que son adecuadas para un destino de compilación que se ejecuta en un explorador web (en lugar de un entorno de Node.js). Este paquete está pensado para importarse directamente mediante un archivo de Gulp que usa el sistema de compilación de SharePoint Framework.
- @microsoft/gulp-core-build. Las tareas de compilación principales de Gulp para compilar TypeScript, HTML, LESS y otros formatos de compilación. Este paquete depende de otros paquetes de npm que contienen las siguientes tareas:
- @microsoft/gulp-core-build-typescript
- @microsoft/gulp-core-build-sass
- @microsoft/gulp-core-build-webpack
- @microsoft/gulp-core-build-serve
- @microsoft/gulp-core-build-karma
- @microsoft/gulp-core-build-mocha@microsoft/loader-cased-file. Un contenedor de file-loader del paquete web que se puede usar para modificar el uso de mayúsculas y minúsculas del nombre de archivo resultante. Esto es útil en algunas situaciones, como cuando se usa una red de entrega de contenido (CDN) que solo permite nombres de archivo en minúsculas.
- @microsoft/loader-load-themed-styles. Un cargador que encapsula la carga de CSS en un script equivalente a
require('load-themed-styles').loadStyles( /* css text */ ). Está diseñado como reemplazo de style-loader. - @microsoft/loader-raw-script. Un cargador que carga el contenido de un archivo de script directamente en una agrupación de paquetes web mediante
eval(…). - @microsoft/loader-set-webpack-public-path. Un cargador que establece la variable webpack_public_path en un valor especificado en los argumentos, que se agrega opcionalmente a la propiedad SystemJS baseURL.
Scaffolding de un nuevo proyecto del lado cliente
El generador de SharePoint aplica scaffolding a un proyecto del lado cliente con un elemento web. El generador también descarga y configura los componentes de la cadena de herramientas necesarios para el proyecto del lado cliente especificado.
Instalar paquetes de npm
El generador instala los paquetes de npm necesarios de forma local en la carpeta del proyecto. npm le permite instalar un paquete de forma local en un proyecto o de forma global. Ambos métodos tienen ventajas, pero las instrucciones generales indican que se instalen los paquetes de npm de forma local si el código depende de los módulos de esos paquetes. En el caso de un proyecto de elementos web, el código del elemento web depende de los diferentes paquetes comunes de compilación y SharePoint y, por tanto, requiere que estos paquetes se instalen de forma local.
Al instalar los paquetes de forma local, npm también instala las dependencias asociadas a cada paquete. Puede encontrar los paquetes instalados en la carpeta node_modules de la carpeta del proyecto. Esta carpeta contiene los paquetes junto con todas sus dependencias. Esta carpeta contiene entre decenas y cientos de carpetas, ya que los paquetes de npm se dividen siempre en módulos más pequeños y, por tanto, se instalan entre decenas y cientos de paquetes. Los paquetes de SharePoint Framework clave se encuentran en la carpeta node_modules@microsoft. El @microsoft es un ámbito npm que representa colectivamente los paquetes publicados por Microsoft.
Cada vez que cree un nuevo proyecto mediante el generador, este instala los paquetes de SharePoint Framework junto con sus dependencias para ese proyecto específico de forma local. De este modo, npm facilita la administración de los proyectos de elementos web sin afectar a otros proyectos en el entorno de desarrollo local.
Especificar dependencias con package.json
El archivo package.json del proyecto del lado cliente especifica la lista de dependencias de las que depende el proyecto. La lista define qué dependencias se instalarán. Como se ha descrito anteriormente, cada dependencia puede contener varias. npm le permite definir las dependencias en tiempo de ejecución y compilación para el paquete mediante las propiedades dependencies y devDependencies. Puede usar la propiedad devDependencies si quiere usar ese módulo en el código, como en el caso de compilar elementos web.
A continuación se encuentra el package.json de helloworld-webpart.
{
"name": "helloword-webpart",
"version": "0.0.1",
"private": true,
"engines": {
"node": ">=0.10.0"
},
"dependencies": {
"@microsoft/sp-client-base": "~1.0.0",
"@microsoft/sp-core-library": "~1.0.0",
"@microsoft/sp-webpart-base": "~1.0.0",
"@types/webpack-env": ">=1.12.1 <1.14.0"
},
"devDependencies": {
"@microsoft/sp-build-web": "~1.0.0",
"@microsoft/sp-module-interfaces": "~1.0.0",
"@microsoft/sp-webpart-workbench": "~1.0.0",
"gulp": "~3.9.1",
"@types/chai": ">=3.4.34 <3.6.0",
"@types/mocha": ">=2.2.33 <2.6.0"
},
"scripts": {
"build": "gulp bundle",
"clean": "gulp clean",
"test": "gulp test"
}
}
Aunque hay muchos paquetes instalados para el proyecto, estos son necesarios solo para compilar el elemento web en el entorno de desarrollo. Con la ayuda de estos paquetes, puede depender de los módulos, compilar y empaquetar el elemento web para la implementación. La última versión agrupada reducida del elemento web que implementa en un servidor CDN o SharePoint no incluye ninguno de estos paquetes. Ahora bien, también puede configurarlo para que incluya algunos módulos, según sus requisitos. Para obtener más información, consulte Agregar una biblioteca externa a su elemento web.
Trabajar con sistemas de control de origen
A medida que aumentan las dependencias del proyecto, también aumenta el número de paquetes que se instalarán. No necesita insertar en el repositorio la carpeta node_modules, que contiene todas las dependencias, en el sistema de control de origen. Debe excluir node_modules de la lista de archivos que se omitirán durante las inserciones en el repositorio.
Si usa git como el sistema de control de origen, el proyecto de elementos web de Yeoman con scaffolding incluye un archivo .gitignore que excluye la carpeta node_modules, entre otras cosas.
La primera vez que extraiga del repositorio o clone el proyecto de elementos web del sistema de control de origen, ejecute el comando para inicializar e instalar de forma local todas las dependencias del proyecto:
npm install
Después de ejecutar el comando, npm examina el archivo package.json e instala las dependencias necesarias.
Actualización de la información del desarrollador
A partir de la versión 1.11, el manifiesto de solución definido en el archivo package-solution.json se ha ampliado con la sección developer que le permite almacenar información adicional sobre su organización. La información de esta sección se valida cuando publica su solución en el marketplace. Incluso si va a crear una solución para uso interno, se recomienda que rellene las distintas propiedades en el manifiesto de la solución. Si especifica esta información, en el futuro podrá acceder a información adicional sobre el uso de su aplicación.
Importante
Si elige exponer sus elementos web en Microsoft Teams, los usuarios verán la información de la sección developer al instalar su aplicación en Teams.
Importante
La sección del desarrollador debe contener información válida para cualquier solución de SharePoint Framework que estará disponible en la tienda de Office o en AppSource.
Las propiedades siguientes están disponibles como parte de la sección developer:
| Atributo | Description | Obligatoria |
|---|---|---|
name |
Nombre de la organización que creó la aplicación | Sí |
websiteUrl |
Dirección URL de un sitio web con información adicional sobre la aplicación | Sí |
mpnId |
Id. de red de Microsoft Partner (más detalles en MS Partner Network) | No (pero muy recomendado) |
privacyUrl |
Dirección URL de la declaración de privacidad | Sí |
termsOfUseUrl |
Dirección URL de las condiciones de uso | Sí |
Tareas de compilación
SharePoint Framework usa gulp como ejecutador de tares para tratar los proceso de la siguiente forma:
- Empaquetar y reducir archivos JavaScript y CSS.
- Ejecute herramientas para llamar a las tareas de reducción y agrupación antes de cada compilación.
- Compile los archivos LESS o SASS en CSS.
- Compilar archivos TypeScript en JavaScript.
La cadena de herramientas consta de las siguientes tareas de Gulp definidas en el paquete @microsoft/sp-build-core-tasks:
- build: compila el proyecto de la solución del lado cliente.
- bundle: empaqueta el punto de entrada del proyecto de solución del lado cliente y todas sus dependencias en un solo archivo de JavaScript.
- serve: proporciona el proyecto de solución del lado cliente y los activos de la máquina local.
- clean: limpia los artefactos de compilación del proyecto de solución del lado cliente de la compilación anterior y de los directorios de destino de compilación (lib y dist).
- test: ejecuta las pruebas unitarias, si están disponibles, del proyecto de solución del lado cliente.
- package-solution: empaqueta la solución del lado cliente en un paquete de SharePoint.
- deploy-azure-storage: implementa activos de proyecto de solución del lado cliente en Azure Storage.
Para iniciar las diferentes tareas, anexe el nombre de la tarea con el comando de Gulp. Por ejemplo, para compilar y después previsualizar el elemento web en SharePoint Workbench, ejecute el comando siguiente:
gulp serve
Nota:
No puede ejecutar varias tareas al mismo tiempo.
La tarea serve ejecuta las diferentes tareas y finalmente inicia SharePoint Workbench.
Compilar destinos
En la captura de pantalla anterior, puede ver que la tarea indica el destino de compilación de la siguiente forma:
Build target: DEBUG
Si no se especifica ningún parámetro, los comandos se dirigen al modo BUILD. Si se especifica el parámetro ship, los comandos se dirigen al modo SHIP.
Normalmente, cuando el proyecto de elementos web está listo para enviar o implementar en un servidor de producción, se dirige a SHIP. Para otros escenarios, como pruebas y depuración, se dirigiría a BUILD. El destino SHIP también garantiza que se compile la versión reducida de la agrupación de elementos web.
Para dirigirse al modo SHIP, anexe la tarea con --ship:
gulp --ship
En el modo DEBUG, las tareas de compilación copian todos los activos de elementos web, incluida la agrupación de elementos web, en la carpeta dist.
En el modo SHIP, las tareas de compilación copian todos los activos de elementos web, incluida la agrupación de elementos web, en la carpeta temp\deploy.