Hinzufügen von Clientfunktionen zu einem Webserversteuerelement
Aktualisiert: November 2007
Mit den AJAX-Funktionen von ASP.NET können Sie die Fähigkeiten einer Webanwendung erweitern, um eine hohe Benutzerfreundlichkeit zu erreichen. Sie können die ECMAScript (JavaScript)-, DHTML- und AJAX-Fähigkeiten des Webbrowsers nutzen, um visuelle Effekte, clientseitige Verarbeitung (wie Überprüfungen) usw. zu verwenden.
In diesem Thema erfahren Sie, wie Sie ein benutzerdefiniertes Webserversteuerelement erstellen, das mithilfe der AJAX-Features von ASP.NET die Funktionen im Browser erweitert. Sie können DOM (Document Object Model)-Clientelementen Funktionen hinzufügen, indem Sie ein Clientsteuerelement verwenden. Das Clientsteuerelement kann einem Serversteuerelement zugeordnet werden, indem die IScriptControl-Schnittstelle im Serversteuerelement implementiert wird.
In diesem Thema erfahren Sie, wie Sie folgende Aktionen ausführen:
Erstellen eines Webserversteuerelements, das Clientverhalten kapselt und Eigenschaften enthält, die von Benutzern festgelegt werden können, um das Verhalten zu steuern.
Erstellen eines Clientsteuerelements, das dem Webserversteuerelement zugeordnet ist.
Behandeln von Ereignissen aus dem Browser-DOM im Clientsteuerelement.
.gif "Hinweis")
Hinweis:Sie können Webserversteuerelementen auch Rich Client-Fähigkeiten durch Erstellen eines Extendersteuerelements hinzufügen. Dieses Extendersteuerelement kapselt Clientfunktionen in einem Verhalten und kann dann mit einem Webserversteuerelement verbunden werden. Da ein Extendersteuerelement nicht Teil des ihm zugeordneten Steuerelements ist, können Sie ein einzelnes Extendersteuerelement erstellen, das mehreren Arten von Webserversteuerelementen zugeordnet werden kann. Ein Beispiel finden Sie unter Erstellen eines Extendersteuerelements zum Zuordnen eines Clientverhaltens zu einem Webserversteuerelement.
Kompilieren des benutzerdefinierten Webserversteuerelements in eine Assembly und Einbetten zugehöriger JavaScript-Dateien in diese Assembly als Ressourcen.
Verweisen auf das kompilierte benutzerdefinierte Webserversteuerelement in einer ASP.NET AJAX-fähigen Webseite.
Ermitteln der Clientanforderungen
Wenn Sie einem Webserversteuerelement Clientverhalten hinzufügen möchten, müssen Sie zunächst entscheiden, welches Verhalten das Steuerelement im Browser aufweisen soll. Dann können Sie die Clientfunktionen bestimmen, die zum Implementieren des Verhaltens benötigt werden.
Das Webserversteuerelement, das in diesem Thema erstellt wird, implementiert ein einfaches Clientverhalten. Das Steuerelement (ein TextBox-Steuerelement) wird hervorgehoben, wenn es im Browser ausgewählt wird (oder den Fokus hat). So kann sich beispielsweise die Hintergrundfarbe des Steuerelements ändern, wenn es den Fokus erhält, und dann wieder zur Standardfarbe zurückkehren, wenn der Fokus zu einem anderen Steuerelement wechselt.
Zum Implementieren dieses Verhaltens muss das Clientsteuerelement aus diesem Thema die in der nachfolgenden Tabelle aufgeführten Fähigkeiten und Funktionen besitzen:
Die Fähigkeit, ein DOM-Element hervorzuheben.
Zum Hervorheben eines DOM-Elements auf einer ASP.NET-Webseite wendet das Clientsteuerelement einen Cascading Stylesheet-Stil an, der über einen Klassennamen identifiziert wird. Dieser Stil kann vom Benutzer konfiguriert werden.Die Fähigkeit, das DOM-Element wieder in seinen nicht hervorgehobenen Zustand zurückzusetzen.
Zum Aufheben der Hervorhebung eines DOM-Elements auf einer ASP.NET-Webseite wendet das Clientsteuerelement einen CSS-Stil an, der durch einen Klassennamen identifiziert wird. Dieser Stil kann vom Benutzer konfiguriert werden und wird als Standardstil auf das DOM-Element angewendet.Die Fähigkeit zum Ermitteln, dass ein DOM-Element ausgewählt wurde.
Um ermitteln zu können, wann ein DOM-Element ausgewählt wird (den Fokus erhält), verarbeitet das Steuerelement das onfocus-Ereignis des DOM-Elements.Die Fähigkeit zum Ermitteln, wann ein DOM-Element nicht mehr ausgewählt ist.
Um ermitteln zu können, wenn ein Steuerelement nicht mehr ausgewählt ist, verarbeitet das Steuerelement das onblur-Ereignis des DOM-Elements.
Erstellen des Webserversteuerelements
Ein Webserversteuerelement, das unter Verwendung von ASP.NET AJAX-Funktionen Clientfeatures einschließt, ist ein Webserversteuerelement wie jedes andere. Allerdings implementiert das Steuerelement auch die IScriptControl-Schnittstelle aus dem System.Web.UI-Namespace. Das Steuerelement in diesem Thema erweitert das ASP.NET-TextBox-Steuerelement, indem es die TextBox-Klasse erbt und die IScriptControl-Schnittstelle implementiert.
Das folgende Beispiel zeigt die Klassendefinition.
Public Class SampleTextBox
Inherits TextBox
Implements IScriptControl
public class SampleTextBox : TextBox, IScriptControl
Das neue Webserversteuerelement enthält zwei Eigenschaften, die zum Implementieren der Clientanforderungen dienen:
HighlightCssClass, die die CSS-Klasse identifiziert, die auf das DOM-Element angewendet werden soll, um das Steuerelement hervorzuheben, wenn es den Fokus besitzt.
NoHighlightCssClass, die die CSS-Klasse identifiziert, die auf das DOM-Element angewendet werden soll, wenn es nicht den Fokus besitzt.
Implementieren der IScriptControl-Schnittstelle
In der folgende Tabelle sind Member der IScriptControl-Schnittstelle aufgeführt, die Sie in einem Webserversteuerelement implementieren müssen.
GetScriptDescriptors
Gibt eine Auflistung von ScriptDescriptor-Objekten zurück, die Informationen zu Instanzen von Clientkomponenten enthalten, die mit dem Webserversteuerelement verwendet werden. Dazu gehören der Clienttyp, der erstellt werden soll, die Eigenschaften, die zugewiesen werden sollen, und die Ereignisse, für die Handler hinzugefügt werden sollen.GetScriptReferences
Gibt eine Auflistung von ScriptReference-Objekten zurück, die Informationen zu den Clientskriptbibliotheken enthalten, die das Steuerelement enthalten soll. Die Clientskriptbibliotheken definieren die Clienttypen und jeden anderen JavaScript-Code, der für das Verhalten erforderlich ist.
Mithilfe der GetScriptDescriptors-Methode definiert das Webserversteuerelement in diesem Thema die Instanz des Clientsteuerelementtyps. Das Steuerelement erstellt ein neues ScriptControlDescriptor-Objekt (die ScriptControlDescriptor-Klasse ist von der ScriptDescriptor-Klasse abgeleitet) und schließt das Objekt in den Rückgabewert für die GetScriptDescriptors-Methode ein.
Das ScriptControlDescriptor-Objekt enthält den Namen der Clientklasse (Samples.SampleTextBox) und den ClientID-Wert für das Webserversteuerelement. Dieser Wert wird als id-Wert für das gerenderte DOM-Element verwendet. Der Name der Clientklasse und die ClientID-Eigenschaftenwerte werden an den Konstruktor für das ScriptControlDescriptor-Objekt übergeben.
Die ScriptControlDescriptor-Klasse wird zum Festlegen der Eigenschaftenwerte des Clientsteuerelements verwendet, die aus Eigenschaften des Webserversteuerelements abgerufen werden. Zum Definieren der Eigenschaften des Clientsteuerelements verwendet das Webserversteuerelement die ScriptComponentDescriptor.AddProperty-Methode der ScriptControlDescriptor-Klasse. Anschließend gibt das Webserversteuerelement einen Namen und einen Wert für die Eigenschaft des Clientsteuerelements auf Basis der entsprechenden Eigenschaft des Webserversteuerelements an. In diesem Beispiel wird ein ScriptControlDescriptor-Objekt verwendet, um die Werte der highlightCssClass-Eigenschaft und der nohighlightCssClass-Eigenschaft im Clientsteuerelement festzulegen.
Das Webserversteuerelement übergibt das ScriptControlDescriptor-Objekt im Rückgabewert der GetScriptDescriptors-Methode. Daher rendert ASP.NET jedes Mal, wenn das Webserversteuerelement für den Browser gerendert wird, JavaScript, das eine Instanz des Clientsteuerelements mit allen definierten Eigenschaften und Ereignishandlern erstellt. Die Steuerelementinstanz wird gemäß der vom Webserversteuerelement gerenderten ClientID-Eigenschaft an das DOM-Element angefügt. Das folgende Beispiel zeigt deklaratives ein ASP.NET-Markup, in dem das Webserversteuerelement aus diesem Thema auf einer Seite enthalten ist.
<sample:SampleTextBox
ID="SampleTextBox1"
HighlightCssClass="MyHighLight"
NoHighlightCssClass="MyLowLight" />
Die gerenderte Ausgabe der Seite enthält einen Aufruf der $create-Methode, die die zu erstellende Clientklasse identifiziert. Außerdem werden Werte für die Clienteigenschaften und der id-Wert des DOM-Objekts zur Verfügung gestellt, dem das Clientsteuerelement zugeordnet ist. Das folgende Beispiel zeigt eine gerenderte $create-Methode.
$create(Samples.SampleTextBox, {"highlightCssClass":"MyHighLight","nohighlightCssClass":"MyLowLight"}, null, null, $get('SampleTextBox1'));
Im Beispiel-Webserversteuerelement wird mit der GetScriptReferences-Methode der Speicherort der Skriptbibliothek übergeben, die den Typ des Clientsteuerelements definiert. In diesem Beispiel ist dies eine URL zur Skriptdatei SampleTextBox.js, die noch erstellt wird. Der Verweis erfolgt durch Erstellen eines neuen ScriptReference-Objekts und durch anschließendes Festlegen der Path-Eigenschaft auf die URL der Datei, die den Clientcode enthält.
Das folgende Beispiel zeigt die Implementierungen der GetScriptDescriptors-Methode und der GetScriptReferences-Methode.
Protected Overridable Function GetScriptReferences() As IEnumerable(Of ScriptReference)
Dim reference As ScriptReference = New ScriptReference()
reference.Path = ResolveClientUrl("SampleTextBox.js")
Return New ScriptReference() {reference}
End Function
Protected Overridable Function GetScriptDescriptors() As IEnumerable(Of ScriptDescriptor)
Dim descriptor As ScriptControlDescriptor = New ScriptControlDescriptor("Samples.SampleTextBox", Me.ClientID)
descriptor.AddProperty("highlightCssClass", Me.HighlightCssClass)
descriptor.AddProperty("nohighlightCssClass", Me.NoHighlightCssClass)
Return New ScriptDescriptor() {descriptor}
End Function
Function IScriptControlGetScriptReferences() As IEnumerable(Of ScriptReference) Implements IScriptControl.GetScriptReferences
Return GetScriptReferences()
End Function
Function IScriptControlGetScriptDescriptors() As IEnumerable(Of ScriptDescriptor) Implements IScriptControl.GetScriptDescriptors
Return GetScriptDescriptors()
End Function
protected virtual IEnumerable<ScriptReference> GetScriptReferences()
{
ScriptReference reference = new ScriptReference();
reference.Path = ResolveClientUrl("SampleTextBox.js");
return new ScriptReference[] { reference };
}
protected virtual IEnumerable<ScriptDescriptor> GetScriptDescriptors()
{
ScriptControlDescriptor descriptor = new ScriptControlDescriptor("Samples.SampleTextBox", this.ClientID);
descriptor.AddProperty("highlightCssClass", this.HighlightCssClass);
descriptor.AddProperty("nohighlightCssClass", this.NoHighlightCssClass);
return new ScriptDescriptor[] { descriptor };
}
IEnumerable<ScriptReference> IScriptControl.GetScriptReferences()
{
return GetScriptReferences();
}
IEnumerable<ScriptDescriptor> IScriptControl.GetScriptDescriptors()
{
return GetScriptDescriptors();
}
Registrieren des Clientsteuerelements
Clientsteuerelemente müssen mit dem ScriptManager-Objekt für die aktuelle Seite registriert werden. Dies wird durch Aufruf der RegisterScriptControl<TScriptControl>-Methode der ScriptManager-Klasse und durch Angabe eines Verweises auf das Clientsteuerelement erreicht.
Das Beispiel-Webserversteuerelement registriert sich selbst mit dem auf der Seite vorhandenen ScriptManager-Steuerelement als Clientsteuerelement. Zu diesem Zweck überschreibt das Steuerelement die OnPreRender-Methode des TextBox-Basissteuerelements. Anschließend ruft es die RegisterScriptControl()-Methode auf, um sich als Clientsteuerelement zu registrieren. Darüber hinaus registriert das Steuerelement die Skriptdeskriptoren, die von der GetScriptDescriptors-Methode erstellt werden. Dazu ruft es die RegisterScriptDescriptors()-Methode in der Render-Methode des Steuerelements auf.
Das folgende Beispiel zeigt die Aufrufe der RegisterScriptControl()-Methode und der RegisterScriptDescriptors()-Methode.
Protected Overrides Sub OnPreRender(ByVal e As EventArgs)
If Not Me.DesignMode Then
' Test for ScriptManager and register if it exists
sm = ScriptManager.GetCurrent(Page)
If sm Is Nothing Then _
Throw New HttpException("A ScriptManager control must exist on the current page.")
sm.RegisterScriptControl(Me)
End If
MyBase.OnPreRender(e)
End Sub
Protected Overrides Sub Render(ByVal writer As HtmlTextWriter)
If Not Me.DesignMode Then _
sm.RegisterScriptDescriptors(Me)
MyBase.Render(writer)
End Sub
protected override void OnPreRender(EventArgs e)
{
if (!this.DesignMode)
{
// Test for ScriptManager and register if it exists
sm = ScriptManager.GetCurrent(Page);
if (sm == null)
throw new HttpException("A ScriptManager control must exist on the current page.");
sm.RegisterScriptControl(this);
}
base.OnPreRender(e);
}
protected override void Render(HtmlTextWriter writer)
{
if (!this.DesignMode)
sm.RegisterScriptDescriptors(this);
base.Render(writer);
}
Das folgende Beispiel enthält den vollständigen Code für das Webserversteuerelement.
Imports System
Imports System.Data
Imports System.Configuration
Imports System.Web
Imports System.Web.Security
Imports System.Web.UI
Imports System.Web.UI.WebControls
Imports System.Web.UI.WebControls.WebParts
Imports System.Web.UI.HtmlControls
Imports System.Collections.Generic
Namespace Samples.VB
Public Class SampleTextBox
Inherits TextBox
Implements IScriptControl
Private _highlightCssClass As String
Private _noHighlightCssClass As String
Private sm As ScriptManager
Public Property HighlightCssClass() As String
Get
Return _highlightCssClass
End Get
Set(ByVal value As String)
_highlightCssClass = value
End Set
End Property
Public Property NoHighlightCssClass() As String
Get
Return _noHighlightCssClass
End Get
Set(ByVal value As String)
_noHighlightCssClass = value
End Set
End Property
Protected Overrides Sub OnPreRender(ByVal e As EventArgs)
If Not Me.DesignMode Then
' Test for ScriptManager and register if it exists
sm = ScriptManager.GetCurrent(Page)
If sm Is Nothing Then _
Throw New HttpException("A ScriptManager control must exist on the current page.")
sm.RegisterScriptControl(Me)
End If
MyBase.OnPreRender(e)
End Sub
Protected Overrides Sub Render(ByVal writer As HtmlTextWriter)
If Not Me.DesignMode Then _
sm.RegisterScriptDescriptors(Me)
MyBase.Render(writer)
End Sub
Protected Overridable Function GetScriptReferences() As IEnumerable(Of ScriptReference)
Dim reference As ScriptReference = New ScriptReference()
reference.Path = ResolveClientUrl("SampleTextBox.js")
Return New ScriptReference() {reference}
End Function
Protected Overridable Function GetScriptDescriptors() As IEnumerable(Of ScriptDescriptor)
Dim descriptor As ScriptControlDescriptor = New ScriptControlDescriptor("Samples.SampleTextBox", Me.ClientID)
descriptor.AddProperty("highlightCssClass", Me.HighlightCssClass)
descriptor.AddProperty("nohighlightCssClass", Me.NoHighlightCssClass)
Return New ScriptDescriptor() {descriptor}
End Function
Function IScriptControlGetScriptReferences() As IEnumerable(Of ScriptReference) Implements IScriptControl.GetScriptReferences
Return GetScriptReferences()
End Function
Function IScriptControlGetScriptDescriptors() As IEnumerable(Of ScriptDescriptor) Implements IScriptControl.GetScriptDescriptors
Return GetScriptDescriptors()
End Function
End Class
End Namespace
using System;
using System.Data;
using System.Configuration;
using System.Web;
using System.Web.Security;
using System.Web.UI;
using System.Web.UI.WebControls;
using System.Web.UI.WebControls.WebParts;
using System.Web.UI.HtmlControls;
using System.Collections.Generic;
namespace Samples.CS
{
public class SampleTextBox : TextBox, IScriptControl
{
private string _highlightCssClass;
private string _noHighlightCssClass;
private ScriptManager sm;
public string HighlightCssClass
{
get { return _highlightCssClass; }
set { _highlightCssClass = value; }
}
public string NoHighlightCssClass
{
get { return _noHighlightCssClass; }
set { _noHighlightCssClass = value; }
}
protected override void OnPreRender(EventArgs e)
{
if (!this.DesignMode)
{
// Test for ScriptManager and register if it exists
sm = ScriptManager.GetCurrent(Page);
if (sm == null)
throw new HttpException("A ScriptManager control must exist on the current page.");
sm.RegisterScriptControl(this);
}
base.OnPreRender(e);
}
protected override void Render(HtmlTextWriter writer)
{
if (!this.DesignMode)
sm.RegisterScriptDescriptors(this);
base.Render(writer);
}
protected virtual IEnumerable<ScriptReference> GetScriptReferences()
{
ScriptReference reference = new ScriptReference();
reference.Path = ResolveClientUrl("SampleTextBox.js");
return new ScriptReference[] { reference };
}
protected virtual IEnumerable<ScriptDescriptor> GetScriptDescriptors()
{
ScriptControlDescriptor descriptor = new ScriptControlDescriptor("Samples.SampleTextBox", this.ClientID);
descriptor.AddProperty("highlightCssClass", this.HighlightCssClass);
descriptor.AddProperty("nohighlightCssClass", this.NoHighlightCssClass);
return new ScriptDescriptor[] { descriptor };
}
IEnumerable<ScriptReference> IScriptControl.GetScriptReferences()
{
return GetScriptReferences();
}
IEnumerable<ScriptDescriptor> IScriptControl.GetScriptDescriptors()
{
return GetScriptDescriptors();
}
}
}
Erstellen des Clientsteuerelements
Im Webserversteuerelement gibt die GetScriptReferences-Methode eine JavaScript-Datei (SampleTextBox.js) an, die den Clientcode für den Steuerelementtyp enthält. In diesem Abschnitt wird der JavaScript-Code in dieser Datei beschrieben.
Der Clientsteuerelementcode stimmt mit den in den ScriptDescriptor-Objekten angegebenen Membern überein, die von der GetScriptDescriptors-Methode zurückgegeben werden. Ein Clientsteuerelement kann auch Member besitzen, die nicht Membern in der Webserversteuerelementklasse entsprechen.
Das Beispiel-Webserversteuerelement legt den Namen für das Clientsteuerelement auf Samples.SampleTextBox fest und definiert zwei Eigenschaften des Clientsteuerelements: highlightCssClass und nohighlightCssClass.
Weitere Informationen zum Erstellen von Clientkomponenten und Clientsteuerelementen finden Sie unter Erstellen einer Clientkomponentenklasse mit dem Prototypmodell.
Registrieren des Clientnamespaces
Im Clientsteuerelementcode muss zuerst die registerNamespace-Methode der Type-Klasse aufgerufen werden, um den Namespace (Samples) zu registrieren. Das folgende Beispiel zeigt, wie der Clientnamespace registriert wird.
// Register the namespace for the control.
Type.registerNamespace('Samples');
Definieren der Clientklasse
Nachdem der Clientnamespace registriert wurde, definiert der Code die Samples.SampleTextBox-Klasse. Diese Klasse enthält zwei Eigenschaften zum Speichern der vom Webserversteuerelement bereitgestellten Eigenschaftenwerte. Sie enthält auch zwei Ereignisdelegaten, die Handler für das onfocus-Ereignis und das onblur-Ereignis des DOM-Elements festlegen, das dem Samples.SampleTextBox-Steuerelement zugeordnet ist.
Das folgende Beispiel zeigt die Samples.SampleTextBox-Klassendefinition.
Samples.SampleTextBox = function(element) {
Samples.SampleTextBox.initializeBase(this, [element]);
this._highlightCssClass = null;
this._nohighlightCssClass = null;
}
Definieren des Klassenprototyps
Nachdem die Samples.SampleTextBox-Klasse definiert ist, definiert der Clientcode den Prototyp für die Klasse. Der Prototyp enthält get- und set-Accessoren für Eigenschaften und Ereignishandler. Außerdem enthält er eine initialize-Methode, die aufgerufen wird, wenn eine Instanz des Steuerelements erstellt wird, sowie eine dispose-Methode, die eine Bereinigung durchführt, wenn das Steuerelement von der Seite nicht mehr benötigt wird.
Definieren der Ereignishandler für das DOM-Element
Ereignishandler für eine Clientklasse werden als Methoden des Klassenprototyps definiert. Mithilfe der addHandlers-Methode (die in diesem Thema später zusammen mit der initialize-Methode diskutiert wird) werden die Handler mit Ereignisdelegaten und mit Ereignissen des Browser-DOM verknüpft.
Das folgende Beispiel zeigt die Ereignishandlermethoden für das Samples.SampleTextBox-Steuerelement.
_onFocus : function(e) {
if (this.get_element() && !this.get_element().disabled) {
this.get_element().className = this._highlightCssClass;
}
},
_onBlur : function(e) {
if (this.get_element() && !this.get_element().disabled) {
this.get_element().className = this._nohighlightCssClass;
}
},
Definieren der Eigenschaftenmethoden Get und Set
Jede im ScriptDescriptor-Objekt der GetScriptDescriptors-Methode des Webserversteuerelements angegebene Eigenschaft muss über zugehörige Clientaccessoren verfügen. Die Clienteigenschaftenaccessoren werden als get_<property name>-Methode und set_<property name>-Methode des Clientklassenprototyps definiert.
| Hinweis: |
|---|
Bei JavaScript muss die Groß-/Kleinschreibung beachtet werden. Die Namen der Accessoren get und set müssen exakt mit den Eigenschaftennamen übereinstimmen, die im ScriptDescriptor-Objekt der GetScriptDescriptors-Methode im Webserversteuerelement angegeben sind. |
Im folgenden Beispiel werden die Eigenschaftenaccessoren get und set für das Samples.SampleTextBox-Steuerelement dargestellt.
get_highlightCssClass : function() {
return this._highlightCssClass;
},
set_highlightCssClass : function(value) {
if (this._highlightCssClass !== value) {
this._highlightCssClass = value;
this.raisePropertyChanged('highlightCssClass');
}
},
get_nohighlightCssClass : function() {
return this._nohighlightCssClass;
},
set_nohighlightCssClass : function(value) {
if (this._nohighlightCssClass !== value) {
this._nohighlightCssClass = value;
this.raisePropertyChanged('nohighlightCssClass');
}
}
Implementieren der Methoden Initialize und Dispose
Die initialize-Methode wird beim Erstellen einer Instanz des Steuerelements aufgerufen. Mit dieser Methode können Sie Standardeigenschaftenwerte festlegen, Funktionsdelegaten erstellen und Delegaten als Ereignishandler hinzufügen.
Die initialize-Methode der Samples.SampleTextBox-Klasse führt Folgendes aus:
Sie ruft die initialize-Methode der Sys.UI.Control-Basisklasse auf.
Sie ruft die addHandlers-Methode auf, um Ereignisdelegaten als Handler für das onfocus-Ereignis und das onblur-Ereignis des zugehörigen HTML-Elements (<input type="text">) hinzuzufügen. Der "on"-Teil des Ereignisnamens (z. B. onfocus) wird nicht angegeben.
Die dispose-Methode wird aufgerufen, wenn eine Instanz des Steuerelements auf der Seite nicht mehr benötigt und daher entfernt wird. Verwenden Sie diese Methode, um für das Steuerelement nicht mehr erforderliche Ressourcen (z. B. DOM-Ereignishandler) freizugeben.
Die dispose-Methode der Sample.SampleTextBox-Klasse führt Folgendes aus:
Sie ruft die clearHandlers-Methode auf, um die Ereignisdelegaten als Handler für das onfocus-Ereignis und das onblur-Ereignis des zugehörigen DOM-Elements zu löschen.
Sie ruft die dispose-Methode der Control-Basisklasse auf.
Hinweis:Die dispose-Methode einer Clientklasse kann auch mehrere Male aufgerufen werden. Stellen Sie sicher, dass der Code, den Sie in der dispose-Methode eintragen, dieses berücksichtigt.
Das folgende Beispiel veranschaulicht die Implementierung der initialize-Methode und der dispose-Methode für den Samples.SampleTextBox-Prototyp.
initialize : function() {
Samples.SampleTextBox.callBaseMethod(this, 'initialize');
this._onfocusHandler = Function.createDelegate(this, this._onFocus);
this._onblurHandler = Function.createDelegate(this, this._onBlur);
$addHandlers(this.get_element(),
{ 'focus' : this._onFocus,
'blur' : this._onBlur },
this);
this.get_element().className = this._nohighlightCssClass;
},
dispose : function() {
$clearHandlers(this.get_element());
Samples.SampleTextBox.callBaseMethod(this, 'dispose');
},
Registrieren des Steuerelements
Die letzte Aufgabe beim Erstellen des Clientsteuerelements besteht darin, die Clientklasse durch Aufrufen der registerClass-Methode zu registrieren. Da es sich bei der Klasse um ein Clientsteuerelement handelt, enthält der Aufruf der registerClass-Methode den JavaScript-Klassennamen zum Registrieren. Außerdem gibt er Control als Basisklasse an.
Das folgende Beispiel zeigt den Aufruf der registerClass-Methode für das Samples.SampleTextBox-Steuerelement. Das Beispiel enthält auch einen Aufruf der notifyScriptLoaded-Methode des Sys.Application-Objekts. Dieser Aufruf ist erforderlich, um Microsoft AJAX Library zu benachrichtigen, dass die JavaScript-Datei geladen wurde.
Samples.SampleTextBox.registerClass('Samples.SampleTextBox', Sys.UI.Control);
if (typeof(Sys) !== 'undefined') Sys.Application.notifyScriptLoaded();
Im folgenden Beispiel wird der vollständige Code für das Samples.SampleTextBox-Clientsteuerelement dargestellt.
// Register the namespace for the control.
Type.registerNamespace('Samples');
//
// Define the control properties.
//
Samples.SampleTextBox = function(element) {
Samples.SampleTextBox.initializeBase(this, [element]);
this._highlightCssClass = null;
this._nohighlightCssClass = null;
}
//
// Create the prototype for the control.
//
Samples.SampleTextBox.prototype = {
initialize : function() {
Samples.SampleTextBox.callBaseMethod(this, 'initialize');
this._onfocusHandler = Function.createDelegate(this, this._onFocus);
this._onblurHandler = Function.createDelegate(this, this._onBlur);
$addHandlers(this.get_element(),
{ 'focus' : this._onFocus,
'blur' : this._onBlur },
this);
this.get_element().className = this._nohighlightCssClass;
},
dispose : function() {
$clearHandlers(this.get_element());
Samples.SampleTextBox.callBaseMethod(this, 'dispose');
},
//
// Event delegates
//
_onFocus : function(e) {
if (this.get_element() && !this.get_element().disabled) {
this.get_element().className = this._highlightCssClass;
}
},
_onBlur : function(e) {
if (this.get_element() && !this.get_element().disabled) {
this.get_element().className = this._nohighlightCssClass;
}
},
//
// Control properties
//
get_highlightCssClass : function() {
return this._highlightCssClass;
},
set_highlightCssClass : function(value) {
if (this._highlightCssClass !== value) {
this._highlightCssClass = value;
this.raisePropertyChanged('highlightCssClass');
}
},
get_nohighlightCssClass : function() {
return this._nohighlightCssClass;
},
set_nohighlightCssClass : function(value) {
if (this._nohighlightCssClass !== value) {
this._nohighlightCssClass = value;
this.raisePropertyChanged('nohighlightCssClass');
}
}
}
// Optional descriptor for JSON serialization.
Samples.SampleTextBox.descriptor = {
properties: [ {name: 'highlightCssClass', type: String},
{name: 'nohighlightCssClass', type: String} ]
}
// Register the class as a type that inherits from Sys.UI.Control.
Samples.SampleTextBox.registerClass('Samples.SampleTextBox', Sys.UI.Control);
if (typeof(Sys) !== 'undefined') Sys.Application.notifyScriptLoaded();
Dynamisches Kompilieren des Steuerelements zum Testen
Jedes Webserversteuerelement (wie das Steuerelement in diesem Thema) muss kompiliert werden, bevor auf einer Webseite darauf verwiesen werden kann. Mit dem dynamischen Kompilierungsfeature von ASP.NET 2.0 können Sie Webserversteuerelemente testen, ohne die Steuerelemente manuell in eine Assembly kompilieren zu müssen. Damit sparen Sie Zeit, wenn Sie Code für Webserversteuerelemente schreiben und debuggen. Die folgende Anleitung zeigt Ihnen, wie Sie das Steuerelement mithilfe des Ordners App_Code dynamisch kompilieren können.
So legen Sie das Steuerelement für die dynamische Kompilierung im Ordner App_Code ab
Erstellen Sie unterhalb des Stammordners der Website einen Ordner mit dem Namen App_Code.
Verschieben Sie die CS- oder VB-Quelldateien für das Steuerelement und alle zugehörigen Klassen in den Ordner App_Code.
- oder -
Wenn Sie dem Bin-Ordner bereits eine Assembly für das Steuerelement hinzugefügt haben, löschen Sie diese. Bearbeiten Sie die Quelldateien von nun an im Ordner App_Code. Der Steuerelement-Quellcode wird bei jedem Ausführen des Projekts kompiliert.
Hinweis:Sie können entweder das Steuerelement im Voraus in eine Assembly kompilieren und die Assembly im Bin-Ordner ablegen oder die Quelldatei des Steuerelements im Ordner App_Code speichern. Beides zugleich ist jedoch nicht möglich. Wenn Sie das Steuerelement in beiden Ordnern speichern, kann der Seitenparser Verweise aus einer Webseite auf das Steuerelement nicht auflösen und löst einen Fehler aus.
Führen Sie die Webseite aus.
Das Steuerelement wird dynamisch kompiliert.
Testen des dynamisch kompilierten Steuerelements in einer Webseite
Die folgende Vorgehensweise beschreibt, wie das Steuerelement in einer ASP.NET AJAX-fähigen Webseite getestet wird. Der Code für das Webserversteuerelement wird dynamisch aus dem Ordner App_Code kompiliert.
So verwenden Sie das Verhalten in einer ASP.NET-Seite
Erstellen Sie eine neue ASP.NET-Webseite.
Wenn die Seite nicht bereits über ein ScriptManager-Steuerelement verfügt, fügen Sie eines hinzu.
Erstellen Sie CSS-Stilregeln für hervorgehobene und für nicht hervorgehobene Textfelder.
Auf welche Weise das Steuerelement hervorgehoben wird, bleibt Ihnen überlassen. Sie können zum Beispiel die Hintergrundfarbe des Steuerelements ändern, einen Rahmen hinzufügen oder die Schriftart von Text ändern.
Fügen Sie der Seite eine @ Register-Direktive hinzu, und geben Sie dann den Namespace und das TagPrefix-Attribut für das Steuerelement an, wie im nächsten Beispiel gezeigt.
Hinweis:In diesem Fall befindet sich der Code für das Serversteuerelement im Ordner App_Code, sodass er dynamisch kompiliert werden kann. Daher ist kein Assemblyattribut angegeben.
Fügen Sie der Seite ein TextBox-Steuerelement und ein Button-Steuerelement hinzu, und legen Sie deren ID-Eigenschaften fest.
Das Markup für die Steuerelemente muss enthalten.
Fügen Sie der Seite eine Instanz des FocusExtender-Steuerelements hinzu.
Legen Sie für die TargetControlID-Eigenschaft des FocusExtender-Steuerelements die ID des Button-Steuerelements fest, das Sie zuvor hinzugefügt haben.
Legen Sie für die HighlightCssClass-Eigenschaft den CSS-Stil zum Hervorheben und für die NoHighlightCssClass-Eigenschaft den CSS-Stil zum Nichthervorheben fest.
Führen Sie die Seite aus, und wählen Sie jedes Steuerelement aus.
Wenn Sie das Button-Steuerelement auswählen, wird es hervorgehoben.
Das folgende Beispiel zeigt eine ASP.NET-Seite, die das in diesem Thema erstellte Verhalten verwendet.
Kompilieren des Steuerelements in eine Assembly
Wenn Sie die JavaScript-Komponente und den Erweiterungscode des Webserversteuerelements in eine Assembly einbetten, lässt sich das benutzerdefinierte Steuerelement leichter bereitstellen. Eine Assembly vereinfacht auch das Verwalten der Versionskontrolle für das Steuerelement. Außerdem können Steuerelemente erst dann der Toolbox eines Designers hinzugefügt werden, wenn sie in eine Assembly kompiliert sind.
In der folgenden Anleitung wird beschrieben, wie Sie mit Visual Studio eine neue Codebibliothek im Projekt dieses Themas erstellen. Sie verschieben eine Kopie der Codedateien in eine neue Codebibliothek im Projekt dieses Themas. Beim Kompilieren des Steuerelements in eine Codebibliothek wird eine Assembly erstellt, die Sie bereitstellen können.
| Hinweis: |
|---|
Um diese Schritte ausführen zu können, müssen Sie Microsoft Visual Studio 2005 verwenden. Sie können Visual Web Developer 2005 Express Edition nicht verwenden, da mit Visual Web Developer Express Edition nicht zwei Projekte in derselben Projektmappe erstellt werden können. |
So fügen Sie einem vorhandenen Projekt eine neue Codebibliothek hinzu
Klicken Sie in Visual Studio im Menü Datei auf Neu, und klicken Sie dann auf Projekt.
Das Dialogfeld Neues Projekt wird angezeigt.
Wählen Sie unter Projekttypen entweder Visual C# oder Visual Basic aus.
Wählen Sie unter Vorlagen die Vorlage Klassenbibliothek aus, und geben Sie dem Projekt den Namen Samples.
Wählen Sie in der Liste Projektmappe den Eintrag Zu Projektmappe hinzufügen aus, und klicken Sie dann auf OK.
Die Klassenbibliothek Samples wird der vorhandenen Projektmappe hinzugefügt.
So verschieben Sie das benutzerdefinierte Serversteuerelement in eine Codebibliothek
Fügen Sie dem Klassenbibliotheksprojekt Samples die folgenden Verweise hinzu, die für das benutzerdefinierte Serversteuerelement erforderlich sind:
System.Drawing
System.Web
System.Web.Extensions
Kopieren Sie im Projektmappen-Explorer die Datei SampleTextBox.cs bzw. SampleTextBox.vb sowie die Datei SampleTextBox.js aus dem ursprünglichen Projekt in den Stamm des Klassenbibliotheksprojekts Samples.
Legen Sie im Fenster Eigenschaften der Datei SampleTextBox.js für Buildvorgang die Option Eingebettete Ressource fest.
.png)
Fügen Sie der AssemblyInfo-Datei die folgende Eigenschaft hinzu.
<Assembly: WebResource("Samples.SampleTextBox.js", "text/javascript")>[assembly: System.Web.UI.WebResource("Samples.SampleTextBox.js", "text/javascript")]Hinweis:Die Datei AssemblyInfo.vb befindet sich im Knoten Eigenes Projekt des Projektmappen-Explorers. Wenn Ihnen im Knoten Eigenes Projekt keine Dateien angezeigt werden, klicken Sie im Menü Projekt auf Alle Dateien anzeigen. Die Datei AssemblyInfo.cs befindet sich im Knoten Eigenschaften des Projektmappen-Explorers.
Die WebResource-Definition für JavaScript-Dateien muss der Namenskonvention [Assemblynamespace].[JavaScript-Dateiname].js folgen.
Hinweis:Standardmäßig legt Visual Studio für den Assemblynamespace den Assemblynamen fest. Sie können den Assemblynamespace in den Eigenschaften der Assembly bearbeiten.
Ändern Sie in der the SampleTextBox-Klassendatei das ScriptReference-Objekt in der GetScriptReferences-Methode so, dass es auf das in der Assembly Samples eingebettete Clientsteuerelementskript verweist. Nehmen Sie dazu die folgenden Änderungen vor:
Ersetzen Sie die Path-Eigenschaft durch eine auf Samples festgelegte Assembly-Eigenschaft.
Fügen Sie eine Name-Eigenschaft hinzu, und legen Sie als deren Wert "Samples.SampleTextBox.js" fest.
Das folgende Beispiel zeigt das Ergebnis dieser Änderungen.
Protected Overridable Function GetScriptReferences() As IEnumerable(Of ScriptReference) Dim reference As ScriptReference = New ScriptReference() reference.Assembly = "Samples" reference.Name = "Samples.SampleTextBox.js" Return New ScriptReference() {reference} End Functionprotected virtual IEnumerable<ScriptReference> GetScriptReferences() { ScriptReference reference = new ScriptReference(); reference.Assembly = "Samples"; reference.Name = "Samples.SampleTextBox.js"; return new ScriptReference[] { reference }; }Erstellen Sie das Projekt.
Nach Abschluss der Kompilierung verfügen Sie über eine Assembly mit dem Namen Samples.dll. Die JavaScript-Codedatei (SampleTextBox.js) ist in dieser Assembly als Ressource eingebettet.
Hinweis:Vergessen Sie nicht, das Klassenbibliotheksprojekt jedes Mal neu zu erstellen, wenn Sie neue Quelldateien hinzufügen oder vorhandene Dateien ändern.
Verwenden des kompilierten Steuerelements aus der Assembly in einer Webseite
Jetzt verweisen Sie in einer ASP.NET AJAX-fähigen Webseite auf das kompilierte benutzerdefinierte Steuerelement.
So verweisen Sie in einer ASP.NET AJAX-fähigen Webseite auf das kompilierte benutzerdefinierte Steuerelement
Erstellen Sie ein neues ASP.NET AJAX-Projekt.
Erstellen Sie im Stammverzeichnis der Website ein Verzeichnis mit dem Namen Bin.
Kopieren Sie die Assembly Samples.dll aus dem Ordner Bin\Debug oder Bin\Release des Klassenprojekts Samples in den neuen Ordner Bin.
Fügen Sie eine neue ASP.NET-Webseite mit dem Namen TestSampleTextBoxAssembly.aspx hinzu, und fügen Sie der neuen Seite dann das folgende Markup hinzu.
<%@ Register Assembly="Samples" Namespace="Samples.VB" TagPrefix="sample" %><%@ Register Assembly="Samples" Namespace="Samples.CS" TagPrefix="sample" %>Da das Serversteuerelement in einer Assembly kompiliert ist, verfügt die @ Register-Direktive zusätzlich zum Namespace-Attribut und TagPrefix-Attribut über ein Assembly-Attribut, das auf die Assembly Samples verweist.
Führen Sie die Seite aus, und wählen Sie jedes Steuerelement aus.
Wenn Sie das SampleTextBox-Steuerelement auswählen, wird es hervorgehoben.
Die Webseite, die das kompilierte benutzerdefinierte Steuerelement verwendet, enthält das Assembly-Attribut in der @ Register-Direktive. Ansonsten ist es dieselbe Webseite, die Sie für das Steuerelement im Ordner App_Code verwendet haben.
Siehe auch
Konzepte
Verwenden des ASP.NET UpdatePanel-Steuerelements mit datengebundenen Steuerelementen