Erstellen benutzerdefinierter AJAX-Clientsteuerelemente

Aktualisiert: November 2007

In dieser Übersicht wird gezeigt, wie ein benutzerdefiniertes ASP.NET-AJAX-Clientsteuerelement erstellt und in einer Seite verwendet wird. In dieser Übersicht erfahren Sie, wie Sie folgende Aktion ausführen:

• Verwenden des Prototypentwurfsmusters in ECMAScript (JavaScript) zur Definition einer Steuerelementklasse

• Registrieren eines Steuerelements als Klasse, die von der Sys.UI.Control-Basisklasse abgeleitet ist

• Initialisieren der Control-Basisklasse und Aufrufen ihrer Methoden

• Erstellen von benutzerdefinierten Ereignissen, die Seitenentwickler binden und behandeln können

• Verwenden des Clientsteuerelements in einer Seite und Herstellen einer Bindung zu den Ereignissen des Steuerelements

In der Übersicht wird ein Beispiel für ein vollständiges Clientsteuerelement zur Verfügung gestellt, das eine Schaltfläche mit Hoververhalten erstellt.

Der Schwerpunkt dieser Übersicht liegt auf Clientsteuerelementen. In ASP.NET-AJAX stehen drei Clientkomponenten-Objekttypen zur Verfügung:

• Nicht visuelle Komponenten, die von der Sys.Component-Basisklasse abgeleitet sind und auf der Benutzeroberfläche nicht dargestellt werden

• Verhalten, die von Sys.UI.Behavior abgeleitet sind

• Steuerelemente, die von Control abgeleitet sind

In der folgenden Tabelle sind die Unterschiede zwischen Komponenten, Verhalten und Steuerelementen zusammengefasst.

Vorbereitungsmaßnahmen

Zum Ausführen des Beispiels zu Clientsteuerelementen in diesem Thema ist Folgendes erforderlich:

• Eine AJAX-fähige ASP.NET-Website. Wenn Sie bereits über eine solche Site verfügen, können Sie diese für das Beispiel verwenden. Weitere Informationen über das Erstellen eines virtuellen Verzeichnisses oder einer Site finden Sie unter Gewusst wie: Erstellen und Konfigurieren von virtuellen Verzeichnissen in IIS 5.0 und 6.0.

Erstellen der grundlegenden Funktionalität für ein benutzerdefiniertes ASP.NET-AJAX-Clientsteuerelement

Ein ASP.NET-AJAX-Clientsteuerelement stellt ein DOM-Element als Clientobjekt dar und erweitert eine Markupdarstellung oder stellt zusätzliche Funktionen für das Element bereit. Ein Clientsteuerelement kann beispielsweise ein HTML-Element erweitern, um auf Mausereignisse mit unterschiedlichen CSS-Stilen zu reagieren.

Ein Clientsteuerelement kapselt JavaScript-Code, der in unterschiedlichen Anwendungen wiederverwendbar sein soll. Durch Ableitung von der Control-Basisklasse erbt das benutzerdefinierte Steuerelement automatisch viele integrierte browserübergreifende Features, z. B. die folgenden:

• Die Möglichkeit, Ereignishandler für das Steuerelement selbst und für DOM-Elemente, die dem Steuerelement zugeordnet sind, hinzuzufügen oder zu entfernen

• Automatische Registrierung des Steuerelements als verwerfbares Objekt, das die Sys.IDisposable-Schnittstelle implementiert

• Die Möglichkeit, Benachrichtigungsereignisse bei Änderung von Eigenschaften auszulösen

• Die Möglichkeit der Batchverarbeitung von Einstellungen für Steuerelementeigenschaften Auf diese Weise fällt weniger Skriptumfang und Bearbeitungszeit an, als wenn sämtliche Logik in einzelnen get- und set-Accessoren der Eigenschaft behandelt wird.

Implementieren eines Clientsteuerelements

In der folgenden Tabelle werden die Schritte zum Implementieren eines benutzerdefinierten Clientsteuerelements zusammengefasst, das von Control abgeleitet ist. Ausführlichere Informationen zu jedem Schritt finden Sie im Anschluss an die Tabelle.

Definieren einer Steuerelementklasse mit dem Prototypentwurfsmuster

Eine ASP.NET-AJAX-Clientklasse, die eine Komponentenklasse enthält, wird in JavaScript mithilfe des Prototypentwurfsmusters definiert. Weitere Informationen finden Sie unter Erstellen einer Clientkomponentenklasse mit dem Prototypmodell.

Eine Clientsteuerelementklasse muss von der Control-Basisklasse abgeleitet werden. Eine ASP.NET-AJAX-Clientklasse wird als Kasse in der Clientanwendung mit der Type.registerClass-Methode registriert. Weitere Informationen finden Sie unter Type.registerClass-Methode.

Initialisieren der Basisklasse

Das Control-Basisobjekt wird im Konstruktor des Steuerelements initialisiert. Im Konstruktor des Steuerelements wird die geerbte initializeBase-Methode aufgerufen und das im Konstruktorargument empfangene DOM-Element an die Basisklasse übergeben. Normalerweise wird die initializeBase-Methode aufgerufen, bevor anderer Code im Konstruktor ausgeführt wird. Wenn die Control-Basisklasse initialisiert wird, sind ihre Methoden für das Steuerelement verfügbar. Außerdem wird das Steuerelement automatisch als verwerfbares Objekt in der Sys.Application-Instanz registriert. Weitere Informationen finden Sie unter Sys.IDisposable-Schnittstelle.

Im folgenden Beispiel wird eine Konstruktorfunktion für ein Steuerelement veranschaulicht, das von Control abgeleitet ist. Der Komponentenkonstruktor ruft die geerbte initializeBase-Methode auf.

Samples.SimpleControl = function(element)
{
    Samples.SimpleControl.initializeBase(this, [element]);
}

Definieren von Eigenschaften und Auslösen von Benachrichtigungen für Eigenschaftenänderungen

Eigenschaften werden in der Steuerelementklasse des Clients definiert. Diese Eigenschaften können von Seitenentwicklern abgerufen und festgelegt werden. Sie können auch propertyChanged-Benachrichtigungsereignisse für die Eigenschaften der Komponente auslösen. Wenn Seitenentwickler Ihre Komponente verwenden, können sie Bindungen zu diesen Ereignissen herstellen. Eine von den Basisklassen Component, Behavior oder Control abgeleitete ASP.NET-AJAX-Komponente erbt die Sys.Component.raisePropertyChanged-Methode, die zum Auslösen eines propertyChanged-Ereignisses aufgerufen wird. Weitere Informationen finden Sie unter Definieren von benutzerdefinierten Komponenteneigenschaften und Auslösen von PropertyChanged-Ereignissen.

Initialisieren von Eigenschaften und Ereignislistenern

Überschreiben Sie die initialize-Methode im Komponentenprototyp, wenn für das benutzerdefinierte Steuerelement Eigenschaften oder Eventlistener initialisiert werden müssen. Ein von der Control-Basisklasse abgeleitetes Clientsteuerelement bindet in der Regel alle Handler an seine DOM-Elementereignisse und legt die Anfangswerte für die Eigenschaften der DOM-Elemente fest. Im letzten Schritt rufen Sie die initialize-Basismethode auf, damit die Basisklasse der Komponente die Initialisierung abschließen kann.

Freigeben von Ressourcen

Überschreiben Sie die dispose-Methode, wenn vor der Freigabe des benutzerdefinierten Steuerelements Ressourcen freigegeben werden müssen, und geben Sie die Ressourcen in der überschriebenen Methode frei. Dadurch wird sichergestellt, dass die Ressourcen unmittelbar vor der Freigabe des Steuerelements freigegeben werden. Freizugebende Ressourcen sind u. a. Handler, die zum Binden von DOM-Ereignissen verwendet werden. Indem Sie überprüfen, dass alle vorhandenen Zirkelverweise zwischen DOM-Elementen und dem Komponentenobjekt entfernt wurden, stellen Sie sicher, dass das Objekt aus dem Speicher entfernt werden kann. Weitere Informationen finden Sie unter Freigeben von Komponentenressourcen.

Verwenden eines Steuerelements in einer Seite

Gehen Sie folgendermaßen vor, um ein benutzerdefiniertes Clientsteuerelement in einer ASP.NET-Webseite zu verwenden:

• Registrieren Sie die Skriptbibliothek des Clientsteuerelements in der Webseite.

• Erstellen Sie eine Clientsteuerelementinstanz.

Die folgenden Abschnitte enthalten ausführliche Informationen zu diesen Schritten.

Registrieren der Skriptbibliothek eines Steuerelements in der Webseite.

Die erforderlichen Skripts für ein Clientsteuerelement auf der Seite können mit dem ScriptManager-Steuerelement entweder deklarativ oder programmgesteuert registriert werden.

Im folgenden Beispiel wird das deklarative Markup für ein ScriptManager-Steuerelement veranschaulicht, das ein Steuerelementskript registriert.

<form id="form1" >
  <asp:ScriptManager  ID="ScriptManager01">
    <scripts>
      <asp:ScriptReference path="HoverButton.js" />
    </scripts>
  </asp:ScriptManager>
</form>

Das asp:ScriptManager-Element enthält ein asp:ScriptReference-Element in einem scripts-Knoten. Das path-Attribut des asp:ScriptReference-Elements verweist auf den Pfad der Datei HoverButton.js, in der eine Steuerelementklasse definiert ist. Weitere Informationen finden Sie unter Dynamisches Zuweisen von Skriptverweisen sowie in der Übersicht über die ScriptManager-Klasse.

Hinweis:

Alle für das ScriptManager-Steuerelement zu registrierenden eigenständigen Skriptdateien, müssen die notifyScriptLoaded-Methode aufrufen, um die Anwendung über das Beenden des Skriptladevorgangs zu benachrichtigen. In einer Assembly eingebettete Skripts sollten die Methode in den meisten Fällen nicht aufrufen. Weitere Informationen hierzu finden Sie unter Sys.Application.notifyScriptLoaded-Methode.

Als Alternative zum Registrieren von Skriptdateien mit dem ScriptManager-Steuerelement können Sie Clientkomponenten mit einem benutzerdefinierten Serversteuerelement verwalten, das die IScriptControl-Schnittstelle implementiert. Ein benutzerdefiniertes Serversteuerelement kann die erforderlichen Komponentenskripts automatisch registrieren und das deklarative Markup zum Festlegen von Komponenteneigenschaften und Ereignisbindungen verfügbar machen. Dies vereinfacht das Verwenden Ihres benutzerdefinierten Steuerelements für Seitenentwickler. Weitere Informationen finden Sie in der Übersicht über die IScriptControl-Klasse.

Erstellen einer benutzerdefinierten Steuerelementinstanz

Ein benutzerdefiniertes Clientsteuerelement wird durch Aufrufen der Sys.Component.create-Methode oder mithilfe der Verknüpfung $create während des Sys.Application.init-Ereignisses instanziiert. In der folgenden Tabelle werden die Parameter beschrieben, die beim Erstellen eines Clientsteuerelements an die $create-Methode übergeben werden.

Im folgenden Beispiel wird gezeigt, wie eine Steuerelementinstanz durch Aufrufen der $create-Methode instanziiert wird.

$create(Demo.HoverButton, {text: 'A HoverButton Control',element: {style: {fontWeight: "bold", borderWidth: "2px"}}}, {click: start, hover: doSomethingOnHover, unhover: doSomethingOnUnHover},null, $get('Button1'));

Weitere Informationen finden Sie unter Sys.Component.create-Methode und unter Sys.Component $create-Methode.

Erstellen eines benutzerdefinierten HoverButton-Steuerelements

In diesem Abschnitt erstellen Sie ein einfaches benutzerdefiniertes Clientsteuerelement mit der Bezeichnung HoverButton, mit dem die Control-Basisklasse erweitert wird. Anschließend wird das Steuerelement in einer Seite verwendet. Das HoverButton-Steuerelement fängt die Ereignisse click, focus und mouseover des zugeordneten button-HTML-Elements ab. Außerdem stellt es über die $create-Methode bindbare Ereignisse für die Steuerelemente bereit. Ein Seitenentwickler, der das HoverButton-Steuerelement verwendet, kann Bindungen zum hover-Ereignis des Steuerelements herstellen.

So erstellen Sie den Code für das HoverButton-Steuerelement

1. Erstellen Sie im Stammverzeichnis einer AJAX-aktivierten ASP.NET-Website eine Datei mit dem Namen HoverButton.js.

2. Fügen Sie folgenden Code in die Datei ein:

   Type.registerNamespace("Demo");
   
   // Constructor
   Demo.HoverButton = function(element) {
   
       Demo.HoverButton.initializeBase(this, [element]);
   
       this._clickDelegate = null;
       this._hoverDelegate = null;
       this._unhoverDelegate = null;
   }
   Demo.HoverButton.prototype = {
   
       // text property accessors.
       get_text: function() {
           return this.get_element().innerHTML;
       },
       set_text: function(value) {
           this.get_element().innerHTML = value;
       },
   
       // Bind and unbind to click event.
       add_click: function(handler) {
           this.get_events().addHandler('click', handler);
       },
       remove_click: function(handler) {
           this.get_events().removeHandler('click', handler);
       },
   
       // Bind and unbind to hover event.
       add_hover: function(handler) {
           this.get_events().addHandler('hover', handler);
       },
       remove_hover: function(handler) {
           this.get_events().removeHandler('hover', handler);
       },
   
       // Bind and unbind to unhover event.
       add_unhover: function(handler) {
           this.get_events().addHandler('unhover', handler);
       },
       remove_unhover: function(handler) {
           this.get_events().removeHandler('unhover', handler);
       },
   
       // Release resources before control is disposed.
       dispose: function() {
   
           var element = this.get_element();
   
           if (this._clickDelegate) {
               Sys.UI.DomEvent.removeHandler(element, 'click', this._clickDelegate);
               delete this._clickDelegate;
           }
   
           if (this._hoverDelegate) {
               Sys.UI.DomEvent.removeHandler(element, 'focus', this._hoverDelegate);
               Sys.UI.DomEvent.removeHandler(element, 'mouseover', this._hoverDelegate);
               delete this._hoverDelegate;
           }
   
           if (this._unhoverDelegate) {
               Sys.UI.DomEvent.removeHandler(element, 'blur', this._unhoverDelegate);
               Sys.UI.DomEvent.removeHandler(element, 'mouseout', this._unhoverDelegate);
               delete this._unhoverDelegate;
           }
           Demo.HoverButton.callBaseMethod(this, 'dispose');
       },
   
       initialize: function() {
   
           var element = this.get_element();
   
           if (!element.tabIndex) element.tabIndex = 0;
   
           if (this._clickDelegate === null) {
               this._clickDelegate = Function.createDelegate(this, this._clickHandler);
           }
           Sys.UI.DomEvent.addHandler(element, 'click', this._clickDelegate);
   
           if (this._hoverDelegate === null) {
               this._hoverDelegate = Function.createDelegate(this, this._hoverHandler);
           }
           Sys.UI.DomEvent.addHandler(element, 'mouseover', this._hoverDelegate);
           Sys.UI.DomEvent.addHandler(element, 'focus', this._hoverDelegate);
   
           if (this._unhoverDelegate === null) {
               this._unhoverDelegate = Function.createDelegate(this, this._unhoverHandler);
           }
           Sys.UI.DomEvent.addHandler(element, 'mouseout', this._unhoverDelegate);
           Sys.UI.DomEvent.addHandler(element, 'blur', this._unhoverDelegate);
   
           Demo.HoverButton.callBaseMethod(this, 'initialize');
   
       },
       _clickHandler: function(event) {
           var h = this.get_events().getHandler('click');
           if (h) h(this, Sys.EventArgs.Empty);
       },
       _hoverHandler: function(event) {
           var h = this.get_events().getHandler('hover');
           if (h) h(this, Sys.EventArgs.Empty);
       },
       _unhoverHandler: function(event) {
           var h = this.get_events().getHandler('unhover');
           if (h) h(this, Sys.EventArgs.Empty);
       }
   }
   Demo.HoverButton.registerClass('Demo.HoverButton', Sys.UI.Control);
   
   // Since this script is not loaded by System.Web.Handlers.ScriptResourceHandler
   // invoke Sys.Application.notifyScriptLoaded to notify ScriptManager 
   // that this is the end of the script.
   if (typeof(Sys) !== 'undefined') Sys.Application.notifyScriptLoaded();
   
   

Codeerläuterung

Mit dem Code wird der Demo-Namespace durch Aufrufen der Type.registerNamespace-Methode registriert. Die geerbte initializeBase-Methode wird vom Konstruktor aufgerufen, damit die Control-Basisklassenmethoden verfügbar sind. Die initialisierte Basisklasse registriert in der Clientanwendung wiederum die Demo.HoverButton-Instanz als verwerfbares Objekt.

Im Prototyp deklariert der Code die öffentlichen Ereignisse click, hover und unhover. Seitenentwickler können Handler zum Überwachen dieser Ereignisse hinzufügen und entfernen. Mithilfe der Ereignishandlerauflistung des Steuerelements entfernen diese Methoden wiederum den angegebenen Handler oder fügen diesen hinzu. Mit dem Sys.EventHandlerList-Objekt des Steuerelements können Handler der Steuerelementklasse hinzugefügt oder aus dieser entfernt werden. Durch die geerbte Sys.Component.events-Eigenschaft enthält das EventHandlerList-Objekt eine Auflistung der Ereignishandler des Steuerelements. Im Beispiel werden über den Code die Methoden Sys.EventHandlerList.addHandler und Sys.EventHandlerList.removeHandler des zurückgegebenen EventHandlerList-Objekts aufgerufen, um Handler hinzuzufügen oder zu entfernen.

Die HoverButton-Klasse überschreibt die dispose-Basismethode, um vor dem Freigeben des Steuerelements auf sichere Weise alle Steuerelementressourcen (z. B. Handler für DOM-Ereignisse) freizugeben. Im Code wird abschließend die dispose-Basismethode aufgerufen, damit die Anwendung das Steuerelement freigeben kann.

Verwenden des HoverButton-Steuerelements in einer Webseite

In diesem Abschnitt erfahren Sie, wie eine Steuerelementinstanz mithilfe von Clientskript in einer Webseite erstellt wird.

So erstellen Sie eine Seite, um das HoverButton-Steuerelement zu verwenden

1. Erstellen Sie im Stammverzeichnis der Anwendung, in dem die Datei HoverButton.js gespeichert ist, eine Datei mit dem Namen DemoHoverButton.aspx.

2. Fügen Sie der Datei das folgende Markup und den folgenden Code hinzu:

   <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   
   <html xmlns="http://www.w3.org/1999/xhtml" >
   <head id="Head1" >
   
       <style type="text/css">
           button {border: solid 1px black}
           #HoverLabel {color: blue}
       </style>
       <title>Control Demo</title>
   </head>
   <body>
       <form id="form1" >
           <div id="ResultDisplay"></div>
   
               <asp:ScriptManager  ID="ScriptManager01">
                   <scripts>
                      <asp:ScriptReference Path="HoverButton.js" />
                   </scripts>
               </asp:ScriptManager>
   
               <script type="text/javascript">
                   var app = Sys.Application;
                   app.add_init(applicationInitHandler);
   
                   function applicationInitHandler(sender, args) {
                       $create(Demo.HoverButton, {text: 'A HoverButton Control',element: {style: {fontWeight: "bold", borderWidth: "2px"}}}, {click: start, hover: doSomethingOnHover, unhover: doSomethingOnUnHover},null, $get('Button1'));
                   }
   
                   function doSomethingOnHover(sender, args) {
                       hoverMessage = "The mouse is over the button."
                       $get('HoverLabel').innerHTML = hoverMessage;
                   }
   
                   function doSomethingOnUnHover(sender, args) {
                      $get('HoverLabel').innerHTML = "";
                   }
   
                   function start(sender, args) {
                      alert("The start function handled the HoverButton click event.");
                   }
               </script>
   
               <button type="button" id="Button1"></button>&nbsp;
           <div id="HoverLabel"></div>
       </form>
   
   </body>
   </html>
   

Codeerläuterung

Die Datei DemoHoverButton.aspx ist eine ASP.NET-Webseite und Host des benutzerdefinierten Steuerelements. Im script-Element dieser Seite sind die Funktionen definiert, die in das benutzerdefinierte Steuerelement eingebunden sind. Im Sys.Application.init-Ereignishandler wird das HoverButton-Steuerelement in Clientskript instanziiert, indem die $create-Methode aufgerufen wird. Im Code werden die folgenden Argumente an die $create-Methode übergeben:

• Das type-Argument enthält die Demo.HoverButton-Klasse, die Sie zuvor erstellt haben.

• Das properties-Argument enthält ein JSON-Objekt, in dem der erforderliche ID-Wert des Steuerelements und Name-Wert-Paare, die Eigenschafsnamen und Anfangswerte angeben, enthalten sind.

• Das events-Argument enthält ein Objekt, das Ereignisnamen paarweise mit den zugeordneten Handlern enthält.

Im ScriptManager-Steuerelement verweist das path-Attribut des asp:ScriptReference-Knotens auf den Pfad der Datei HoverButton.js, in der die Demo.HoverButton-Steuerelementklasse definiert ist.

Festlegen von Ereignishandlern für DOM-Elemente und für Komponenten

AJAX-Funktionalität in ASP.NET umfasst Klassen, die standardisierte Ereignisverwaltung für Komponenten und DOM-Elemente zur Verfügung stellen. Die Ereignisse des Steuerelements werden mithilfe von Membern der Sys.EventHandlerList-Klasse verwaltet, wie z. B. addHandler und removeHandler. Weitere Informationen finden Sie in der Übersicht über die Sys.EventHandlerList-Klasse.

Ereignishandler für DOM-Elemente oder für Ereignisse des window-Objekts werden mithilfe der statischen Methoden der Klassen Sys.UI.DomEvent, addHandler oder removeHandler verwaltet. Weitere Informationen finden Sie in der Übersicht über die Sys.UI.DomEvent-Klasse.

Zugreifen auf DOM-Elementeigenschaften

Die Sys.UI.DomElement-Klasse enthält Member, mit denen CSS-Klassenverknüpfungen für Clientsteuerelemente und für Clientelemente hinzugefügt, entfernt und ein- oder ausgeschaltet werden können. Diese Member stellen ebenfalls standardisierten Zugriff auf DOM-Elementeigenschaften bereit. Weitere Informationen finden Sie unter Sys.UI.DomElement-Klasse.

Siehe auch

Aufgaben

Erstellen von benutzerdefinierten nicht visuellen Clientkomponenten

Dynamisches Zuweisen von Skriptverweisen

Konzepte

Verwenden des ASP.NET UpdatePanel-Steuerelements mit datengebundenen Steuerelementen

Arbeiten mit PageRequestManager-Ereignissen

Referenz

Sys.Component-Klasse

ScriptManager