如何：使用用户自定义操作

项目
06/15/2015

上次修改时间： 2011年4月30日

适用范围： SharePoint Foundation 2010

本文内容
为列表项添加用户自定义操作
修改用户自定义操作
向网站的网站操作中添加用户自定义操作

您可以使用客户端对象模型向用户界面中添加自定义操作。UserCustomActions 属性返回网站集、网站或列表的自定义操作集合。若要在其中一个集合中创建自定义操作，请调用 UserCustomActionCollection 类 (JavaScript: UserCustomActionCollection) 的 Add() 方法 (JavaScript: add())。在返回的 UserCustomAction 对象 (JavaScript: UserCustomAction) 上设置新操作的属性，然后在通过调用 ExecuteQuery() 或 ExecuteQueryAsync(ClientRequestSucceededEventHandler, ClientRequestFailedEventHandler) (JavaScript: executeQueryAsync(succeededCallback, failedCallback)) 方法执行查询之前调用 Update() 方法 (JavaScript: update())。用户自定义操作的位置可以由其命名空间位置、自定义操作组以及相对于其他用户自定义操作的顺序确定。有关列出自定义操作位置和组的可能值的表，请参阅默认自定义操作位置和 ID。

为列表项添加用户自定义操作

以下示例向为列表项显示的下拉菜单中添加用户自定义操作。为了将新操作放置到菜单上，Location 属性 (JavaScript: location) 将指定 EditControlBlock，Sequence (JavaScript: sequence) 将指定相对于其他用户自定义操作的放置顺序，而 Url (JavaScript: url) 将指定用于定义该操作的页面的绝对路径。该示例假定 %ProgramFiles%\Common Files\Microsoft Shared\web server extensions\14\TEMPLATE\LAYOUTS 中存在 .aspx 文件。

using System;
using Microsoft.SharePoint.Client;

namespace Microsoft.SDK.SharePointServices.Samples
{
    class CreateUserCustomActionList
    {
        static void Main()
        {
            string urlWebsite = "http://MyServer/sites/MySiteCollection";
            ClientContext clientContext = new ClientContext(urlWebsite);
            Web oWebsite = clientContext.Web;

            List oList = oWebsite.Lists.GetByTitle("My List");
            UserCustomActionCollection collUserCustomAction = oList.UserCustomActions;

            UserCustomAction oUserCustomAction = collUserCustomAction.Add();
            oUserCustomAction.Location = "EditControlBlock";
            oUserCustomAction.Sequence = 100;
            oUserCustomAction.Title = "My First User Custom Action";
            oUserCustomAction.Url = urlWebsite + @"/_layouts/MyPage.aspx";
            oUserCustomAction.Update();

            clientContext.Load(oList,
                list => list.UserCustomActions);

            clientContext.ExecuteQuery();
        }
    }
}

Imports System
Imports Microsoft.SharePoint.Client

Namespace Microsoft.SDK.SharePointServices.Samples
    Class CreateUserCustomActionList

        Shared Sub Main()
            Dim siteUrl As String = "http://MyServer/sites/MySiteCollection"
            Dim clientContext As New ClientContext(siteUrl)

            Dim oWebsite As Web = clientContext.Web

            Dim oList As List = oWebsite.Lists.GetByTitle("My List")
            Dim collUserCustomAction As UserCustomActionCollection = oList.UserCustomActions

            Dim oUserCustomAction As UserCustomAction = collUserCustomAction.Add()
            oUserCustomAction.Location = "EditControlBlock"
            oUserCustomAction.Sequence = 100
            oUserCustomAction.Title = "My First User Custom Action"
            oUserCustomAction.Url = siteUrl + "/_layouts/MyPage.aspx"
            oUserCustomAction.Update()

            clientContext.Load(oList, Function(list) list.UserCustomActions)

            clientContext.ExecuteQuery()

        End Sub
    End Class
End Namespace

siteUrl = '/sites/MySiteCollection';

function createUserCustomActionList() {

    var clientContext = new SP.ClientContext(siteUrl);
    var oWebsite = clientContext.get_web();
    this.oList = oWebsite.get_lists().getByTitle('My List');
    var collUserCustomAction = oList.get_userCustomActions();
        
    var oUserCustomAction = collUserCustomAction.add();
    oUserCustomAction.set_location('EditControlBlock');
    oUserCustomAction.set_sequence(100);
    oUserCustomAction.set_title('My First User Custom Action');
    oUserCustomAction.set_url(siteUrl + '/_layouts/MyPage.aspx');
    oUserCustomAction.update();
        
    clientContext.load(oList, 'Title' ,'UserCustomActions');
    
    clientContext.executeQueryAsync(Function.createDelegate(this, this.onQuerySucceeded), Function.createDelegate(this, this.onQueryFailed));
}

function onQuerySucceeded() {

    alert('Custom action created for ' + this.oList.get_title());}

function onQueryFailed(sender, args) {

    alert('Request failed. ' + args.get_message() + '\n' + args.get_stackTrace());
}

修改用户自定义操作

以下示例从用户自定义操作集合中为列表项的下拉菜单检索相关操作，并更新该自定义操作以包含代表菜单操作的图标。该示例假定 %ProgramFiles%\Common Files\Microsoft Shared\web server extensions\14\TEMPLATE\IMAGES 中存在图标图像文件。

using System;
using Microsoft.SharePoint.Client;

namespace Microsoft.SDK.SharePointServices.Samples
{
    class ModifyUserCustomAction
    {
        static void Main()
        {
            string urlWebsite = "http://MyServer/sites/SiteCollection";
            ClientContext clientContext = new ClientContext(urlWebsite);
            Web oWebsite = clientContext.Web;

            List oList = oWebsite.Lists.GetByTitle("My List");
            UserCustomActionCollection collUserCustomAction = oList.UserCustomActions;

            clientContext.Load(collUserCustomAction,
                userCustomActions => userCustomActions.Include(
                    userCustomAction => userCustomAction.Title));

            clientContext.ExecuteQuery();

            foreach (UserCustomAction oUserCustomAction in collUserCustomAction)
            {
                if (oUserCustomAction.Title == "My First User Custom Action")
                {
                    oUserCustomAction.ImageUrl = "http://MyServer/_layouts/images/MyIcon.png";
                    oUserCustomAction.Update();

                    clientContext.ExecuteQuery();
                }
            }
        }
    }
}

Imports System
Imports Microsoft.SharePoint.Client

Namespace Microsoft.SDK.SharePointServices.Samples
    Class ModifyUserCustomAction

        Shared Sub Main()
            Dim siteUrl As String = "http://MyServer/sites/MySiteCollection"
            Dim clientContext As New ClientContext(siteUrl)
            Dim oWebsite As Web = clientContext.Web

            Dim oList As List = oWebsite.Lists.GetByTitle("My List")
            Dim collUserCustomAction As UserCustomActionCollection = oList.UserCustomActions

            clientContext.Load(collUserCustomAction, _
                               Function(userCustomActions) userCustomActions.Include( _
                                   Function(userCustomAction) userCustomAction.Title))

            clientContext.ExecuteQuery()

            Dim oUserCustomAction As UserCustomAction
            For Each oUserCustomAction In collUserCustomAction
                If oUserCustomAction.Title = "My First User Custom Action" Then
                    oUserCustomAction.ImageUrl = "http://MyServer/_layouts/images/MyIcon.png"
                    oUserCustomAction.Update()

                    clientContext.ExecuteQuery()
                End If
            Next oUserCustomAction

        End Sub
    End Class
End Namespace

siteUrl = '/sites/MySiteCollection';

function modifyUserCustomAction() {

    this.clientContext = new SP.ClientContext(siteUrl);
    var oWebsite = clientContext.get_web();
    this.oList = oWebsite.get_lists().getByTitle('My List');
    this.collUserCustomAction = oList.get_userCustomActions();
        
    clientContext.load(oList,'UserCustomActions','Title');

    clientContext.executeQueryAsync(Function.createDelegate(this, this.SetImage), Function.createDelegate(this, this.onQueryFailed));
}

function SetImage() {

    var customActionEnumerator = collUserCustomAction.getEnumerator();

    while (customActionEnumerator.moveNext()) 
    {
        var oUserCustomAction = customActionEnumerator.get_current();
            
        if (oUserCustomAction.get_title() == 'My First User Custom Action') 
        {
            oUserCustomAction.set_imageUrl('http://MyServer/_layouts/images/MyIcon.png');
            oUserCustomAction.update();
                
            clientContext.load(oUserCustomAction);

            clientContext.executeQueryAsync(Function.createDelegate(this, this.onQuerySucceeded), Function.createDelegate(this, this.onQueryFailed));
        }
    }
}

function onQuerySucceeded() {

    alert('Custom action changed for ' + this.oList.get_title());
}

function onQueryFailed(sender, args) {

        alert('Request failed. ' + args.get_message() + '\n' + args.get_stackTrace());
}

向网站的网站操作中添加用户自定义操作

在网站的"网站操作"菜单上创建用户自定义操作类似于为列表项创建操作：可以调用 Add() 方法 (JavaScript: add())，设置操作属性，然后调用 Update() (JavaScript: update())。以下示例为 Location (JavaScript: location) 指定 Microsoft.SharePoint.StandardMenu，为 Group (JavaScript: group) 指定 SiteActions，以便将新操作放置到"网站操作"菜单上。Sequence (JavaScript: sequence) 的值指定 101，以使该操作出现在序号为 100 的操作的下面。该示例假定 %ProgramFiles%\Common Files\Microsoft Shared\web server extensions\14\TEMPLATE\LAYOUTS 中存在 .aspx 文件。

using System;
using Microsoft.SharePoint.Client;

namespace Microsoft.SDK.SharePointServices.Samples
{
    class CreateUserCustomActionSite
    {
        static void Main()
        {
            string urlWebsite = "http://MyServer/sites/MySiteCollection";
            ClientContext clientContext = new ClientContext(urlWebsite);

            Web oWebsite = clientContext.Web;
            UserCustomActionCollection collUserCustomAction = oWebsite.UserCustomActions;

            UserCustomAction oUserCustomAction = collUserCustomAction.Add();

            oUserCustomAction.Location = "Microsoft.SharePoint.StandardMenu";
            oUserCustomAction.Group = "SiteActions";
            oUserCustomAction.Sequence = 101;
            oUserCustomAction.Title = "Website User Custom Action";
            oUserCustomAction.Description = "This description appears on the Site Actions menu.";
            oUserCustomAction.Url = urlWebsite + @"/_layouts/MyPage.aspx";

            oUserCustomAction.Update();

            clientContext.Load(oWebsite,
                webSite => webSite.UserCustomActions);

            clientContext.ExecuteQuery();
        }
    }
}

Imports System
Imports Microsoft.SharePoint.Client

Namespace Microsoft.SDK.SharePointServices.Samples
    Class ModifyUserCustomAction

        Shared Sub Main()
            Dim siteUrl As String = "http://MyServer/sites/MySiteCollection"
            Dim clientContext As New ClientContext(siteUrl)
            Dim oWebsite As Web = clientContext.Web

            Dim collUserCustomAction As UserCustomActionCollection = oWebsite.UserCustomActions

            Dim oUserCustomAction As UserCustomAction = collUserCustomAction.Add()

            oUserCustomAction.Location = "Microsoft.SharePoint.StandardMenu"
            oUserCustomAction.Group = "SiteActions"
            oUserCustomAction.Sequence = 101
            oUserCustomAction.Title = "Website User Custom Action"
            oUserCustomAction.Description = "This description appears on the Site Actions menu."
            oUserCustomAction.Url = siteUrl + "/_layouts/MyPage.aspx"

            oUserCustomAction.Update()

            clientContext.Load(oWebsite, Function(webSite) webSite.UserCustomActions)

            clientContext.ExecuteQuery()

        End Sub
    End Class
End Namespace

siteUrl = '/sites/MySiteCollection';

function createUserCustomActionSite() {

    var clientContext = new SP.ClientContext(siteUrl);
    this.oWebsite = clientContext.get_web();
    var collUserCustomAction = oWebsite.get_userCustomActions();
        
    var oUserCustomAction = collUserCustomAction.add();
    oUserCustomAction.set_location('Microsoft.SharePoint.StandardMenu');
    oUserCustomAction.set_group('SiteActions');
    oUserCustomAction.set_sequence(101);
    oUserCustomAction.set_title('ECMA Website User Custom Action ECMA');
    oUserCustomAction.set_description('This description appears on the Site Actions menu.');
    oUserCustomAction.set_url(siteUrl + '/_layouts/jstest2.aspx');
    oUserCustomAction.update();
        
    clientContext.load(oWebsite, 'Title', 'UserCustomActions');
    
    clientContext.executeQueryAsync(Function.createDelegate(this, this.onQuerySucceeded), Function.createDelegate(this, this.onQueryFailed));
}

function onQuerySucceeded(sender, args) {

    alert('Custom action created for ' + this.oWebsite.get_title());
}

function onQueryFailed(sender, args) {

    alert('Request failed. ' + args.get_message() + '\n' + args.get_stackTrace());
}

有关在 Microsoft SharePoint Foundation 2010 Silverlight 对象模型上下文中使用客户端对象的信息和示例，请参阅使用 Silverlight 对象模型。

请参阅

概念

其他资源

客户端类库

ECMAScript 类库