定制功能区(part 1) –创建选项卡，组和控件

[此帖子于2011年9月更新，其中包含修复程序和更多信息–详见文字]

在本系列文章中：

1. 定制功能区–创建选项卡，组和控件 (this post)
2. 将功能区项目添加到现有选项卡/组中
3. 功能区自定义-下拉控件，客户端对象模型和JavaScript页面组件
4. 通过Web部件和现场控件以编程方式自定义功能区
5. ** 2011年10月-下载本系列（以及更多）中的代码示例** 

现在，一些不错的帖子开始出现在SharePoint 2010功能区自定义中，在接下来的几篇文章中，我要介绍开发解决方案时可能要使用功能区进行的一些关键操作。然后直接潜水，一些功能区基础知识：

• Ribbon 元素 必须 使用CustomAction标签以声明性XML进行定义-即使您实际上将使用代码来操作它们（例如，使其可见，启用/禁用等）
• 的“control hierarchy” is ribbon > tab > group > controls – we’我将在这篇文章中探索所有这些
• 单个按钮/控件不会出现在功能区上，也不会消失。这是关键的功能区原则，以避免“I’m 当然 这个按钮昨天在这里！”效果-相反，取决于上下文：
  • 可以显示/隐藏整个选项卡
  • 各个控件可以是 启用/禁用
  • [2011年9月–尽管SharePoint本身遵守此准则，但通过自定义，可以*完全隐藏功能区项目（尽管’d仍然说这是不推荐的，因为不一致的地方。本质上，您需要部署XML‘blanks out’ the definition – see 从服务器功能区上卸下按钮 在MSDN上获得更多详细信息。]
• It’s not possible to add custom controls to the ribbon e.g. a custom .ascx/server control. 的list of controls defined by the ribbon can be found 这里 在MSDN文档中，包括按钮，复选框，颜色选择器，组合框，下拉列表，文本框，切换按钮等，但还包括一些时髦的元素，例如微调器，拆分按钮和弹出锚（可以在以下位置找到这些异类的定义）文档）。 FlyoutAnchor特别有趣，因为它将XML作为数据源，并且可以用来构建有趣的“pickers” e.g. with images – I’希望在以后的文章中详细介绍
• 的definitions for the 盒子外面 ribbon 元素 are split across several files in the SharePoint root, with TEMPLATE\GLOBAL\XML\CMDUI.XML being the main one. 您 will likely spend significant time in this file looking for 例 s similar to what you’re building.

It’还值得特别考虑一下JavaScript如何使用功能区– it’经常使用，因为客户端上发生了很多事情。根据您对JavaScript的需求范围（例如，每页还是两页）以及您所需要的复杂性’为此，可以通过以下几种方式提供JavaScript：

• 通过将其嵌入到声明性XML中（通过带有新‘Location="ScriptLink"’ 在 tribute) –这篇文章使用了这种方法，尽管在本系列的后面’ll显示下一个选项
• 通过部署自定义.js文件，其中包含一些面向对象的JavaScript。这是用于更复杂的自定义的方法，您需要在其中创建客户端的对象“page component” in addition to your XML. 的页面组件 supplies the implementation for how your custom ribbon 元素 should handle various events (“commands”）。该对象需要从CUI.js中定义的现有CUI.Page.Component对象派生。与任何JavaScript文件一样，您可以在页面上使用几个选项进行引用。

在这篇文章中，我们’ll显示第一种添加JavaScript的方法，尽管在本系列的后面部分’ll show the use of a 页面组件.

示例-创建新的自定义标签

这是一个相当深入的示例， 因为有必要，它也涵盖了创建自定义组和控件的内容。另外，要用一颗石头杀死两只鸟，我认为最好看看新鸟。‘notifications’ 和 ‘status’客户端对象模型中的框架，用于将消息传递回SharePoint应用程序中的用户。首先我们’将逐步浏览我的自定义标签的外观，然后再实际操作。我有一个标题为“Chris’s custom tab” with 3 groups (“通知讯息”, “Add 状态 messages” 和 “Remove 状态 messages”），每个按钮中都有一些大小和图像不同的按钮（注意：尽管这些屏幕截图来自SP2​​010 beta时间范围，但此示例看起来仍然相同）：

点击‘Notify hello’ button adds a transient message in the 通知 area (fades in from right 和 stays for 5 seconds by default):

点击‘Info 状态’ button shows a 状态 这次以默认颜色显示消息（此消息会一直显示在屏幕上，直到被另一个API调用删除为止）：

点击‘Warning 状态’ button shows a 状态 message of a different color to indicate severity, I chose red:

您可能还注意到了‘remove 状态’ buttons 有 become enabled when a 状态 message is present –这样的客户端检查可以通过链接一个‘CommandUIHandler’ with an ‘EnabledScript’ 在 tribute, as we’re about to see.

那么，需要什么XML来实现呢？在滚动浏览之前，请注意我’我采用了一些声明的复杂方法，因此我的示例尽可能提供了很多信息– most samples I’到目前为止，您只需在一个组中添加一个或两个按钮，然后’t specify the "’group template” details which determines how the controls in the group get laid out. This is fine for a button or 二 as you can just reference an 盒子外面 组模板, but if you want to do anything different you’有点卡住，所以希望这是很好的文档：

   1: <?xml version="1.0" encoding="utf-8"?> 

   2: <Elements xmlns="http://schemas.microsoft.com/sharepoint/"> 

   3:   <  CustomAction   

   4:       Id="COB.SharePoint.Ribbon.CustomTab" 

   5:       位置="CommandUI.Ribbon" 

   6:       注册类型="List" 

   7:       注册编号="101"> 

   8:     <命令UIExtension> 

   9:       <命令UIDefinitions> 

  10:         <命令UIDefinition 位置="Ribbon.Tabs._children"> 

  11:           <Tab Id="COB.SharePoint.Ribbon.CustomTab" 

  12:                Title="Chris's custom tab" 

  13:                Description="Groups  和  controls will go in 这里" 

  14:                顺序="550"> 

  15:             < 缩放比例  Id="COB.SharePoint.Ribbon.CustomTab.Scaling"> 

  16:               <最大尺寸 Id="COB.SharePoint.Ribbon.CustomTab.NotificationGroup.MaxSize" 

  17:                        GroupId="COB.SharePoint.Ribbon.CustomTab.NotificationGroup" 

  18:                        Size="OneLarge"/> 

  19:               <最大尺寸 Id="COB.SharePoint.Ribbon.CustomTab.StatusGroup.MaxSize" 

  20:                        GroupId="COB.SharePoint.Ribbon.CustomTab.StatusGroup" 

  21:                        Size="TwoMedium"/> 

  22:               <最大尺寸 Id="COB.SharePoint.Ribbon.CustomTab.RemoveStatusGroup.MaxSize" 

  23:                        GroupId="COB.SharePoint.Ribbon.CustomTab.RemoveStatusGroup" 

  24:                        Size="TwoLarge"/> 

  25:               <规模 Id="COB.SharePoint.Ribbon.CustomTab.NotificationGroup.Scaling.CustomTabScaling" 

  26:                      GroupId="COB.SharePoint.Ribbon.CustomTab.NotificationGroup" 

  27:                      Size="OneLarge" /> 

  28:               <规模 Id="COB.SharePoint.Ribbon.CustomTab.StatusGroup.Scaling.CustomTabScaling" 

  29:                      GroupId="COB.SharePoint.Ribbon.CustomTab.StatusGroup" 

  30:                      Size="TwoMedium" /> 

  31:               <规模 Id="COB.SharePoint.Ribbon.CustomTab.RemoveStatusGroup.Scaling.CustomTabScaling" 

  32:                      GroupId="COB.SharePoint.Ribbon.CustomTab.RemoveStatusGroup" 

  33:                      Size="TwoLarge" /> 

  34:             </ 缩放比例 > 

  35:             <团体 Id="COB.SharePoint.Ribbon.CustomTab.Groups"> 

  36:               <Group 

  37:                 Id="COB.SharePoint.Ribbon.CustomTab.NotificationGroup" 

  38:                 Description="Contains notification items" 

  39:                 Title="通知讯息" 

  40:                 顺序="10" 

  41:                 模板="Ribbon.Templates.OneLargeExample"> 

  42:                 <Controls Id="COB.SharePoint.Ribbon.CustomTab.NotificationGroup.Controls"> 

  43:                   <Button 

  44:                     Id="COB.SharePoint.Ribbon.CustomTab.NotificationGroup.Notify" 

  45:                     命令="COB.Command.Notify" 

  46:                     顺序="10" 

  47:                     Image16by16="/_layouts/images/NoteBoard_16x16.png" 

  48:                     Image32by32="/_layouts/images/NoteBoard_32x32.png" 

  49:                     Description="Uses the notification area to display a message." 

  50:                     LabelText="Notify hello" 

  51:                     模板Alias="cust1"/> 

  52:                 </Controls> 

  53:               </Group> 

  54:               <Group 

  55:                 Id="COB.SharePoint.Ribbon.CustomTab.StatusGroup" 

  56:                 Description="Contains 'add 状态' items" 

  57:                 Title="Add 状态 messages" 

  58:                 顺序="20" 

  59:                 模板="Ribbon.Templates.TwoMediumExample"> 

  60:                 <Controls Id="COB.SharePoint.Ribbon.CustomTab.StatusGroup.Controls"> 

  61:                   <Button 

  62:                     Id="COB.SharePoint.Ribbon.CustomTab.StatusGroup.AddStatusInfo" 

  63:                     命令="COB.Command.AddStatusInfo" 

  64:                     顺序="10" 

  65:                     Image16by16="/_layouts/images/info16by16.gif" 

  66:                     Image32by32="/_layouts/images/info16by16.gif" 

  67:                     Description="Uses the 状态 bar to display an info message." 

  68:                     LabelText="Info 状态" 

  69:                     模板Alias="cust2"/> 

  70:                   <Button 

  71:                     Id="COB.SharePoint.Ribbon.CustomTab.StatusGroup.AddStatusWarning" 

  72:                     命令="COB.Command.AddStatusWarn" 

  73:                     顺序="20" 

  74:                     Image16by16="/_layouts/images/warning16by16.gif" 

  75:                     Image32by32="/_layouts/images/warning32by32.gif" 

  76:                     Description="Uses the 状态 bar to display a warning message." 

  77:                     LabelText="Warning 状态" 

  78:                     模板Alias="cust3"/> 

  79:                 </Controls> 

  80:               </Group> 

  81:               <Group 

  82:                   Id="COB.SharePoint.Ribbon.CustomTab.RemoveStatusGroup" 

  83:                   Description="Contains 'remove 状态' items" 

  84:                   Title="Remove 状态 messages" 

  85:                   顺序="30" 

  86:                   模板="Ribbon.Templates.TwoLargeExample"> 

  87:                 <Controls Id="COB.SharePoint.Ribbon.CustomTab.RemoveStatusGroup.Controls"> 

  88:                   <Button 

  89:                     Id="COB.SharePoint.Ribbon.CustomTab.RemoveStatusGroup.RemoveLastStatusButton" 

  90:                     命令="COB.Command.RemoveLastStatus" 

  91:                     顺序="10" 

  92:                     Image16by16="/_layouts/images/warning16by16.gif" 

  93:                     Image32by32="/_layouts/images/CRIT_32.GIF" 

  94:                     Description="Removes the last message from the 状态 bar." 

  95:                     LabelText="Remove last 状态 message" 

  96:                     模板Alias="cust4"/> 

  97:                   <Button 

  98:                     Id="COB.SharePoint.Ribbon.CustomTab.RemoveStatusGroup.RemoveAllStatusButton" 

  99:                     命令="COB.Command.RemoveAllStatus" 

 100:                     顺序="20" 

  101 :                     Image16by16="/_layouts/images/warning16by16.gif" 

 102:                     Image32by32="/_layouts/images/CRIT_32.GIF" 

 103:                     Description="Removes all messages from the 状态 bar." 

 104:                     LabelText="Remove all 状态 messages" 

 105:                     模板Alias="cust5"/> 

 106:                 </Controls> 

 107:               </Group> 

 108:             </团体> 

 109:           </Tab> 

 110:         </命令UIDefinition> 

 111:         <命令UIDefinition 位置="Ribbon.Templates._children"> 

 112:           <组模板 Id="Ribbon.Templates.OneLargeExample"> 

 113:             <Layout Title="OneLarge" LayoutTitle="OneLarge"> 

 114:               <Section Alignment="Top" Type="OneRow"> 

 115:                 <Row> 

 116:                   <ControlRef DisplayMode="Large" 模板Alias="cust1" /> 

 117:                 </Row> 

 118:               </Section> 

 119:             </Layout> 

 120:           </组模板> 

 121:         </命令UIDefinition> 

 122:         <命令UIDefinition 位置="Ribbon.Templates._children"> 

 123:           <组模板 Id="Ribbon.Templates.TwoMediumExample"> 

 124:             <Layout Title="TwoMedium" LayoutTitle="TwoMedium"> 

 125:               <Section Alignment="Top" Type="TwoRow"> 

 126:                 <Row> 

 127:                   <ControlRef DisplayMode="Medium" 模板Alias="cust2" /> 

 128:                 </Row> 

 129:                 <Row> 

 130:                   <ControlRef DisplayMode="Medium" 模板Alias="cust3" /> 

 131:                 </Row> 

 132:               </Section> 

 133:             </Layout> 

 134:           </组模板> 

 135:         </命令UIDefinition> 

 136:         <命令UIDefinition 位置="Ribbon.Templates._children"> 

 137:           <组模板 Id="Ribbon.Templates.TwoLargeExample"> 

 138:             <Layout Title="TwoLarge" LayoutTitle="TwoLarge"> 

 139:               <Section Alignment="Top" Type="OneRow"> 

 140:                 <Row> 

 141:                   <ControlRef DisplayMode="Large" 模板Alias="cust4" /> 

 142:                   <ControlRef DisplayMode="Large" 模板Alias="cust5" /> 

 143:                 </Row> 

 144:               </Section> 

 145:             </Layout> 

 146:           </组模板> 

 147:         </命令UIDefinition> 

 148:       </命令UIDefinitions> 

 149:       <命令UIHandlers> 

 150:         <命令UIHandler 

 151:             命令="COB.Command.Notify" 

 152:             命令Action="javascript: var notificationId =  SP.UI.通知 .addNotification('Hello from the notification area'); " /> 

 153:         <命令UIHandler 

 154:             命令="COB.Command.AddStatusInfo" 

 155:             命令Action="javascript:                    

 156:               var 状态Id = SP.UI.Status.addStatus('Quite important 状态 message');         

 157:               visibleStatusIds.push(statusId); 

 158:               enableRemoveStatusButton(); 

 159:               RefreshCommandUI（）;" /> 

 160:         <命令UIHandler 

 161:             命令="COB.Command.AddStatusWarn" 

 162:             命令Action="javascript: 

 163:               var warnStatusId = SP.UI.Status.addStatus('Very important 状态 message'); 

 164:               SP.UI.Status.setStatusPriColor(warnStatusId, 'red');   

 165:               visibleStatusIds.push(warnStatusId); 

 166:               enableRemoveStatusButton(); 

 167:               RefreshCommandUI（）; " /> 

 168:         <命令UIHandler 

 169:             命令="COB.Command.RemoveLastStatus" 

 170:             启用脚本="javascript: enableRemoveStatusButton();" 

 171:             命令Action="javascript:             

 172:               SP.UI.Status.removeStatus(visibleStatusIds[visibleStatusIds.length - 1]);   

 173:               visibleStatusIds.pop(); 

 174:               enableRemoveStatusButton(); 

 175:               RefreshCommandUI（）;" /> 

 176:         <命令UIHandler 

 177:             命令="COB.Command.RemoveAllStatus" 

 178:             启用脚本="javascript: enableRemoveStatusButton();" 

 179:             命令Action="javascript:           

 180:               SP.UI.Status.removeAllStatus(true);        

 181:               visibleStatusIds.length = 0; 

 182:               enableRemoveStatusButton(); 

 183:               RefreshCommandUI（）;" /> 

 184:       </命令UIHandlers> 

 185:     </命令UIExtension> 

 186:   </  CustomAction  > 

 187:   <  CustomAction   

 188:     Id="COB.Command.RemoveLastStatus.CheckEnable" 位置="ScriptLink" 

 189:     ScriptBlock="          

 190:       var visibleStatusIds = [];                           

 191:       function enableRemoveStatusButton()  {   

 192:           return (visibleStatusIds.length > 0);        

 193:       }" /> 

 194: </Elements>

遵循XML顺序的一些关键点：

• CustomAction ：
  • 注意我有 二 CustomAction 元素– one for the ribbon 元素, the other for some JavaScript I want to use with my custom 元素. 这是approach mentioned earlier where the JavaScript is effectively embedded in your XML [旁注：你不’t 有 要进行功能区定制以利用这种方法-这种使用CustomAction的方法是向页面提供JavaScript的新方法，只要知道它将为Feature范围中的每个页面（例如站点/网站）添加，您就无法控制在页面的哪个位置将被注入。它确实使您能够通过功能停用取消JavaScript，这在许多情况下可能很有用）。
    
    • 的位置 在 tribute of CustomAction for ribbon 元素 should 总是 be “CommandUI.Ribbon”
    • 的位置 在 tribute of CustomAction for script is a 新 value, “ScriptLink”
  • 我的功能区选项卡的范围为 仅文档库– 这是礼貌的 注册类型="List" 注册编号="101" 属性（这正是将CustomAction定位到SharePoint 2007中的文档库时所做的事情，在此没有更改）
  • 以这种方式定位列表时，RegistrationId引用列表模板ID（例如，通用列表=100。文档库= 101 等）。– 这里’模板ID的完整列表) –例如，不可能以声明方式定位列表。 GUID或URL。因此，请考虑这可能会促使您在其他情况下可能没有创建列表模板，或者定义仅在特定情况下显示的上下文选项卡。
  • 注册类型的其他选项继续是“ContentType”, “ProgID” 和 “FileType”, but I’m pretty 当然 only “List”可以用于功能区元素，但是我’尚未测试，因此我保留错的权利！ [2011年9月– 注册类型 =”ContentType也可以。]  如果您想要一个不同的作用域级别，则可以省略 注册类型 和 注册编号 属性并使用诸如SPRibbon.MakeTabAvailable（）之类的代码有条件地显示功能区–通常这将是‘contextual’ tab. 在本系列后面的文章中，我将介绍如何为Web部件或自定义字段控件添加功能区自定义项，以进一步说明这一点。
• 命令UIDefinition:
  • 另一个元素可能有多个–一个用于主要的自定义定义，一个用于每个“GroupTemplate”设置的元素（稍后会有更多介绍）。对于主要的“Location”此属性非常重要，因为它指定了定制应出现的位置。我的价值“Ribbon.Tabs._children” indicates I’我在里面加点东西“Ribbon.Tabs”由SharePoint定义的集合（通常在CMDUI.XML中）– “_children”是在功能区体系结构中添加到许多集合时使用的约定。我们’ll look 在 下一篇文章中如何在现有组中添加新组和控件，但作为一个简单的示例，将一个组添加到“Ribbon.Library.Groups._children”将使您的小组出现在小组的某个位置‘Ribbon.Library’标签，如下所示（具体取决于“Sequence”组号）：
    
• 标签：
  • 的“Sequence”属性决定将我的标签放置在现有标签之间的位置（并且通常定义与该标签相比，该标签应该放在哪个位置’的兄弟姐妹）。开箱即用的值通常是10的倍数，偶尔是5的倍数，因此您的序列值应避免使用此类数字以避免冲突。通常你’我将需要找到您要定位的位置附近的周围元素的声明（通常在CMDUI.XML中）以找到合适的编号。
• 缩放比例 （和儿童）：
  • 本节定义在调整窗口大小时，元素的行为方式’没有足够的空间。你需要一个“MaxSize” 和 “Scale”您定义的每个组的元素。这些元素定义元素在以下位置时应位于的大小和布局“max”，以及窗口变小时要更改的内容–有效地，您可以根据窗口大小为控件提供多种布局（例如，对重要按钮进行优先级排序）。这是SharePoint功能区的一个非常酷和有用的功能。 [2011年9月– note that these 元素 should be sequenced 最大尺寸, 最大尺寸, 规模, 规模 (as mentioned in the comments below). This changed from beta to RTM, 和 is now reflected in my code sample above.]
• 组：
  • 这是“功能区选项卡上的部分”这是您控件的容器–在上面的小图中，一个Group的例子是‘View Format’其中包含最左边的两个按钮。这里的关键是“Sequence”（与其他地方的交易相同），并且“Template” –这是对“GroupTemplate” element (which we’很快就会介绍）。本质上，这是将告诉功能区框架如何在该组中布置控件的链接。
• 控制项：
  • 很明显，这是您要添加的任何控件的父节点，例如按钮，下拉菜单等。请注意，此处的每个控件都必须有一个“TemplateAlias” 在 tribute – this tells the framework exactly where to place the individual control within the 组模板 which is referenced.
  • Controls expose various 命令, via 在 tributes –一个按钮只是有一个“Command”点击时会触发的属性，而下拉菜单中还包含其他属性，例如“PopulateQueryCommand” 和 “QueryCommand". These link to “CommandUIHandler” 元素 or code defined in a JavaScript 页面组件.
• 组模板:
  • 类似于定义HTML表，此部分提供控件的实际布局，对齐方式，控件大小等。要声明的每个控件都需要一个对应的“ControlRef”元素将与“TemplateAlias” value. [2011年9月–顺便说一句，我同意 安德鲁·康奈尔’s assertion that although you can avoid having to define 组模板s by using ones defined by Microsoft, this should be avoided since the template may not 总是 be available.]
• 命令UIHandler:
  • 在这里，您可以定义在基本“Command”触发控件（例如，单击按钮）–但是请记住，这只是提供JavaScript的一种方式–另一种方法是使用页面组件（如本系列第三篇文章中所述）。使用这种方法，命令名称必须与Control元素上定义的名称匹配，并且“CommandAction”属性包含基本命令的脚本。您也可以使用“EnabledScript”属性以添加一些脚本，该脚本决定是否应启用控件– this is how my '’remove 状态’仅在有要删除的消息时启用按钮。
  • 由于所有JavaScript都被添加到同一页面，因此’ll see in my sample it is possible to declare variables which get used by other JavaScript provisioned by a different 命令UIHandler –再说一次，虽然顺序是确定的，但是您无法控制将脚本添加到整个页面的位置（在开始时<body>标记），因此如果您需要在DOM完成时运行代码，’d必须采取措施在适当的时间调用您的代码–这实际上是页面组件方法，本系列后面的内容将对此进行更多介绍。

希望您觉得这有用。下次我们’ll take a quick look 在 adding items to existing ribbon locations, before moving onto working with JavaScript 和 页面组件s etc.