创建自定义操作以部署 SharePoint 加载项

项目
04/08/2023

创建 SharePoint 加载项时，可以使用自定义操作与主机 Web 中的列表和功能区交互。最终用户安装加载项时，会在主机 Web 上部署自定义操作。自定义操作可以打开远程网页，并通过查询字符串传递信息。

加载项可使用两种类型的自定义操作：功能区和菜单项。

使用本文中的示例的先决条件

需要一个如开始创建提供程序托管的 SharePoint 加载项中所述的开发环境。

有助于了解自定义操作的核心概念

下表列出了一些有价值的文章，这些文章可帮助你了解自定义操作方案中涉及的概念和步骤。

表 1. 自定义操作的核心概念

文章	说明
SharePoint 外接程序	了解 SharePoint 中新的外接程序模型，可以利用此模型来创建对最终用户来说是小型的易于使用的解决方案的外接程序。
适用于 SharePoint 外接程序的 UX 设计	了解在生成 SharePoint 外接程序时可使用的用户体验 (UX) 选项。
SharePoint 中的主机 Web、外接程序 Web 和 SharePoint 组件	了解主机 Web 和外接程序 Web 之间的区别。了解 SharePoint 外接程序中可以包括哪些 SharePoint 组件、将哪些组件部署到主机 Web、将哪些组件部署到外接程序 Web 以及如何在独立的域中部署外接程序 Web。

代码示例：在主机 Web 文档库中创建自定义操作

按照以下步骤在主机 Web 文档库中创建自定义操作：

创建 SharePoint 加载项和远程 Web 项目。
为自定义操作添加加载项网页。
向 SharePoint 加载项项目添加“菜单项”自定义操作。
向 SharePoint 加载项项目添加“功能区”自定义操作。
将加载项起始页设置为主机 Web 主页。
构建和运行解决方案。

创建 SharePoint 加载项和远程 Web 项目

以管理员身份打开 Visual Studio。（为此，请右键单击“开始”菜单上的“Visual Studio”图标，然后选择“以管理员身份运行”。）
按照开始创建提供程序托管的 SharePoint 加载项中所述创建提供程序托管的 SharePoint 加载项，并将其命名为 CustomActionsApp。

为自定义操作添加加载项网页

创建 Visual Studio 解决方案后，右键单击 Web 应用程序项目（而不是 SharePoint 加载项项目），并添加一个新的 Web 窗体，方法是选择“添加”>“新项目”>“Web”>“Web 表单”。将表单命名为 CustomActionTarget.aspx。

在 CustomActionTarget.aspx 文件中，将整个 html 元素及其子项替换为以下 HTML 代码。保留 html 元素上的所有标记不变。 HTML 代码包含执行以下任务的 JavaScript：

提供用于查询字符串参数的占位符。
从查询字符串中提取参数。
呈现占位符中的参数。

重要

仅在选定项时才会传递 ItemURL 和 ItemID 令牌。在生产质量 SharePoint 加载项中，代码需要处理未选定任何项的情况。在此示例中，代码将提醒用户未选择任何项。

<html xmlns="http://www.w3.org/1999/xhtml">
<head>
    <title>Custom action target</title>
</head>
<body>
    <h2>Query string parameters passed by the custom action:</h2>

    <!-- Placeholder for query string parameters -->
    <ul id="qsparams"/>

    <!-- Main JavaScript function, renders
        the query string parameters -->
    <script lang="javascript">
        var params = document.URL.split("?")[1].split("&amp;");
        var paramsHTML = "";

        // Extracts the parameters from the query string.
        // Parameters are URLencoded, decode for rendering
        // in page.
        for (var i = 0; i < params.length; i = i + 1) {
            params[i] = decodeURIComponent(params[i]);
            paramsHTML += "<li>" + params[i] + "</li>";
        }

        // Alert the user when no item has been selected.
        // (The SPListItemId is the 5th parameter.)
        if (params[5] === undefined) {
            paramsHTML += "<div> <h3> No item has been selected from the list.  Please select an item. </h3> </div> ";
        }

        // Render parameters in the placeholder.
        document.getElementById("qsparams").innerHTML =
            paramsHTML;
    </script>
</body>
</html>

右键单击 SharePoint 加载项项目，然后选择“添加”>“新项目”>“Office/SharePoint”>“菜单项自定义操作”。
保留默认名称，然后选择“添加”。

“创建菜单项自定义操作”向导会询问一系列问题。给出下表中的答案：

表 2. 菜单项自定义操作属性

属性问题	答案
想要在哪里公开自定义操作？	选择“主机 Web”。
自定义操作的作用范围是什么？	选择“列表模板”。
自定义操作的作用范围限定到了哪一项？	选择“文档库”。
菜单项文本是什么？	输入“我的自定义操作”。
自定义操作转到何处？	选择“CustomActionAppWeb\CustomActionTarget.aspx”页。

选择“完成”。

Visual Studio 在菜单项自定义操作功能的 elements.xml 文件中生成以下标记：

<?xml version="1.0" encoding="utf-8"?>
<Elements 
    xmlns="http://schemas.microsoft.com/sharepoint/">
    <!-- RegistrationId attribute is the list type id,
        in this case, a document library (id=101). -->
<CustomAction 
    Id="65695319-4784-478e-8dcd-4e541cb1d682.CustomAction"
    RegistrationType="List"
    RegistrationId="101"
    Location="EditControlBlock"
    Sequence="10001"
    Title="Invoke custom action">
    <!-- 
    Update the Url below to the page you want the custom action to use.
    Start the URL with the token ~remoteAppUrl if the page is in the
    associated web project, use ~appWebUrl if page is in the add-in project.
    -->
    <UrlAction Url=
"~remoteAppUrl/CustomActionTarget.aspx?{StandardTokens}&amp;amp;SPListItemId={ItemId}&amp;amp;SPListId={ListId}" />
</CustomAction>
</Elements>

将以下查询参数添加到 UrlAction 元素的 Url 属性末尾：

&amp;SPSource={Source}&amp;SPListURLDir={ListUrlDir}&amp;SPItemURL={ItemUrl}

UrlAction 元素应如下所示：

<UrlAction Url= "~remoteAppUrl/CustomActionTarget.aspx?{StandardTokens}&amp;SPListItemId={ItemId}&amp;SPListId={ListId}&amp;SPSource={Source}&amp;SPListURLDir={ListUrlDir}&amp;SPItemURL={ItemUrl}" />

注意

在本示例中，当用户从菜单中选择自定义操作时，远程网页将在完整窗口中打开。自定义菜单操作也可以在对话框中打开远程网页，方法是使用 HostWebDialog 属性。有关详细信息，请参阅 SharePoint 加载项本地化。

向 SharePoint 加载项项目中添加“功能区”自定义操作

右键单击 SharePoint 加载项项目，然后选择“添加”>“新项目”>“Office/SharePoint”>“功能区自定义操作”。
保留默认名称，然后选择“添加”。

“创建功能区自定义操作”向导会询问一系列问题。给出下表中的答案：

表 3. 功能区自定义操作属性

属性问题	答案
想要在哪里公开自定义操作？	选择“主机 Web”。
自定义操作的作用范围是什么？	选择“列表模板”。
自定义操作的作用范围限定到了哪一项？	选择“文档库”。
控件位于何处？	选择“Ribbon.Documents.Manage”。
菜单项文本是什么？	输入“我的自定义功能区按钮”。
自定义操作转到何处？	选择“CustomActionAppWeb\CustomActionTarget.aspx”页。

Visual Studio 在功能区自定义操作功能的 elements.xml 文件中生成以下标记：

<?xml version="1.0" encoding="utf-8"?>
<Elements xmlns="http://schemas.microsoft.com/sharepoint/">
<CustomAction Id="85691508-c076-4f43-93d4-96b4d5253a09.RibbonCustomAction1"
                RegistrationType="List"
                RegistrationId="101"
                Location="CommandUI.Ribbon"
                Sequence="10001"
                Title="Invoke &amp;apos;RibbonCustomAction1&amp;apos; action">
    <CommandUIExtension>
    <!-- 
    Update the UI definitions below with the controls and the command actions
    that you want to enable for the custom action.
    -->
    <CommandUIDefinitions>
        <CommandUIDefinition Location="Ribbon.Documents.Manage.Controls._children">
        <Button Id="Ribbon.Documents.Manage.RibbonCustomAction1Button"
                Alt="My Custom Ribbon Button"
                Sequence="100"
                Command="Invoke_RibbonCustomAction1ButtonRequest"
                LabelText="My Custom Ribbon Button"
                TemplateAlias="o1"
                Image32by32="_layouts/15/images/placeholder32x32.png"
                Image16by16="_layouts/15/images/placeholder16x16.png" />
        </CommandUIDefinition>
    </CommandUIDefinitions>
    <CommandUIHandlers>
        <CommandUIHandler Command="Invoke_RibbonCustomAction1ButtonRequest"
                        CommandAction="~remoteAppUrl/CustomActionTarget.aspx?{StandardTokens}&amp;amp;SPListItemId={SelectedItemId}&amp;amp;SPListId={SelectedListId}"/>
    </CommandUIHandlers>
    </CommandUIExtension >
</CustomAction>
</Elements>

将以下查询参数添加到 CommandAction 元素的 CommandUIHandler 属性末尾：

&amp;SPSource={Source}&amp;SPListURLDir={ListUrlDir}

CommandUIHandler 元素应如下所示：

<CommandUIHandler Command="Invoke_RibbonCustomAction1ButtonRequest" CommandAction="~remoteAppUrl/CustomActionTarget.aspx?{StandardTokens}&amp;SPListItemId={SelectedItemId}&amp;SPListId={SelectedListId}&amp;SPSource={Source}&amp;SPListURLDir={ListUrlDir}" />

注意

功能区自定义操作使用 SelectedListId 和 SelectedItemId。 ListId 和 ItemId 仅适用于菜单项自定义操作。

将加载项起始页设置为主机 Web 主页

接下来的示例 SharePoint 加载项不具有任何加载项 Web，其远程 Web 应用程序的存在只是为了托管表单。因此，加载项的起始页应设置为主机 Web 的主页。

要开始操作，请在“解决方案资源管理器”中选择 SharePoint 加载项项目（不是 Web 应用程序项目）并将“网站 URL”属性的值复制到剪贴板中，包括协议（例如，https://contoso.sharepoint.com）。
打开加载项清单，然后将 URL 粘贴到“起始页”框中。
可以选择从 Web 应用程序项目中删除 Default.aspx 页面，因为它没有在 SharePoint 外接程序中使用。

生成并运行解决方案

按 F5 键。

注意

按 F5 键时，Visual Studio 会生成解决方案并部署加载项，同时还会打开加载项的权限页面。
选择“信任它”按钮。将打开开发人员网站的默认页面。
导航到主机 Web 中的任意文档库。

启动自定义菜单操作
选择任意文档的标注按钮 (...)。标注将打开。
选择标注上的标注按钮 (...)。
选择“高级”。
在上下文菜单中选择“我的自定义菜单操作”。应看到类似下面的内容在远程网页上打开：

具有来自自定义操作的参数的远程网页
选择浏览器上的“后退”按钮返回到库。

启动自定义功能区操作
选择任意文档。
打开功能区上的“文件”选项卡。
选择“我的自定义功能区按钮”。会看到相同的远程网页。

解决方案疑难解答

问题	解决方案
在按 F5 键后，Visual Studio 不打开浏览器。	将 SharePoint 加载项项目设置为启动项目。
在 Visual Studio 中选择 F5 键后，不会解析 URL 中的标记。	转到主机 Web 中的“网站内容”页，并选择加载项图标。

Share via