2016年7月1日,星期五

Understanding the web part manifest, 束.json and other key files and folders in the SharePoint框架

新的“SharePoint Framework”客户端Web部件和客户端应用程序的模型使用了一系列文件,开发人员必须学会使用此方法成功扩展SharePoint。有一个新的Web部件清单文件(现在是JSON,而不是XML)和bundle.json,package-solution.json和upload-cdn.json之类的文件,它们与新的基于Gulp的开发人员工具进行交互以控制解决方案的方式打包并部署–全部包裹在一个新的文件夹结构中。所以那里’学习曲线并了解这些文件和文件夹至关重要。在上一篇文章中 Develop a client web part in the SharePoint框架 - a walk-through 我们看了整体“getting started” process which 使用Yeoman Generator为您创建文件 – 但是在这篇文章中’我将解释文件和文件夹。

夹s used in the SharePoint框架

让’s首先列出各个文件夹及其包含的内容。我的上一篇文章对此表进行了简化,但我在此处进行了详细说明,并添加了密钥文件和图像列表,以便您可以看到该文件夹​​的外观:

目的

关键文件

图片

src 的place where you add/edit code files –您将在此处建立文件结构。
  • [MyWebPart1.ts](TypeScript)
  • [MyWebPart1.manifest.json]
SNAGHTML72de5c5_thumb
LIB 包含“processed”准备移入与应用程序一起分发的捆绑软件中的代码文件。

例如,TypeScript文件已被编译为该目录中的JavaScript文件。
  • [MyWebPart1] .js
  • [MyWebPart2] .js
SNAGHTML72e6ac4_thumb
dist 包含the final code files which are distributed with your application.

的most 进口ant file is the final JavaScript 束 file [MyWebPart] .bundle.js–这是您Web部件的所有JS,包括一些框架内容。
  • [MyWebPart] .bundle.js
  • [MyWebPart] .bundle.js.stats.json
  • webpart.manifest.js
SNAGHTML4ed93fd_thumb
配置 包含该工具用于构建过程的一组JSON文件。特别是要控制应用程序的打包方式-使用.spapp文件,JavaScript / CSS捆绑等等。
  • build.json
  • 束.json
  • package-solution.json
  • serve.json
  • upload-cdn.json
SNAGHTML4e02bfb_thumb
node_modules 包含JavaScript 模组 used by the solution. TypeScript follows the standard set by node.js for resolving 模组 (i.e. when you use the 进口 关键字以使用在另一个模块/库中定义的对象),而node_modules文件夹是其中的关键部分。  Whatever JavaScript LIBraries your code OR the underlying SharePoint框架 has a dependency on. SNAGHTML73042df_thumb
打字 包含TypeScript类型文件– these are used to give you auto-complete (IntelliSense) against JavaScript LIBraries you are using, such as jQuery. Typings for whatever JavaScript LIBraries you’在代码中重复使用。这些通常是通过TypeScript Definition Manager添加的,例如
tsd install jQuery的 jQuery的ui --save
SNAGHTML14200135
共享点 包含.spapp文件,该文件由‘gulp包装解决方案’. This is what you’将添加到您实际环境(例如生产)的“应用程序目录”中。

也有一个‘debug’文件夹,以便您查看包装中包含的内容。
  • [MyApp] .spapp
SNAGHTML20029fca

的web part manifest

的[MyWebPart].manifest.json file is where core details such as the display name and 描述 are specified. Critically, other associations are specified here such as the associated JavaScript file (usually a 束) and any dependent JavaScript 模组 which will be loaded – yes, there’是一个内置的JS加载框架。这里’s清单.manifest.json文件中指定的一些关键属性的摘要:

元件

样本值

目的

清单版本 1 表示构建系统所期望的清单模式的版本。目前这必须是“1” –任何其他值将被拒绝。
ID 41d9c141-e10f-4373-8a24-84383fa95592 客户端Web部件的ID– the same as we’习惯,即它提供了一种识别Web部件的具体方式(例如通过API)
bootstrapModule http:// localhost:4321 / dist / cob-latestnews-wp.bundle.js

//cob.azureedge.net/intranet/cob-latestnews-wp.bundle.js
这是Web部件的JS文件所在的位置。在开发人员中,您’将会有一个本地主机路径(该工具将使用node.js为您托管)。对于生产,您’将其替换为您实际部署JS文件的路径–CDN,网站路径或类似内容。
moduleName CobLatestnewsWebPart Web部件对象的JavaScript模块名称。
localizedScripts ? 我相信这是语言环境/ JavaScript文件映射的数组–支持本地化。
preloadModules

"preLoadModules": ["jquery","jqueryui"]

Specifies JavaScript 模组 that the web part should load before execution. 的module names specified here must match names/paths specified in the “config”接下来描述的元素–换句话说,您为模块命名并指定其位置’s loaded from.
配置

"config": {
        "paths": {
            "jquery": "//code.jquery.com/jquery-1.10.2.js",
            "jqueryui": "//code.jquery.com/ui/1.11.4/jquery-ui.js"
        },
        "meta": {
            "jqueryui": {
                "scriptLoad": "true",
                "deps": [
                    "jquery"
                ]
            }
        }
    }

Used to specify 路径 to JavaScript LIBraries pre-loaded by the web part (as specified in the “preloadModules”标签)。还在此处指定了脚本之间的依赖关系-例如,在jQuery UI之前加载jQuery(如左图所示)。
属性

"properties": {
    "description": "显示当前用户的最新文档。",
    "headerText": "您最近的文件:",
    "searchQuery": "*",
    "itemLimit": "5"
  }

指定Web部件属性的默认值。请注意,Web部件属性中的其他元素在Web部件代码中定义– specifically the 接口 代表网页部分’的属性,以及 propertyPaneSettings 方法。您可以在上面的代码示例中看到这些。

请注意,清单文件中还有其他属性,’m not listing here –但是这些现在是一些重要的!

其他密钥文件“src” folder

除了Web部件清单之外,代码文件也位于此处。这些其他文件可以更容易地汇总,所以我’ll切换到项目符号点。您将在此处创建子文件夹,并根据需要构建我们的代码库。但是让’s以单个Web部件为例,并查看使用的文件集:

  • [MyWebPart] .test.ts– 将Mocha JavaScript测试添加到的文件
  • [MyWebPart] .less– 一个添加LESS CSS指令的文件。如果你’不熟悉LESS,它’一种更整洁地构造CSS的方式–它允许变量(例如@ cob-title-color:#FFB900;–然后您可以使用不同的样式)。除变量外,CSS标记可以以与HTML结构匹配的方式嵌套。这两件事使您的CSS代码更易于维护。  看到 http://lesscss.org 更多细节。
  • [MyWebPart] .strings.ts– 一个向其添加资源字符串的文件(以将其与代码分开放置,从而避免使用魔术字符串)

中的文件“lib” folder

的lib folder serves as an intermediate folder in the build system. A few things happen between the src and LIB folders:

  • 将TypeScript文件编译为JavaScript文件
  • LESS文件被编译为CSS文件 
  • 压缩CSS文件,并为CSS加载程序做准备
  • HTML模板文件已编译为JavaScript(N.B.’我仍然在努力工作!)
  • 每个.ts文件都会生成TypeScript类型文件(即“foo.d.ts”,按照TypeScript约定)

中的文件“dist” folder

这些是与应用程序一起分发的文件–其中一些在运行时使用,例如:

关键文件:

  • [MyWebPart] .bundle.js– 这是运行解决方案所需的所有JavaScript,并且对Web部件或客户端应用程序的正常工作至关重要。打包进行生产时,您可以在任意位置托管该文件(CDN,Azure Web应用程序,本地Web服务器等),但是最终用户必须可以访问该文件所在的URL。 并且必须在“bootstrapModule”键入Web部件清单。
  • [MyWebPart] .bundle.js.map– map file to support browser 调试ging
  • [MyWebPart] .manifest.js– 这是Web部件清单文件的出厂版本。
  • [MyWebPart] .bundle.js.stats.json– 包含有关生成的JS捆绑包的元数据的文件。这里真正有用的一件事是“modules”节点,其中列出了捆绑软件中所有的原始JavaScript文件。如果您真的很有用’重新排查为什么使用JavaScript库’re using isn’t making it’进入捆绑包的方式(反之亦然)–比尝试读取捆绑包本身中的丑陋的JavaScript(例如,尝试找出jQuery停止和jQuery UI开始的位置!)要容易得多。

中的文件“config” folder

的config directory holds a collection of JSON files which mainly control how the app gets packaged. 的most critical files are:

  • 束.json – this controls which JavaScript files make their way into your final JS 束. Note that by default, any 3rd party JS LIBraries you load as a module into your code (e.g. with something like 导入$ = require('jquery')) 将包含在捆绑包中。但是,您可以覆盖此设置(例如,如果您’重新引用CDN上的jQuery),方法是添加一个“exclude”具有相同名称的条目。在另一篇文章中对此有更多的了解。
  • package-solution.json– 控制由gulp包装解决方案生成的应用程序包的详细信息。这是您所用的.spapp文件’d上传到App Catalog,以在为非开发环境打包时使Web部件可用
  • upload-cdn.json– I’不确定发布时最终工具链中的格式是否会采用这种格式,但是此文件提供了一种方便的方式将文件(例如JavaScript捆绑包)推送到Azure文件存储(如果需要,还可以推送到Azure CDN)’ve 配置ured that). 的file takes parameters which IDentify your area in Azure BLOB storage so the files get uploaded to the right place, such as:
    • 帐户
    • 容器
    • accessKey

Bundle.json是一个重要文件,尤其是当您添加多个JavaScript文件并引用越来越多的外部库时。一世’我会在以后的文章中更深入地探讨这一点,但现在让我们’仅考虑几个关键点。这里 ’■当前工具中的bundle.json是什么样的:

的“entries”节点指定解决方案的元素–例如每个应放入捆绑包的JavaScript文件。值得注意的是,如果您愿意,可以将第三方JavaScript库与JS代码捆绑在一起–实际上,如果您将它们用作解决方案中的模块,则必须明确排除它们,但是’re referencing a CDN 在 run-time for example. 的key children of the “entries” element are:

元件

样本值

目的

条目 “./lib/webparts/cobLatestnewsWp/CobLatestnewsWpWebPart.js” Path to a source file to go into the JavaScript 束. 的“lib”文件夹应该包含JavaScript文件,而不是TypeScript文件–中的任何TS文件“src”文件夹被编译为JavaScript文件,这些文件将在此处输出(请考虑gulp.dest()’熟悉它)。

但是,这不是最终的 所有JavaScript文件中-这是生成到“dist” folder.
outputPath "./dist/cob-latestnews-wp.bundle.js" 整个捆绑包的最终JavaScript文件的路径。这将随您的应用程序一起分发,最终用户也会受到打击。  
排除

"@ ms / sp-client-platform",
  "jquery"

所使用的模块不应纳入捆绑包中(例如,因为您’重新引用CDN上的jQuery(例如)。

中的文件root folder

最后,我们进入根文件夹中的文件。这里有几个重要文件,例如gulpfile.js,这是构建系统的入口点– you might choose to extend this to add custom Gulp tasks. 的following list details the key files:

  • gulpfile.js – the “top”构建系统的版本,它定义了您从命令行调用的Gulp任务,例如:
    • 吞咽建立
    • 口香糖束
    • 喝一口
    • gulp包装解决方案
    • gulp上传-cdn
    • [注: Gulp任务本身在node_modules \ @ms \ ms-core-build \ tasks文件夹中定义]
  • package.json – similar to “packages.config” in NuGet, in that it defines the JavaScript LIBrary dependencies (and their versions) used by your solution.
  • tsconfig.json –定义TypeScript编译设置
  • tslint.json –定义TypeScript样式检查设置

概要

Phew! As you can see there are lots of new files and folders to get to grips with in the SharePoint框架. Remember that this information is based on an early version of the Framework, and there may be some changes by the time things actually become generally available –我将使用我发现的任何更改来更新此帖子,以保持信息的准确性。一世’ll also be covering more aspects of the SharePoint框架 in the next few articles.