开发服务器功能区的网页组件
上次修改时间: 2011年2月9日
适用范围: SharePoint Foundation 2010
本文内容
页面组件中的命令
必需的页面组件方法
可选的页面组件方法
页面组件示例
页面组件是用于与服务器功能区进行交互的 ECMAScript(JavaScript、JScript) 对象。它启用功能区上的命令并响应您在服务器功能区 XML 中定义的命令。所有页面组件都必须派生自 CUI.Page.PageComponent 类并实现必需的方法。本主题将解释这些方法以及在与功能区交互时如何使用它们。
页面组件中的命令
页面组件包含两类命令:全局 和聚焦。一个页面组件只有在具有焦点时才会对聚焦命令做出响应。而对于全局命令,页面组件不管是否具有焦点都会做出响应。页面组件注册为通过 SP.Ribbon.PageState.PageStateHandler.getGlobalCommands() Method和 SP.Ribbon.PageState.PageStateHandler.getFocusedCommands() Method对这两类命令做出响应。本主题后面将更深入地介绍这些方法。
必需的页面组件方法
下面的方法是页面组件正常工作所必需的。
init
SP.Ribbon.PageState.PageStateHandler.init() Method用于初始化页面组件。可使用此方法初始化页面组件的任何变量。这包括初始化页面组件可以处理的命令的列表,以及注册用于处理命令的方法的数组。命令列表在 SP.Ribbon.PageState.PageStateHandler.getFocusedCommands() Method和 SP.Ribbon.PageState.PageStateHandler.getGlobalCommands() Method中使用,而方法数组在SP.Ribbon.PageState.PageStateHandler.handleCommand(commandId, properties, sequence) Method和 SP.Ribbon.PageState.PageStateHandler.canHandleCommand(commandId) Method中使用。
init: function CustomPageComponents_MyCustomPageComponent$init() {
// Create an array of methods used to handle commands passed to the page component.
this._myHandledCommands = new Object;
this._myHandledCommands['MyFocusedRibbonCommands.EnableCustomTab'] = this.canHandleEnableCustomTab;
this._myHandledCommands['MyFocusedRibbonCommands.EnableCustomGroup'] = this.canHandleEnableCustomGroup;
// Create a list of commands that your page component can handle.
this._myCommandList = ['MyFocusedRibbonCommands.EnableCustomTab', 'MyFocusedRibbonCommands.EnableCustomGroup', 'MyFocusedRibbonCommands.HelloWorldCommand', 'MyFocusedRibbonCommands.GoodbyeWorldCommand'];
}
getFocusedCommands
SP.Ribbon.PageState.PageStateHandler.getFocusedCommands() Method返回包含聚焦命令的名称的字符串数组。一个页面组件只有在具有焦点时才会对这些命令做出响应。可以通过两种方式返回命令的列表。可以在该方法中声明一个列表,也可以创建一个如 SP.Ribbon.PageState.PageStateHandler.init() Method中所示的命令名称的数组。下面的代码演示了这两种方式。
getFocusedCommands: function CustomPageComponents_MyCustomPageComponent$getFocusedCommands() {
return ['MyFocusedRibbonCommands.EnableCustomTab', 'MyFocusedRibbonCommands.EnableCustomGroup', 'MyFocusedRibbonCommands.HelloWorldCommand', 'MyFocusedRibbonCommands.GoodbyeWorldCommand'];
// The alternative method using an array of strings. This is defined in the init method.
// return this._myCommandList;
}
getGlobalCommands
SP.Ribbon.PageState.PageStateHandler.getGlobalCommands() Method返回包含全局命令的名称的字符串数组。页面组件在位于页面上时将对这些命令做出响应。可以通过两种方式返回命令的列表。可以在该方法中声明一个列表,也可以创建一个如 SP.Ribbon.PageState.PageStateHandler.init() Method中所示的命令名称的数组。下面的代码演示了这两种方式。
getGlobalCommands: function CustomPageComponents_MyCustomPageComponent$getGlobalCommands() {
return ['MyGlobalRibbonCommands.EnableCustomTab', 'MyGlobalRibbonCommands.EnableCustomGroup', 'MyGlobalRibbonCommands.HelloWorldCommand', 'MyGlobalRibbonCommands.GoodbyeWorldCommand'];
// The alternative method using an array of strings. This is defined in the init method.
// return this._myCommandList;
}
isFocusable
SP.Ribbon.PageState.PageStateHandler.isFocusable() Method返回一个指示页面组件是否可以接收焦点的 Boolean。如果此方法返回 false,则页面管理器将不会注册页面组件的聚焦命令。
isFocusable: function CustomPageComponents_MyCustomPageComponent$isFocusable() {
return true;
}
canHandleCommand
SP.Ribbon.PageState.PageStateHandler.canHandleCommand(commandId) Method返回一个指示页面组件是否可以处理传递给它的命令的 Boolean。可以通过多种方式从此方法中返回值。如果您要定义少量的命令,则使用 if 语句或 switch 语句。如果您要定义大量的命令,则使用一个按命令名称编制索引的命令关联阵列。下面的代码示例演示这些不同的方式。
if 语句和 switch 语句方式。
// Using an if statement.
canHandleCommand: function CustomPageComponents_MyCustomPageComponent$canHandleCommand(commandId) {
if ((commandId === 'MyFocusedRibbonCommands.EnableCustomTab') || (commandId === 'MyFocusedRibbonCommands.EnableCustomGroup')) {
return true; }
}
// Using a switch statement.
canHandleCommand: function CustomPageComponents_MyCustomPageComponent$canHandleCommand(commandId) {
switch(commandId)
{
case 'MyFocusedRibbonCommands.EnableCustomTab':
case 'MyFocusedRibbonCommands.EnableCustomGroup':
return true;
default: return false;
}
}
命令数组方式。
canHandleCommand: function CustomPageComponents_MyCustomPageComponent$canHandleCommand(commandId) {
// The this._myHandledCommands object is a global array of command functions. This is demonstrated in the init method.
var canHandle = this._myHandledCommands[commandId];
if(canHandle)
return true;
else
return false;
}
handleCommand
SP.Ribbon.PageState.PageStateHandler.handleCommand(commandId, properties, sequence) Method用于处理传递给页面组件的命令。您可以调用其他 JavaScript 函数,也可以在 SP.Ribbon.PageState.PageStateHandler.handleCommand(commandId, properties, sequence) Method中编写代码。可以通过多种方式使用此方法来处理命令。您将使用用于 SP.Ribbon.PageState.PageStateHandler.canHandleCommand(commandId) Method的同一个方法。下面的代码演示了这两种方式。
if 语句和 switch 语句方式。
// Using an if statement.
handleCommand: function CustomPageComponents_MyCustomPageComponent$handleCommand(commandId, properties, sequence) {
if (commandId === 'MyFocusedRibbonCommands.HelloWorldCommand')
{
alert('I handled the Hello World command.');
}
else if(commandId === 'MyFocusedRibbonCommands.GoodbyeWorldCommand')
{
alert('I handled the Goodbye World command.');
}
}
// Using a switch statement.
handleCommand: function CustomPageComponents_MyCustomPageComponent$handleCommand(commandId, properties, sequence) {
switch(commandId)
{
case 'MyFocusedRibbonCommands.HelloWorldCommand':
alert('I handled the Hello World command.');
break;
case 'MyFocusedRibbonCommands.GoodbyeWorldCommand':
alert('I handled the Goodbye World Command.');
break;
}
}
命令数组方式。
handleCommand: function CustomPageComponents_MyCustomPageComponent$handleCommand(commandId, properties, sequence) {
// The this._myHandledCommands object is a global array of commands. This is demonstrated in the init method.
return this._myHandledCommands[commandId](commandId, properties, sequence);
}
可选的页面组件方法
下面的方法在页面组件中是可选的。
yieldFocus
当页面组件失去焦点时调用 SP.Ribbon.PageState.PageStateHandler.yieldFocus() Method。
yieldFocus: function CustomPageComponents_MyCustomPageComponent$yieldFocus() {
alert('The page component has lost focus.');
}
receiveFocus
当页面组件接收焦点时使用 SP.Ribbon.PageState.PageStateHandler.receiveFocus() Method。
receiveFocus: function CustomPageComponents_MyCustomPageComponent$receiveFocus() {
alert('The page component has received focus.');
}
页面组件示例
Type.registerNamespace('CustomPageComponents');
CustomPageComponents.MyCustomPageComponent = function CustomPageComponents_MyCustomPageComponent(){
CustomPageComponents.MyCustomPageComponent.initializeBase(this);
}
CustomPageComponents.MyCustomPageComponent.prototype = {
init: function CustomPageComponents_MyCustomPageComponent$init() { },
getFocusedCommands: function CustomPageComponents_MyCustomPageComponent$getFocusedCommands() {
return ['CustomContextualTab.EnableCustomTab', 'CustomContextualTab.EnableCustomGroup', 'CustomContextualTab.HelloWorldCommand', 'CustomContextualTab.GoodbyeWorldCommand'];
},
getGlobalCommands: function CustomPageComponents_MyCustomPageComponent$getGlobalCommands() {
return [];
},
canHandleCommand: function CustomPageComponents_MyCustomPageComponent$canHandleCommand(commandId) {
// Contextual Tab commands
if ((commandId === 'CustomContextualTab.EnableCustomTab') || (commandId === 'CustomContextualTab.EnableCustomGroup') || (commandId === 'CustomContextualTab.HelloWorldCommand') || (commandId === 'CustomContextualTab.GoodbyeWorldCommand')) {
return true;
}
},
handleCommand: function CustomPageComponents_MyCustomPageComponent$handleCommand(commandId, properties, sequence) {
if (commandId === 'CustomContextualTab.HelloWorldCommand') {
alert('Hello, world!');
}
if (commandId === 'CustomContextualTab.GoodbyeWorldCommand') {
alert('Good-bye, world!');
}
},
getId: function CustomPageComponents_MyCustomPageComponent$getId() {
return this._webPartPageComponentId;
}
}
CustomPageComponents.MyCustomPageComponent.registerClass('CustomPageComponents.MyCustomPageComponent', CUI.Page.PageComponent);
SP.SOD.notifyScriptLoadedAndExecuteWaitingJobs("CustomContextualTabPageComponent.js");