通过

使用 JavaScript 对象模型 (JSOM) 开发Project Online加载项

本文介绍Microsoft Project Online外接程序开发，以增强Project Online体验。 开发项目作为演练实现。 用于本文的加载项从Project Online帐户读取和显示已发布项目的项目名称和 ID，并允许向下钻取以检索与单个项目关联的任务。

在运行时，加载项列表类似于下图：

显示 JSOM 项目和任务列表的屏幕截图

本示例的重点是与Project Online交互，为来自服务的每个请求创建查询和设置上下文。 用户界面 (UI) 元素受到最少的关注。 相反，源列表提供了有关 UI 的注释。

注意

示例外接程序（Visual Studio 项目）的源文件位于： https://github.com/OfficeDev/Project-JSOM-List-Projects-Tasks..... 在阅读本文时，请保持源文件方便作为参考，因为每个源文件都是相互补充的。 Visual Studio 项目中生成的 和 文件是可执行的，只需极少的更改 - 将Project Online租户的 URL 替换为 PWA 文件夹。

背景

Project Online是一项Office 365服务，为公司提供项目组合管理 (PPM) 和项目管理办公室， (PMO) 解决方案来协调和管理项目组合、计划和项目。 Project Online产品/服务与 Project 桌面版不同;但是，Project Online仍包含用于在项目整个生命周期内维护和跟踪项目详细信息的功能。 Project Online基于 SharePoint Online 构建。

Project Online托管加载项由与 Client-Side-Object-Model API 交互的 JavaScript 和资源文件组成。 当用户访问加载项时，JavaScript 和资源在浏览器中下载并执行。 加载项对Project Online进行异步调用，以便与服务交互，无论是创建、检索、更新还是删除数据。

Project Online再执行一项操作来保护外接程序中属于其他租户的信息;即，Project Online创建一个独立站点来与来自外接程序的请求进行交互。 Project Online主机上不运行任何自定义代码。

Project Online加载项的开发设置使用 Visual Studio SharePoint 外接程序项目类型。 外接程序是用 JavaScript 编写的，它使用 Project JavaScript 对象模型 (JSOM) 与 Project Online 服务交互。 JSOM 从 SharePoint JSOM 继承其大部分功能。

注意

加载项可以在 Office 应用商店中发布和销售，也可以部署到 SharePoint 上的专用应用程序目录。 有关详细信息，请参阅 部署和发布 Office 外接程序。

本文中使用的加载项是面向开发人员的示例：它不适用于生产环境。 主要目的是显示Project Online的应用开发示例。

先决条件

将以下项添加到受支持的 Windows 环境：

注意

标准.NET Framework是要使用的正确框架。 请勿使用“.NET Framework 4 客户端配置文件”。

设置 Visual Studio 项目

应用程序设置包括创建新项目、链接相应的库和声明所需的命名空间。 Visual Studio 提供有多种类型的开发项目。 本部分内容简短且非常基本。 值是将信息合并到一个位置。

选择 Visual Studio 项目

若要为加载项创建适当类型的项目，必须执行以下步骤。 屏幕上遇到的关键字具有 粗体 属性：

  1. 在“文件”菜单中，选择“ 文件>新建>项目”。

  2. 在左窗格中的“已安装模板”中，选择“ C#>Office/SharePoint>Web 外接程序”。

  3. 在中央窗格顶部，选择.NET Framework 4 或更高版本;当前版本为 4.6。

  4. 在中央窗格中的应用程序类型中，选择 “SharePoint 外接程序”。

  5. 在底部为项目指定名称和位置以及解决方案名称。

  6. 此外，在底部选中“创建解决方案的目录”复选框。

  7. 单击“确定”以创建初始项目。

Visual Studio 向导会询问一些有关Project Online设置网站的后续问题， (在随后的几个对话框中) 名为 SharePoint 设置。 下面是问题：

  1. 要使用哪个 SharePoint 网站来调试加载项？ 指定 PWA 网站的 URL，例如 https://contoso.sharepoint.com/sites/pwa。

  2. 希望如何托管 SharePoint 外接程序？ 选择 [X] SharePoint-hosted。

    有关 SharePoint 外接程序的详细信息（包括托管选项），请参阅 SharePoint 外接程序。

  3. 单击下一个。

第二个附加对话框要求你指定加载项的 SharePoint Online 版本：

  1. 您希望外接程序面向的 SharePoint 的最早版本是什么？ 选择 [X] S harePoint-Online。

  2. 单击“完成”。

Visual Studio 创建项目并访问Project Online网站。

在Project Online站点上启用旁加载

旁加载是测试和调试Project Online加载项的机制。需要两个脚本进行旁加载：一个用于在Project Online站点上启用旁加载，另一个用于在完成加载项测试和调试后禁用旁加载。

有关设置旁加载的详细信息，请参阅 在非开发人员网站集中启用应用 SideLoading。

注意

旁加载应用是一项开发人员/测试功能。 它 不适用于生产用途。 不要定期旁加载应用，或使应用旁加载的启用时间比使用该功能的时间长。

将内容添加到外接程序项目

创建项目并设置调试机制后，向应用添加内容包括以下任务：

  • 设置应用程序范围

  • 链接 JSOM 库

  • 将 UI 元素添加到外接程序

  • 初始化并连接到 Project Online 服务

  • 检索项目和详细信息/属性

  • 显示项目

  • 显示项目的任务

外接程序项目包含许多文件。 在此示例中，需要编辑以下文件：

  • AppManifest.xml

  • Default.aspx

  • App.js

  • App.css - 可选;包含为加载项开发的样式定义

如果Project Online租户发生更改（例如从试用版迁移到订阅网站），则可以使用“查看>属性窗口”命令提供的“属性窗口”更新项目属性，包括“服务器连接”和“站点 URL”。

还可以向项目添加文件。 如果是这样，则需要更新位于同一组中的 Elements.xml 文件， (内容、图像、页面或脚本) 以包含新文件。 有关项目文件的详细信息，请参阅 浏览应用程序清单结构和 SharePoint 外接程序的包。

设置应用程序范围

外接程序需要服务在查询结果中返回信息之前定义的范围或权限级别。 对于此外接程序，请对 Visual Studio 项目使用以下范围。 此更改对“权限”选项卡中的 AppManifest.xml 文件进行：

范围 权限
多个项目 (Project Server)
阅读

设置应用程序范围后保存文件。 否则，不会从服务返回任何数据。

运行时Project Online库（PS.js 和 PS.debug.js）由 Project Online 提供，并且始终是最新版本。 使用 JSOM 的 JavaScript 加载项必须与其中一个库链接。 链接定义将添加到 Default.aspx 文件中。 使用 PS.js 和/或 PS.debug.js 的命令是位于 App.js 文件中的代码的一部分。

sp.js 的“SharePoint：ScriptLink”后面的元素中添加 <asp:Content ContentPlaceHolderID="PlaceHolderAdditionalPageHead" 以下命令，用于 PS.js 或 PS.debug.js 定义。

<SharePoint:ScriptLink name="PS.js" runat="server" OnDemand="false" LoadAfterUI="true" Localizable="false" />

注意

PS.js 或 PS.debug.js 的 OnDemand 属性设置为 false。

将 UI 元素添加到外接程序

示例加载项由几个组件组成。 静态元素说明位于 Default.aspx 文件中。 所有组件的动态元素说明和代码位于 App.js 文件中。 有关组件的注释，请参阅源代码列表。 下面是加载项中的 UI 组件列表：

  • Title

  • 介绍性谓词

  • 用于从表中删除任务的按钮

  • 列出项目 ID、名称以及任务信息的表。

  • 将任务数据导入表中的每个项目) (克隆一次任务按钮。

有关用户界面的详细信息（如项目表的标题和标题部分），请参阅Default.aspx项目文件。

初始化并连接到主机系统

App.js 文件包含 JavaScript 代码。 加载项在浏览器中加载 PS.js，然后调用 initializePage 函数。 InitializePage 检索Project Online终结点的上下文，并启动 loadProjects 函数。

    'use strict';
    SP.SOD.executeOrDelayUntilScriptLoaded(initializePage, "PS.js");
    //Project PWA Context and published projects in PWA
    var projContext;
    var projects;
    function initializePage() {
        //Get the Project context for this web
        projContext = PS.ProjectContext.get_current();
        loadProjects();
    }
    //General CSOM failure event handler
    //Invoked when ExecuteQueryAsync returns unsuccessfully
    function onRequestFailed(sender, args) {
        alert("Failed to execute: " + args.get_message());
        return;
    };

检索项目

loadProjects 函数在服务中查询项目名称和 ID。

应用程序检索项目名称和项目 ID。有关项目的其他信息是可用的，可以通过修改 load 方法来显式标识要检索的属性来访问。 代码中以注释的形式提供了一个示例。

如果查询成功，加载项将继续调用 displayProjects。

    //Query CSOM and get the list of projects in PWA
    function loadProjects() {
        projects = projContext.get_projects();
    //Request to server - identifies what to retrieve
        projContext.load(projects, 'Include(Name, Id)');
        //Notice to server to execute query
        projContext.executeQueryAsync(displayProjects, onRequestFailed);
        // Syntax for requesting more fields to pull down from server
        // projContext.load(projects, 'Include(Name, Description, StartDate, 
        // Id, IsCheckedOut)');
    }

显示项目

displayProjects 函数创建一个表，每个项目一行，以及一个按钮来显示特定项目的任务。

    //Display the projects with names and ids in a table
    function displayProjects() {
        //Current published project and ID
        var p, projId;
        //Project table rows to publish collectively
        var pTable = []; 
        var pEnum = projects.getEnumerator();
        //Build a 3-column table, with one project per row.
        while (pEnum.moveNext()) {
            p = pEnum.get_current();
        
            //Items used in getting information for table rows:
            //Current published project object, and ID and name
            // var project = p;
            // var projId = p.get_id();
            // var projName = p.get_name();
        
            //Continue processing/working with project object as needed.
        }
    }

注意

while 循环访问 ID 和名称属性。 这与调用又访问相同属性的函数的源代码项目略有不同。

显示项目的任务

任务虽然是加载项的一部分，但不是初始加载的一部分。 如果用户对与项目关联的任务感兴趣，则单击“显示任务”按钮会导致使用 btnLoadTasks 事件处理程序在列表中显示任务。

btnLoadTasks 事件处理程序使用相应的项目 ID 从服务器请求指定项目的任务。 检索到后，btnLoadTasks 会将任务列表传递给 displayTasks 以在屏幕上显示任务。

    //Query CSOM and get the list of tasks for a specific project
    function btnLoadTasks(pid) {
        //Event handler for the "Show tasks" buttons. 
        //
        //The project ID is the sole argument and is used to get the appropriate task 
        //info from the service.
        //The project ID is also the button name, and is used to identify where to place
        //the task information in the table.
        //
        //Project ID to pass to the event handler
        var projId = pid;
        //
        //Get the project reference
        var pProj = projects.getById(projId);
        //
        //Get the tasks collection reference associated with the project.
        var tasks = pProj.get_tasks();
        //
        projContext.load(tasks, 'Include(Id, Name, Start, ScheduledStart, Completion)');
        //
        //If the query succeeds, displayTasks presents the tasks to the user.
        projContext.executeQueryAsync(function () { displayTasks(tasks, projId) }, onRequestFailed);
    }

displayTasks 函数在项目条目下方显示与指定项目关联的任务。

    //Insert tasks for the specified project immediately underneath the project entry 
    //in the table.
    function displayTasks(tasks, projId) {
        //selected project ID
        var pId = projId;
        //individual task
        var t;
        //Task table rows to publish collectively
        var tTable = [];
        var tEnum = tasks.getEnumerator();
        //Build table one task per row.
        while (tEnum.moveNext()) {
            t = tEnum.get_current();
            //
            //Items used in getting information for table rows:
            //Current task object, and ID and name
            // var task = t;
            // var taskId = t.get_id();
            // var taskName = t.get_name();
            
            //Continue processing/working with task object as needed.
        }
    }

注意

while 循环访问任务 ID 和名称属性。 这与调用又访问相同属性的函数的源代码项目略有不同。

下面提供了单个项目任务的示例输出。

显示项目任务输出的屏幕截图

另请参阅

有关 Project Online 和使用 CSOM 进行应用程序开发的文档和示例，请参阅 Project 开发门户。