开发服务器功能区的网页组件

项目
06/15/2015

上次修改时间： 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");

通过