生成首个 SharePoint 框架扩展(Hello World 第 1 部分)Build your first SharePoint Framework Extension (Hello World part 1)

SharePoint Framework (SPFx) 扩展是运行在 SharePoint 页面的上下文中的客户端组件。可以将扩展部署到 SharePoint Online,并可以使用新式 JavaScript 工具和库生成它们。SharePoint Framework (SPFx) Extensions are client-side components that run inside the context of a SharePoint page. You can deploy extensions to SharePoint Online, and you can use modern JavaScript tools and libraries to build them.

也可以观看 SharePoint PnP YouTube 频道上的这段视频,按照本文中的步骤操作:You can also follow the steps in this article by watching the video on the SharePoint PnP YouTube Channel:



创建扩展项目Create an extension project

  1. 在最喜爱的位置创建新的项目目录。Create a new project directory in your favorite location.

    md app-extension
    
  2. 转到项目目录。Go to the project directory.

    cd app-extension
    
  3. 通过运行 Yeoman SharePoint 生成器创建新的 HelloWorld 扩展。Create a new HelloWorld extension by running the Yeoman SharePoint Generator.

    yo @microsoft/sharepoint
    
  4. 当出现提示时:When prompted:

    • 接受默认的“app-extension”**** 作为解决方案名称,并按 Enter。Accept the default app-extension as your solution name, and select Enter.
    • 选择“仅限 SharePoint Online (最新)”****,并按 Enter。Select SharePoint Online only (latest), and select Enter.
    • 选择“使用当前文件夹”****,然后按 EnterSelect Use the current folder, and select Enter.
    • 选择“N”**** 以允许将解决方案立即部署到所有网站。Select N to allow solution to be deployed to all sites immediately.
    • 在解决方案是否包含独有权限的问题上选择“N”****。Select N on the question if solution contains unique permissions.
    • 选择“扩展”**** 作为要创建的客户端组件类型。Select Extension as the client-side component type to be created.
    • 选择“应用自定义工具”**** 作为要创建的扩展类型。Select Application Customizer as the extension type to be created.
  5. 接下来的一组提示要求提供扩展的具体信息:The next set of prompts ask for specific information about your extension. 当出现提示时:When prompted:

    • 接受默认的“HelloWorld”**** 作为扩展名称,并按 Enter。Accept the default HelloWorld as your extension name, and select Enter.
    • 接受默认的“HelloWorld 说明”**** 作为扩展说明,并按 Enter。Accept the default HelloWorld description as your extension description, and select Enter.

    Yeoman SharePoint 生成器提示创建扩展解决方案

    备注

    如果为扩展命名的名称过长,可能会遇到问题。If you use a name for the extension that is too long, you might encounter issues. 所提供的项是用于生成应用自定义工具清单 JSON 文件的别名项。The entries provided are used to generate an alias entry for the Application Customizer manifest JSON file. 如果别名长度超过 40 个字符,可能会在尝试使用 gulp serve --nobrowser 提供扩展时遇到异常。If the alias is longer than 40 characters, you get an exception when you try to serve the extension by using gulp serve --nobrowser. 接下来,可以通过更新别名项来解决此问题。You can resolve this by updating the alias entry afterward.

    此时,Yeoman 安装必需的依赖项,并为解决方案文件和“HelloWorld”**** 扩展搭建基架。At this point, Yeoman installs the required dependencies and scaffolds the solution files along with the HelloWorld extension. 这可能需要几分钟的时间。This might take a few minutes.

    基架完成后,应该可以看到指示成功搭建基架的以下消息:When the scaffold is complete, you should see the following message indicating a successful scaffold:

    SharePoint 客户端解决方案成功搭建基架

    有关任何错误故障排除的信息,请参阅已知问题For information about troubleshooting any errors, see Known issues.

  6. 接下来,在控制台中键入下面的命令,以启动 Visual Studio Code。Next, type the following into the console to start Visual Studio Code.

    code .
    

    备注

    由于 SharePoint 客户端解决方案基于 HTML/TypeScript,因此可使用任何支持客户端开发的代码编辑器来生成扩展。Because the SharePoint client-side solution is HTML/TypeScript based, you can use any code editor that supports client-side development to build your extension.

    请注意默认解决方案结构与客户端 Web 部件的解决方案结构的类似程度。这是基本的 SharePoint Framework 解决方案结构,具有跨所有解决方案类型的类似配置选项。Notice how the default solution structure looks like the solution structure for client-side web parts. This is the basic SharePoint Framework solution structure, with similar configuration options across all solution types.

    初始基架搭建完成后打开的 SharePoint Framework 解决方案

  7. 打开 src\extensions\helloWorld 文件夹中的 HelloWorldApplicationCustomizer.manifest.jsonOpen HelloWorldApplicationCustomizer.manifest.json in the src\extensions\helloWorld folder.

    此文件定义扩展类型和扩展的唯一标识符。稍后在调试扩展并将其部署到 SharePoint 时将需要此 ID。This file defines your extension type and a unique identifier for your extension. You’ll need this ID later when you debug and deploy your extension to SharePoint.

    应用自定义工具清单 json 内容

对应用自定义工具编码Code your Application Customizer

打开 src\extensions\helloWorld 文件夹中的 HelloWorldApplicationCustomizer.manifest.json 文件。Open the HelloWorldApplicationCustomizer.ts file in the src\extensions\helloWorld folder.

请注意,应用程序定制器的基类从 sp-application-base 程序包中导入,其中包含应用程序定制器所需的 SharePoint Framework 代码。Notice that base class for the Application Customizer is imported from the sp-application-base package, which contains SharePoint framework code required by the Application Customizer.

从 @microsoft/sp-application-base 导入 BaseApplicationCustomizer 的语句

应用自定义工具的逻辑包含在 onInit 方法中。当客户端扩展在页面上首次激活时,此方法获得调用。The logic for your Application Customizer is contained in the onInit method, which is called when the client-side extension is first activated on the page. 此事件在 this.contextthis.properties 分配后发生。This event occurs after this.context and this.properties are assigned. 与 Web 部件一样,onInit() 返回可用于执行异步操作的承诺。As with web parts, onInit() returns a promise that you can use to perform asynchronous operations.

备注

如果未定义 this.contextthis.properties,那么在早期阶段调用的是类构造函数。此时,不支持自定义启动逻辑。The class constructor is called at an early stage, when this.context and this.properties are undefined. Custom initiation logic is not supported here.

以下是默认解决方案中的 onInit() 的内容。此默认解决方案将日志写入开发仪表板,然后在页面呈现时显示简单的 JavaScript 警报。The following are the contents of onInit() in the default solution. This default solution writes a log to the Dev Dashboard, and then displays a simple JavaScript alert when the page renders.

代码中的默认 onInit 方法

备注

SharePoint 框架开发人员仪表板是一个附加的 UI 仪表板,可以通过 ctrl+F12 开始使用。SharePoint Framework Dev Dashboard is additional UI dashboard, which can be started with ctrl+F12. 这是面向开发人员的日志记录信息,可以以开发人员的身份利用这些信息。This is developer oriented logging information, which you can take advantage as developer. 此外,它还有大量的 oob 日志记录。It also has plenty of oob logging in it.

如果用程序定制器使用 ClientSideComponentProperties JSON 输入,它会反序列化为 BaseExtension.properties 对象。If your Application Customizer uses the ClientSideComponentProperties JSON input, it is deserialized into the BaseExtension.properties object. 可以定义用于描述它的接口。You can define an interface to describe it. 默认模板在寻找的是 testMessage 属性。The default template is looking for a property called testMessage. 如果提供了此属性,那么模板会在警报消息中输出它。If that property is provided, it outputs it in an alert message.

调试应用程序定制器Debug your Application Customizer

不能使用本地工作台测试 SharePoint 框架扩展。You cannot use the local Workbench to test SharePoint Framework Extensions. 需要针对实际 SharePoint Online 网站测试这些扩展。You need to test them against a live SharePoint Online site. 但是,无需为此将自定义部署到应用程序目录中,这样可以简化调试体验并提高效率。You don't have to however deploy your customization to the app catalog to do this, which makes the debugging experience simple and efficient.

  1. 打开 config 文件夹中的 serve.json 文件。Open the serve.json file in the config folder.

    注意,已经使用与项目匹配的默认设置对此文件进行了更新。Notice that this file has been updated with the default settings matching your project. 可以注意到,customActions 元素下提到了一个特定 GUID。You can notice that there's a specific GUID mentioned under the customActions element. 当项目为基架时,它会自动更新以匹配组件。This is automatically updated to match your component when project was scaffold. 如果要添加新组件或更改组件属性,则需要更新此文件以进行测试。If you will add new components or change the properties for the component, you will need to update this file for testing.

  2. 更新 pageURL 以匹配你自己要用于测试的租户。Update pageURL to match your own tenant, which you want to use for testing. 可以使用任何具有新式体验的 URL。You can use any URL with modern experience. 例如,这可能是一个新组关联的团队网站的欢迎页面,意味着以下 URL 之类的内容:This could be for example a welcome page of a new group associated team site, which would mean something like the following URL:

    https://sppnp.sharepoint.com/sites/yoursite/SitePages/Home.aspx

    serve.json 文件应如下所示(已使用租户详细信息进行更新):Your serve.json file should look similar to the following (updated with your tenant details):

    已更新的 server json 文件

  3. 切换到控制台,并确保仍位于 app-extension 目录中,然后输入以下命令:Switch to your console, ensure that you are still in the app-extension directory, and then enter the following command:

    备注

    只能在开发环境中安装一次开发人员证书,因此,如果已在环境中执行此操作,则可以跳过该步骤。Developer certificate has to be installed ONLY once in your development environment, so you can skip this step, if you have already executed that in your environment.

    gulp trust-dev-cert
    
  4. 通过运行以下命令来编译代码,并通过本地计算机托管编译后的文件:Compile your code and host the compiled files from your local computer by running the following command:

    gulp serve
    

    备注

    如果没有安装 SPFx 开发人员证书,Workbench 会发出通知,指明它未被配置为通过 localhost 加载脚本。If you do not have the SPFx developer certificate installed, Workbench notifies you that it is not configured to load scripts from localhost. 如果发生这种情况,请在控制台窗口中停止当前正在运行的进程,在项目目录控制台中运行 gulp trust-dev-cert 命令以安装开发人员证书,然后再次运行 gulp serve --nobrowser 命令。If this happens, stop the process that is currently running in the console window, run the gulp trust-dev-cert command in your project directory console to install the developer certificate, and then run the gulp serve --nobrowser command again. 设置开发环境一文中记录了此过程。This process is documented in the Set up your development environment article.

    当代码编译没有任何错误,它将提供来自 https://localhost:4321 的生成清单,并使用所需的查询参数启动默认浏览器。When the code compiles without errors, it serves the resulting manifest from https://localhost:4321 and also starts your default browser with needed query parameters.

    Gulp serve

  5. 移动到浏览器并选择“加载调试脚本”****,继续从本地主机加载脚本。Move to your browser and select Load debug scripts to continue loading scripts from your local host.

    页面中显示的“允许调试清单?”问题


    现在会在页面上看到对话框消息。You should now see the dialog message on your page.

    Hello as property 警报消息

    此对话框由 SharePoint 框架扩展抛出。This dialog is thrown by your SharePoint Framework Extension. 请注意,由于在调试查询参数中提供了 testMessage 属性,因此警报消息中有它。Note that because you provided the testMessage property as part of the debug query parameters, it's included in the alert message. 可以根据客户端组件属性来配置扩展实例,这些属性是在运行时模式下为实例传递的。You can configure your extension instances based on the client component properties, which are passed for the instance in runtime mode.

备注

如果遇到调试问题,请仔细检查 serve.json 文件中的 pageUrl 设置。If you have issues with debugging, double-check the pageUrl setting in the serve.json file.

后续步骤Next steps

恭喜!已成功运行首个 SharePoint 框架扩展!Congratulations, you got your first SharePoint Framework Extension running!

若要继续生成扩展,请参阅使用应用自定义工具中的页面占位符(Hello World 第 2 部分)To continue building out your extension, see Using page placeholders from Application Customizer (Hello World part 2). 将使用同一项目,并利用特定内容占位符来修改 SharePoint UI。You use the same project and take advantage of specific content placeholders for modifying the UI of SharePoint. 请注意,gulp serve 命令仍在控制台窗口或 Visual Studio Code(如果使用的是此编辑器)中运行。Notice that the gulp serve command is still running in your console window (or in Visual Studio Code if you are using the editor). 浏览下一篇文章时,可以继续让它运行。You can continue to let it run while you go to the next article.

备注

如果发现本文档或 SharePoint Framework 有问题,请使用 sp-dev-docs 存储库上的问题列表或向本文添加注释,向 SharePoint 工程团队报告问题。If you find an issue in the documentation or in the SharePoint Framework, please report that to SharePoint engineering by using the issue list at the sp-dev-docs repository or by adding a comment to this article. 提前感谢读者提供反馈意见。Thanks for your input in advance.