相关文章推荐
心软的刺猬  ·  MySQL :: MySQL 8.0 ...·  1 年前    · 
安静的小刀  ·  java - How to avoid ...·  1 年前    · 
英俊的作业本  ·  Objective-C 排序 - ...·  1 年前    · 

你可以利用许多第三方库来生成丰富多彩的 SharePoint 框架客户端 Web 部件。 除了脚本以外,这些库通常还包含其他资产(如样式表)。 本文介绍了两种在 Web 部件中添加第三方 CSS 样式的方法,以及每种方法对生成的 Web 部件捆绑包产生的影响。 本文中的示例 Web 部件使用 jQuery 和 jQuery UI 显示可折叠项。

执行本文中的步骤前,请务必先 设置 SharePoint 客户端 Web 部件开发环境

  • 为项目新建文件夹。

    md js-thirdpartycss
    
  • 转到项目文件夹。

    cd js-thirdpartycss
    
  • 在项目文件夹中,运行 SharePoint 框架 Yeoman 生成器,为新的 SharePoint 框架项目搭建基架。

    yo @microsoft/sharepoint
    
  • 出现提示时,输入以下值:

  • 作为解决方案名称的 js thirdpartycss
  • Use the current folder 作为文件放置位置
  • No JavaScript web framework 作为生成 Web 部件的起点
  • jQuery accordion 作为 Web 部件名称
  • Shows jQuery accordion 作为 Web 部件说明
  • 在代码编辑器中,打开项目文件夹。 本文的步骤和屏幕截图中使用 Visual Studio Code,但你可以使用你喜欢的任何编辑器。

    添加测试内容

    在代码编辑器中,打开 ./src/webparts/jQueryAccordion/JQueryAccordionWebPart.ts 文件,然后将 render() 方法更改为:

    export default class JQueryAccordionWebPart extends BaseClientSideWebPart<IJQueryAccordionWebPartProps> {
      // ...
      public render(): void {
        this.domElement.innerHTML = `
            <div class="accordion">
              <h3>Information</h3>
                The Volcanoes, crags, and caves park is a scenic destination for
                many visitors each year. To ensure everyone has a good
                experience and to preserve the natural beauty, access is
                restricted based on a permit system.
                Activities include viewing active volcanoes, skiing on mountains,
                walking across lava fields, and caving (spelunking) in caves
                left behind by the lava.
              <h3>Snow permit</h3>
                The Northern region has snow in the mountains during winter.
                Purchase a snow permit for access to approved ski areas.
              <h3>Hiking permit</h3>
                The entire region has hiking trails for your enjoyment.
                Purchase a hiking permit for access to approved trails.
              <h3>Volcano access</h3>
                The volcanic region is beautiful but also dangerous. Each
                area may have restrictions based on wind and volcanic
                conditions. There are three type of permits based on activity.
                  <li>Volcano drive car pass</li>
                  <li>Lava field access permit</li>
                  <li>Caving permit</li>
          </div>`;
          ($('.accordion', this.domElement) as any).accordion();
      // ...
    

    如果立即生成项目,则会看到错误消息,提示你未定义 $。 这是因为项目引用 jQuery,而未预先加载它。 库加载方法分为两种。 两种方法都不会影响脚本在代码中的使用方式。

    方法 1:在捆绑包中添加第三方库

    在 SharePoint 框架项目中引用第三方库的最简单方法是,将库添加到生成的捆绑包中。 库会以程序包的形式进行安装,然后在项目中引用。 捆绑项目时,Webpack 会选择对库的引用,并将其添加到生成的捆绑包中。

  • 运行以下命令,安装 jQuery 和 jQuery UI:

    npm install jquery jquery-ui --save
    
  • 由于你是在 TypeScript 中生成 Web 部件,因此还需要运行以下命令,安装适用于 jQuery 的 TypeScript 键入文件:

    npm install @types/jquery --save-dev
    

    在 Web 部件中引用库

    安装库后,下一步是在项目中引用库。

  • 在代码编辑器中,打开 ./src/webparts/jQueryAccordion/JQueryAccordionWebPart.ts 文件。 在文件顶部,就在最后一个 import 语句正下方,添加对 jQuery 和 jQuery UI 的引用。

    import * as $ from 'jquery';
    require('../../../node_modules/jquery-ui/ui/widgets/accordion');
    

    由于你已为 jQuery 程序包安装了 TypeScript 键入文件,因此可以使用 import 语句引用它。 不过,jQuery UI 程序包的生成方式则不同。 与构建多少模块不同,不存在包含对所有可用组件的引用的主入口点。 相反,你需要直接引用要使用的特定组件。 相应组件的入口点包含对其正常运行所需的依赖项的全部引用。

  • 运行以下命令,确认项目是否正在生成:

    gulp serve
    
  • 将 Web 部件添加到画布后,你应该会看到可折叠项能够正常运行。

    至此,你只引用了 jQuery UI 脚本,这就是为什么可折叠项不含样式的原因所在。 接下来,添加缺少的 CSS 样式表,为可折叠项设置样式。

    在 Web 部件中引用第三方 CSS 样式表

    第三方 CSS 样式表位于项目中安装的程序包中。添加对第三方 CSS 样式表的引用与添加对程序包本身的引用一样简单。 SharePoint 框架提供对通过 Webpack 加载 CSS 文件的标准支持。

  • 在代码编辑器中,打开 ./src/webparts/jQueryAccordion/JQueryAccordionWebPart.ts 文件。 在最后一个 require 语句的正下方,添加对 jQuery UI 可折叠项 CSS文件的引用。

    require('../../../node_modules/jquery-ui/themes/base/core.css');
    require('../../../node_modules/jquery-ui/themes/base/accordion.css');
    require('../../../node_modules/jquery-ui/themes/base/theme.css');
    

    引用项目中安装的程序包中的 CSS 文件与引用 JavaScript 文件类似。 你只需指定要加载的 CSS 文件的相对路径(包括 .css 扩展名)。 捆绑项目时,Webpack 会处理这些引用,然后将这些文件添加到生成的 Web 部件捆绑包中。

  • 运行以下命令,确认项目是否正在生成:

    gulp serve
    

    应使用标准的 jQuery UI 主题正确显示可折叠项并设置其样式。

    分析生成的 Web 部件捆绑包的内容

    使用第三方库及其资源的最简单方法是,将它们添加到生成的 Web 部件捆绑包中。 若使用这种方法,Webpack 会自动解析不同库之间的全部依赖关系,并确保所有脚本以正确顺序加载。 这种方法的缺点是,引用的所有资源必须与各个 Web 部件分开加载。 因此,如果项目中有多个 Web 部件并且全都使用 jQuery UI,那么各个 Web 部件都会加载自己的 jQuery UI 副本,这就减慢了页面的加载速度。

    若要了解库对生成的 Web 部件捆绑包大小产生的影响,请在捆绑项目后,在 Web 浏览器中打开 ./temp/stats/js-thirdpartycss.stats.html 文件。 例如,将鼠标悬停在图表之上,你会看到,Web 部件引用的 jQuery UI CSS 文件占 Web 部件捆绑包总大小的 6% 还多。

    如图表下面的声明所述,大小表示捆绑包的调试版大小。 捆绑包的发行版大小明显减小。 不过,最好还是了解 Web 部件捆绑包的不同组成部分及其相较于捆绑包中其他元素的相对大小。

    方法 2:通过 URL 加载第三方库

    在 SharePoint 框架中引用第三方库的另一种方法是,通过 URL(如公用 CDN 或私有管理位置)引用库。 最大的好处是,如果你要从公共场所加载常用库,用户可能已经在其计算机上下载了特定的库。 在这种情况下,SharePoint 框架会重复使用缓存的库,从而可以加快 Web 部件的加载速度。

    即使你无法使用公用 CDN 从中央位置加载库,但从性能的角度来看,这也是很好的做法。 指向 URL 后,用户只需下载一次脚本,即可在整个门户中重复使用,大大加快了页面加载速度,并显著提升了用户体验。

    通过公用 URL 加载第三方库时,请注意使用这些库时存在的风险。 由于你不管理任何特定脚本的托管位置,因此无法确定其内容。 SharePoint 框架加载的脚本在当前用户的上下文中运行,可以完成用户可执行的所有操作。 此外,如果托管位置处于脱机状态,Web 部件就无法运行。

    添加已使用库的类型定义

    通过 URL 引用第三方库时,无需以程序包的形式将库安装在项目中。 如果你希望在开发期间进行类型安全性检查,必须安装适用于库的 TypeScript 类型定义。

    假设你是从本文前面创建的空项目入手,运行以下命令,安装适用于 jQuery 的 TypeScript 类型定义:

    npm install @types/jquery --save-dev
    

    指定库的 URL

    要通过 URL 加载第三方库,必须在项目的配置中指定库所在的 URL。 在代码编辑器中,打开 ./config/config.json 文件。 在 externals 部分中,添加以下 JSON:

    //... "externals": { //... "jquery": "https://code.jquery.com/jquery-3.1.1.min.js", "jquery-ui": "https://code.jquery.com/ui/1.12.1/jquery-ui.min.js" //... //...

    在 Web 部件中通过 URL 引用库

    至此,已指定 SharePoint 框架应用来加载 jQuery 和 jQuery UI 的 URL,下一步是在项目中引用它们。

  • 在代码编辑器中,打开 ./src/webparts/jQueryAccordion/JQueryAccordionWebPart.ts 文件。 在文件顶部,就在最后一个 import 语句的正下方,添加对 jQuery 和 jQuery UI 的以下引用:

    import * as $ from 'jquery';
    require('jquery-ui');
    

    与在你的项目中安装库为程序包时你引用两个库的方式类比,通过 URL 引用库的方式非常相似。 由于 jQuery 安装了自己的 TypeScript 类型定义,因此可使用 import 语句引用它。 对于 jQuery UI,只需在页面上加载脚本。

    由于你已在项目配置中将 jqueryjquery ui 注册为外部资源,因此在引用其中任一库时,SharePoint 框架会使用指定的 URL 在运行时加载库。 捆绑项目时,这些资源会被标记为外部资源,因此不会包含在捆绑包中。

    要注意的一个区别是,以前你指定的是从 jQuery UI 程序包加载可折叠项,而现在你是从包含所有 jQuery UI 组件的 CDN 引用 jQuery UI。

  • 运行以下命令,确认项目是否正在生成:

    gulp serve
    

    将 Web 部件添加到画布后,你应该会看到可折叠项能够正常运行。

  • 在 Web 浏览器中,打开开发者工具,切换到显示网络请求的选项卡,然后重新加载页面。 你应用会看到 jQuery 和 jQuery UI 是如何从 CDN 加载的。

    至此,你只引用了 jQuery UI 脚本,这就是为什么可折叠项不含样式的原因所在。 接下来,添加缺少的 CSS 样式表,为可折叠项设置样式。

    在 Web 部件中通过 URL 引用第三方 CSS 样式表

    通过 URL 添加对第三方 CSS 样式表的引用不同于从项目程序包引用资源。 虽然 config.json 文件中的项目配置允许你指定外部资源,但这仅适用于脚本。 若要通过 URL 引用 CSS 样式表,必须改用 SPComponentLoader

    使用 SPComponentLoader 通过 URL 加载 CSS

  • 在代码编辑器中,打开 ./src/webparts/jQueryAccordion/JQueryAccordionWebPart.ts 文件。 在文件顶部,紧接着最后一个 import 语句,添加以下代码:

    import { SPComponentLoader } from '@microsoft/sp-loader';
    
  • 在同一文件中重写 onInit() 方法,如下所示:

    export default class JQueryAccordionWebPart extends BaseClientSideWebPart<IJQueryAccordionWebPartProps> {
      protected onInit(): Promise<void> {
        SPComponentLoader.loadCss('https://code.jquery.com/ui/1.12.1/themes/base/jquery-ui.min.css');
        return super.onInit();
      // ...
    

    当 Web 部件在页面上实例化后,它会通过指定的 URL 加载 jQuery UI CSS。 此 CSS 样式表是组合优化版 jQuery UI CSS,其中包含所有组件的基本样式、主题和样式设置。

  • 运行以下命令,确认项目是否正在生成:

    gulp serve
    

    应使用标准的 jQuery UI 主题正确显示可折叠项并设置其样式。

    分析生成的 Web 部件捆绑包(通过 URL 加载资源)的内容

    在 Web 浏览器中生成项目后,打开 ./temp/stats/js-thirdpartycss.stats.html 文件。

    注意:捆绑包总大小明显减小(在此方法中,总大小为 7 KB,而在将 jQuery 和 jQuery UI 添加到捆绑包中时,总大小超过 300 KB),图表中未列出 jQuery 和 jQuery UI,因为它们是在运行时加载。

  • SharePoint 框架概述
  •