Entwickeln von Seitenkomponenten für das Menüband für die Serverkomponente

Letzte Änderung: Mittwoch, 9. Februar 2011

Gilt für: SharePoint Foundation 2010

Inhalt dieses Artikels
Befehle in einer Seitenkomponente
Erforderliche Methoden für Seitenkomponenten
Optionale Methoden für Seitenkomponenten
Beispiel für eine Seitenkomponente

Bei einer Seitenkomponente handelt es sich um ein ECMAScript (JavaScript, JScript)-Objekt, das zur Interaktion mit dem Menüband für die Serverkomponente verwendet wird. Dadurch werden Befehle auf dem Menüband aktiviert, und es wird auf die Befehle reagiert, die Sie im Menüband für die Serverkomponente-XML definieren. Alle Seitenkomponenten müssen von der CUI.Page.PageComponent Class-Klasse abgeleitet sein und die erforderlichen Methoden implementieren. In diesem Thema werden diese Methoden und deren Verwendung bei der Interaktion mit dem Menüband erläutert.

Befehle in einer Seitenkomponente

Eine Seitenkomponente enthält zwei Arten von Befehlen: globale und fokussierte. Eine Seitenkomponente reagiert nur auf fokussierte Befehle, wenn sie den Fokus besitzt. Bei globalen Befehlen reagiert eine Seitenkomponente unabhängig vom Fokus auf den Befehl. Die Seitenkomponente wird für die Reaktion auf beide Arten von Befehlen über die SP.Ribbon.PageState.PageStateHandler.getGlobalCommands() Method und die SP.Ribbon.PageState.PageStateHandler.getFocusedCommands() Method registriert. Diese Methoden werden ausführlicher in diesem Thema behandelt.

Erforderliche Methoden für Seitenkomponenten

Die folgenden Methoden sind für den Betrieb der Seitenkomponente erforderlich.

"init"

Mit der SP.Ribbon.PageState.PageStateHandler.init() Method wird die Seitenkomponente initialisiert. Mit dieser Methode kann jede beliebige Variable für die Seitenkomponente initialisiert werden. Dies schließt die Initialisierung der Liste mit Befehlen ein, die von der Seitenkomponente behandelt werden können, sowie das Registrieren des Arrays der zum Behandeln von Befehlen verwendeten Methoden. Die Liste der Befehle wird in der SP.Ribbon.PageState.PageStateHandler.getFocusedCommands() Method und der SP.Ribbon.PageState.PageStateHandler.getGlobalCommands() Method verwendet. Das Array der Methoden wird in der SP.Ribbon.PageState.PageStateHandler.handleCommand(commandId, properties, sequence) Method und der SP.Ribbon.PageState.PageStateHandler.canHandleCommand(commandId) Method verwendet.

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"

Von der SP.Ribbon.PageState.PageStateHandler.getFocusedCommands() Method wird ein Zeichenfolgenarray mit den Namen der fokussierten Befehle zurückgegeben. Eine Seitenkomponente reagiert nur auf diese Befehle, wenn sie den Fokus besitzt. Es gibt zwei Ansätze für das Zurückgeben der Liste mit den Befehlen. Sie können entweder eine Liste in der Methode deklarieren oder ein Array der Befehlsnamen wie in der SP.Ribbon.PageState.PageStateHandler.init() Method gezeigt erstellen. Im folgenden Code werden beide Ansätze gezeigt.

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"

Von der SP.Ribbon.PageState.PageStateHandler.getGlobalCommands() Method wird ein Zeichenfolgenarray mit den Namen der globalen Befehle zurückgegeben. Die Seitenkomponente reagiert auf diese Befehle, wenn sie sich auf der Seite befindet. Es gibt zwei Ansätze für das Zurückgeben der Liste mit den Befehlen. Sie können entweder eine Liste in der Methode deklarieren oder ein Array der Befehlsnamen wie in der SP.Ribbon.PageState.PageStateHandler.init() Method gezeigt erstellen. Im folgenden Code werden beide Ansätze gezeigt.

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"

Von der SP.Ribbon.PageState.PageStateHandler.isFocusable() Method wird ein Boolean-Wert zurückgegeben, der angibt, ob die Seitenkomponente den Fokus erhalten kann. Falls von dieser Methode false zurückgegeben wird, werden die fokussierten Befehle der Seitenkomponente vom Seiten-Manager nicht registriert.

isFocusable: function CustomPageComponents_MyCustomPageComponent$isFocusable() {
        return true;
    }

"canHandleCommand"

Von der SP.Ribbon.PageState.PageStateHandler.canHandleCommand(commandId) Method wird ein Boolean-Wert zurückgegeben, der angibt, ob die Seitenkomponente die an sie übergebenen Befehle behandeln kann. Für das Zurückgeben eines Werts von dieser Methode sind mehrere Ansätze vorhanden. Wenn Sie eine kleine Anzahl von Befehlen definieren, verwenden Sie eine if-Anweisung oder eine switch-Anweisung. Wenn Sie eine große Anzahl von Befehlen definieren, verwenden Sie ein assoziatives Array von Befehlen, die nach Befehlsnamen indiziert sind. Die unterschiedlichen Ansätze sind im folgenden Code dargestellt.

Verwenden von if-Anweisung und switch-Anweisung.

// 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;
   }
}

Verwenden des Arrays mit Befehlen.

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"

Mit der SP.Ribbon.PageState.PageStateHandler.handleCommand(commandId, properties, sequence) Method wird ein Befehl behandelt, der an die Seitenkomponente übergeben wird. Sie können andere JavaScript-Funktionen aufrufen oder Code in der SP.Ribbon.PageState.PageStateHandler.handleCommand(commandId, properties, sequence) Method schreiben. Für das Behandeln eines Befehls in dieser Methode sind mehrere Ansätze vorhanden. Es wird dieselbe Methode verwendet wie für die SP.Ribbon.PageState.PageStateHandler.canHandleCommand(commandId) Method. Diese beiden Ansätze sind im folgenden Code dargestellt.

Verwenden von if-Anweisung und switch-Anweisung.

// 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;
   }
}

Verwenden des Arrays mit Befehlen.

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);
}

Optionale Methoden für Seitenkomponenten

Die folgenden Methoden sind in der Seitenkomponente optional.

"yieldFocus"

Die SP.Ribbon.PageState.PageStateHandler.yieldFocus() Method wird aufgerufen, wenn die Seitenkomponente den Fokus verliert.

yieldFocus: function CustomPageComponents_MyCustomPageComponent$yieldFocus() {
   alert('The page component has lost focus.');
}

"receiveFocus"

Die SP.Ribbon.PageState.PageStateHandler.receiveFocus() Method wird aufgerufen, wenn die Seitenkomponente den Fokus erhält.

receiveFocus: function CustomPageComponents_MyCustomPageComponent$receiveFocus() {
   alert('The page component has received focus.');
}

Beispiel für eine Seitenkomponente

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");