Übersicht über die ASP.NET-PageRequestManager-Klasse
Aktualisiert: November 2007
Die PageRequestManager-Klasse der Microsoft AJAX Library verwaltet Teilaktualisierungen von Seiten im Browser. Wenn eine Seite ein ScriptManager-Steuerelement sowie mindestens ein UpdatePanel-Steuerelement enthält, sind automatisch Teilaktualisierungen der Seite möglich. Die PageRequestManager-Klasse macht Eigenschaften, Methoden und Ereignisse verfügbar, die es Ihnen ermöglichen, Teilaktualisierungen von Seiten mit Clientskripts anzupassen. Die PageRequestManager-Klasse macht ein Ereignismodell für die Clientseite verfügbar, das Sie auf eine ähnliche Weise wie das Ereignismodell für die Serverseite verwenden können.
Dieses Thema enthält folgende Abschnitte:
Szenarien
Features
Hintergrund
Codebeispiele
Gewusst-wie-Themen und Themen exemplarischer Vorgehensweisen
Klassenreferenz
Szenarien
Sie können Teilaktualisierungen von Seiten aktivieren, indem Sie das ScriptManager-Webserversteuerelement und das UpdatePanel-Webserversteuerelement verwenden. Für Teilaktualisierungen von Seiten ist keine Erstellung von Clientskripts erforderlich. Sie können die PageRequestManager-Klasse und Clientskripts jedoch für die folgenden Vorgänge verwenden:
Steuern der Verarbeitung mehrerer asynchroner Postbacks. In der Standardeinstellung hat das letzte Postback Vorrang. Mit der PageRequestManager-Klasse können Sie einem bestimmten Postback Vorrang geben und andere laufende Postbacks abbrechen.
Bereitstellen visueller Hinweise oder anderer Benachrichtigungen zum Kennzeichnen von Bereichen auf der Seite, die als Reaktion auf das letzte asynchrone Postback aktualisiert oder erstellt wurden. Dadurch können Sie die Benutzerfreundlichkeit verbessern, besonders in Szenarien mit mehreren UpdatePanel-Steuerelementen.
Anzeigen von Statusmeldungen bei asynchronen Postbacks. Bei Postbacks mit einer langen Verarbeitungsdauer möchten Sie möglicherweise eine Statusanzeige wie ein animiertes Bild anzeigen. Sie können dem Benutzer auch die Option anbieten, das Postback abzubrechen.
Bereitstellen einer benutzerdefinierten Behandlung von Fehlermeldungen für die Teilaktualisierungen von Seiten. Wenn bei einem asynchronen Postback ein unerwarteter Fehler auftritt, können Sie den Fehler in Clientskripts behandeln.
Zugreifen auf die zugrunde liegenden Anforderungs- und Antwortobjekte, die für das asynchrone Postback verwendet werden.
Features
Die Microsoft AJAX Library unterstützt folgende Features für Teilaktualisierungen von Seiten:
Lebenszyklusereignisse auf der Clientseite, die zu Schlüsselzeiten der Teilaktualisierungen von Seiten ausgelöst werden.
Informationen über die UpdatePanel-Steuerelemente, die während eines asynchronen Postbacks gelöscht, aktualisiert oder erstellt wurden.
Eigenschaften und Methoden, mit denen Sie in Clientskripts ermitteln können, ob die Seite ein asynchrones Postback verarbeitet. Mit diesen Methoden können Sie auch ein laufendes asynchrones Postback beenden oder neue Postbacks abbrechen.
Informationen über Serverdaten, die an Steuerelemente gesendet werden, die nicht an Teilaktualisierungen von Seiten beteiligt sind.
Hintergrund
Bei Teilaktualisierungen von Seiten, die von asynchronen Postbacks initiiert wurden, wird von der PageRequestManager-Klasse koordiniert, wie der Seiteninhalt im Browser inkrementell aktualisiert wird. Das UpdatePanel-Serversteuerelement und die PageRequestManager-Clientklasse abstrahieren einen großen Teil der Komplexität von Teilaktualisierungen von Seiten. Wenn Sie Clientskripts und Member der PageRequestManager-Klasse verwenden, können Sie das Verhalten der Teilaktualisierungen von Seiten im Browser anpassen.
Ereignisbehandlung bei Teilaktualisierungen von Seiten
Bei der Seitenverarbeitung von Postbacks und asynchronen Postbacks können Sie Browserereignisse des Dokumentobjektmodells (DOM) verarbeiten, um benutzerdefinierte Skripts auszuführen. Beispielsweise können Sie ein Skript ausführen, wenn der Browser die Seite lädt oder entlädt.
Durch diese DOM-Ereignisse können Sie jedoch nicht auf alle relevanten Informationen zugreifen oder das Verhalten bei asynchronen Postbacks und Teilaktualisierungen von Seiten steuern. Daher stellt die PageRequestManager-Klasse die folgenden Ereignisse zur Verfügung, mit denen Sie Teilaktualisierungen von Seiten anpassen können:
Weitere Informationen zu diesen Ereignissen finden Sie unter Arbeiten mit PageRequestManager-Ereignissen.
Codebeispiele
Das folgende Beispiel zeigt, wie Sie das pageLoaded-Ereignis der PageRequestManager-Klasse verwenden, um ein UpdatePanel-Steuerelement zu animieren, wenn die Seite nach einem asynchronen Postback aktualisiert wird. In diesem Beispiel können Benutzer ein Datum auswählen und eine E-Mail-Adresse in ein Formular eingeben, um eine Eintrittskarte zu bestellen. Beim Auftreten eines asynchronen Postbacks (ausgelöst durch Links, die sich außerhalb des UpdatePanel-Steuerelements befinden) wird der Bereich kurz animiert, um den Benutzer darauf hinzuweisen, dass das entsprechende Datum in das Textfeld eingetragen wurde. Die Seite enthält ein Popupfenster, das ein Calendar-Steuerelement anzeigt. Der Kalender wird mithilfe der Visible-Eigenschaft des Steuerelements angezeigt oder ausgeblendet. Es muss nicht die gesamte Seite aktualisiert werden, wenn der Kalender angezeigt bzw. ausgeblendet oder ein Datum ausgewählt wird, da sich das Calendar-Steuerelement innerhalb eines UpdatePanel-Steuerelements befindet.
<%@ Page Language="VB" %>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<script >
Protected Sub ChosenDate_TextChanged(ByVal sender As Object, ByVal e As EventArgs)
Dim dt As New DateTime()
DateTime.TryParse(ChosenDate.Text, dt)
CalendarPicker.SelectedDate = dt
CalendarPicker.VisibleDate = dt
End Sub
Protected Sub Close_Click(ByVal sender As Object, ByVal e As EventArgs)
SetDateSelectionAndVisible()
End Sub
Protected Sub ShowDatePickerPopOut_Click(ByVal sender As Object, ByVal e As ImageClickEventArgs)
DatePickerPopOut.Visible = Not (DatePickerPopOut.Visible)
End Sub
Protected Sub CalendarPicker_SelectionChanged(ByVal sender As Object, ByVal e As EventArgs)
SetDateSelectionAndVisible()
End Sub
Private Sub SetDateSelectionAndVisible()
If (CalendarPicker.SelectedDates.Count <> 0) Then
ChosenDate.Text = CalendarPicker.SelectedDate.ToShortDateString()
End If
DatePickerPopOut.Visible = False
End Sub
Protected Sub SubmitButton_Click(ByVal sender As Object, ByVal e As EventArgs)
If (Page.IsValid) Then
MessageLabel.Text = "An email with availability was sent."
Else
MessageLabel.Text = ""
End If
End Sub
Protected Sub Page_Load(ByVal sender As Object, ByVal e As System.EventArgs)
CompareValidatorDate.ValueToCompare = DateTime.Today.ToShortDateString()
ExtraShow1.Text = DateTime.Today.AddDays(10.0).ToShortDateString()
ExtraShow2.Text = DateTime.Today.AddDays(11.0).ToShortDateString()
End Sub
Protected Sub ExtraShow_Click(ByVal sender As Object, ByVal e As EventArgs)
ChosenDate.Text = CType(sender, LinkButton).Text
End Sub
</script>
<html xmlns="http://www.w3.org/1999/xhtml">
<head id="Head1" >
<title>Calendar Example</title>
<style type="text/css">
body {
font-family: Tahoma;
}
.PopUpCalendarStyle
{
background-color:lightblue;
position:absolute;
visibility:show;
margin: 15px 0px 0px 10px;
z-index:99;
border: solid 2px black;
}
.UpdatePanelContainer
{
width: 260px;
height:110px;
}
</style>
</head>
<body>
<form id="form1" >
<asp:ScriptManager ID="ScriptManager1" />
<script type="text/javascript">
Type.registerNamespace("ScriptLibrary");
ScriptLibrary.BorderAnimation = function(color, duration) {
this._color = color;
this._duration = duration;
}
ScriptLibrary.BorderAnimation.prototype = {
animatePanel: function(panelElement) {
var s = panelElement.style;
s.borderWidth = '1px';
s.borderColor = this._color;
s.borderStyle = 'solid';
window.setTimeout(
function() {{ s.borderWidth = 0; }},
this._duration
);
}
}
ScriptLibrary.BorderAnimation.registerClass('ScriptLibrary.BorderAnimation', null);
var panelUpdatedAnimation = new ScriptLibrary.BorderAnimation('blue', 1000);
var postbackElement;
Sys.WebForms.PageRequestManager.getInstance().add_beginRequest(beginRequest);
Sys.WebForms.PageRequestManager.getInstance().add_pageLoaded(pageLoaded);
function beginRequest(sender, args) {
postbackElement = args.get_postBackElement();
}
function pageLoaded(sender, args) {
var updatedPanels = args.get_panelsUpdated();
if (typeof(postbackElement) === "undefined") {
return;
}
else if (postbackElement.id.toLowerCase().indexOf('extrashow') > -1) {
for (i=0; i < updatedPanels.length; i++) {
panelUpdatedAnimation.animatePanel(updatedPanels[i]);
}
}
}
</script>
<h1>Tickets</h1>
<p>
<strong>Latest News</strong> Due to overwhelming response, we
have added two extra shows on:
<asp:LinkButton ID="ExtraShow1" OnClick="ExtraShow_Click" />
and
<asp:LinkButton ID="ExtraShow2" OnClick="ExtraShow_Click" />.
Don't forget curtain time is at 7:00pm sharp. No late arrivals.
</p>
<hr />
<div class="UpdatePanelContainer">
<asp:UpdatePanel ID="UpdatePanel1" UpdateMode="Conditional">
<Triggers>
<asp:AsyncPostBackTrigger ControlID="ExtraShow1" />
<asp:AsyncPostBackTrigger ControlID="ExtraShow2" />
</Triggers>
<ContentTemplate>
<fieldset >
<legend>Check Ticket Availability</legend>Date
<asp:TextBox ID="ChosenDate" OnTextChanged="ChosenDate_TextChanged" />
<asp:ImageButton ID="ShowDatePickerPopOut" OnClick="ShowDatePickerPopOut_Click"
ImageUrl="../images/calendar.gif" AlternateText="Choose a date."
Height="20px" Width="20px" />
<asp:Panel ID="DatePickerPopOut" CssClass="PopUpCalendarStyle"
Visible="false" >
<asp:Calendar ID="CalendarPicker" OnSelectionChanged="CalendarPicker_SelectionChanged">
</asp:Calendar>
<br />
<asp:LinkButton ID="CloseDatePickerPopOut" Font-Size="small"
OnClick="Close_Click" ToolTip="Close Pop out">
Close
</asp:LinkButton>
</asp:Panel>
<br />
Email
<asp:TextBox ID="EmailTextBox" />
<br />
<br />
<asp:Button ID="SubmitButton" Text="Check" ValidationGroup="RequiredFields"
OnClick="SubmitButton_Click" />
<br />
<asp:CompareValidator ID="CompareValidatorDate"
ControlToValidate="ChosenDate" ErrorMessage="Choose a date in the future."
Operator="GreaterThanEqual" Type="Date" Display="None" ValidationGroup="RequiredFields" EnableClientScript="False"></asp:CompareValidator>
<asp:RequiredFieldValidator ID="RequiredFieldValidatorDate"
ControlToValidate="ChosenDate" Display="None" ErrorMessage="Date is required."
ValidationGroup="RequiredFields" EnableClientScript="False"></asp:RequiredFieldValidator>
<asp:RegularExpressionValidator ID="RegularExpressionValidatorEmail"
ControlToValidate="EmailTextBox" Display="None"
ValidationGroup="RequiredFields" ErrorMessage="The email was not correctly formatted."
ValidationExpression="^([0-9a-zA-Z]([-.\w]*[0-9a-zA-Z])*@([0-9a-zA-Z][-\w]*[0-9a-zA-Z]\.)+[a-zA-Z]{2,9})$" EnableClientScript="False"></asp:RegularExpressionValidator>
<asp:RequiredFieldValidator ID="RequiredFieldValidatorEmail"
ValidationGroup="RequiredFields" ControlToValidate="EmailTextBox"
Display="None" ErrorMessage="Email is required." EnableClientScript="False"></asp:RequiredFieldValidator><br />
<asp:ValidationSummary ID="ValidationSummary1"
ValidationGroup="RequiredFields" EnableClientScript="False" />
<asp:Label ID="MessageLabel" />
</fieldset>
</ContentTemplate>
</asp:UpdatePanel>
</div>
</form>
</body>
</html>
<%@ Page Language="C#" %>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<script >
protected void ChosenDate_TextChanged(object sender, EventArgs e)
{
DateTime dt = new DateTime();
DateTime.TryParse(ChosenDate.Text, out dt);
CalendarPicker.SelectedDate = dt;
CalendarPicker.VisibleDate = dt;
}
protected void Close_Click(object sender, EventArgs e)
{
SetDateSelectionAndVisible();
}
protected void ShowDatePickerPopOut_Click(object sender, ImageClickEventArgs e)
{
DatePickerPopOut.Visible = !DatePickerPopOut.Visible;
}
protected void CalendarPicker_SelectionChanged(object sender, EventArgs e)
{
SetDateSelectionAndVisible();
}
private void SetDateSelectionAndVisible()
{
if (CalendarPicker.SelectedDates.Count != 0)
ChosenDate.Text = CalendarPicker.SelectedDate.ToShortDateString();
DatePickerPopOut.Visible = false;
}
protected void SubmitButton_Click(object sender, EventArgs e)
{
if (Page.IsValid)
{
MessageLabel.Text = "An email with availability was sent.";
}
else
{
MessageLabel.Text = "";
}
}
protected void Page_Load(object sender, EventArgs e)
{
CompareValidatorDate.ValueToCompare = DateTime.Today.ToShortDateString();
ExtraShow1.Text = DateTime.Today.AddDays(10.0).ToShortDateString();
ExtraShow2.Text = DateTime.Today.AddDays(11.0).ToShortDateString();
}
protected void ExtraShow_Click(object sender, EventArgs e)
{
ChosenDate.Text = ((LinkButton)sender).Text;
}
</script>
<html xmlns="http://www.w3.org/1999/xhtml">
<head id="Head1" >
<title>Calendar Example</title>
<style type="text/css">
body {
font-family: Tahoma;
}
.PopUpCalendarStyle
{
background-color:lightblue;
position:absolute;
visibility:show;
margin: 15px 0px 0px 10px;
z-index:99;
border: solid 2px black;
}
.UpdatePanelContainer
{
width: 260px;
height:110px;
}
</style>
</head>
<body>
<form id="form1" >
<asp:ScriptManager ID="ScriptManager1" />
<script type="text/javascript">
Type.registerNamespace("ScriptLibrary");
ScriptLibrary.BorderAnimation = function(color, duration) {
this._color = color;
this._duration = duration;
}
ScriptLibrary.BorderAnimation.prototype = {
animatePanel: function(panelElement) {
var s = panelElement.style;
s.borderWidth = '1px';
s.borderColor = this._color;
s.borderStyle = 'solid';
window.setTimeout(
function() {{ s.borderWidth = 0; }},
this._duration
);
}
}
ScriptLibrary.BorderAnimation.registerClass('ScriptLibrary.BorderAnimation', null);
var panelUpdatedAnimation = new ScriptLibrary.BorderAnimation('blue', 1000);
var postbackElement;
Sys.WebForms.PageRequestManager.getInstance().add_beginRequest(beginRequest);
Sys.WebForms.PageRequestManager.getInstance().add_pageLoaded(pageLoaded);
function beginRequest(sender, args) {
postbackElement = args.get_postBackElement();
}
function pageLoaded(sender, args) {
var updatedPanels = args.get_panelsUpdated();
if (typeof(postbackElement) === "undefined") {
return;
}
else if (postbackElement.id.toLowerCase().indexOf('extrashow') > -1) {
for (i=0; i < updatedPanels.length; i++) {
panelUpdatedAnimation.animatePanel(updatedPanels[i]);
}
}
}
</script>
<h1>Tickets</h1>
<p>
<strong>Latest News</strong> Due to overwhelming response, we
have added two extra shows on:
<asp:LinkButton ID="ExtraShow1" OnClick="ExtraShow_Click" />
and
<asp:LinkButton ID="ExtraShow2" OnClick="ExtraShow_Click" />.
Don't forget curtain time is at 7:00pm sharp. No late arrivals.
</p>
<hr />
<div class="UpdatePanelContainer">
<asp:UpdatePanel ID="UpdatePanel1" UpdateMode="Conditional">
<Triggers>
<asp:AsyncPostBackTrigger ControlID="ExtraShow1" />
<asp:AsyncPostBackTrigger ControlID="ExtraShow2" />
</Triggers>
<ContentTemplate>
<fieldset>
<legend>Check Ticket Availability</legend>Date
<asp:TextBox ID="ChosenDate" OnTextChanged="ChosenDate_TextChanged" />
<asp:ImageButton ID="ShowDatePickerPopOut" OnClick="ShowDatePickerPopOut_Click"
ImageUrl="../images/calendar.gif" AlternateText="Choose a date."
Height="20px" Width="20px" />
<asp:Panel ID="DatePickerPopOut" CssClass="PopUpCalendarStyle"
Visible="false" >
<asp:Calendar ID="CalendarPicker" OnSelectionChanged="CalendarPicker_SelectionChanged">
</asp:Calendar>
<br />
<asp:LinkButton ID="CloseDatePickerPopOut" Font-Size="small"
OnClick="Close_Click" ToolTip="Close Pop out">
Close
</asp:LinkButton>
</asp:Panel>
<br />
Email
<asp:TextBox ID="EmailTextBox" />
<br />
<br />
<asp:Button ID="SubmitButton" Text="Check" ValidationGroup="RequiredFields"
OnClick="SubmitButton_Click" />
<br />
<asp:CompareValidator ID="CompareValidatorDate"
ControlToValidate="ChosenDate" ErrorMessage="Choose a date in the future."
Operator="GreaterThanEqual" Type="Date" Display="None" ValidationGroup="RequiredFields" EnableClientScript="False"></asp:CompareValidator>
<asp:RequiredFieldValidator ID="RequiredFieldValidatorDate"
ControlToValidate="ChosenDate" Display="None" ErrorMessage="Date is required."
ValidationGroup="RequiredFields" EnableClientScript="False"></asp:RequiredFieldValidator>
<asp:RegularExpressionValidator ID="RegularExpressionValidatorEmail"
ControlToValidate="EmailTextBox" Display="None"
ValidationGroup="RequiredFields" ErrorMessage="The email was not correctly formatted."
ValidationExpression="^([0-9a-zA-Z]([-.\w]*[0-9a-zA-Z])*@([0-9a-zA-Z][-\w]*[0-9a-zA-Z]\.)+[a-zA-Z]{2,9})$" EnableClientScript="False"></asp:RegularExpressionValidator>
<asp:RequiredFieldValidator ID="RequiredFieldValidatorEmail"
ValidationGroup="RequiredFields" ControlToValidate="EmailTextBox"
Display="None" ErrorMessage="Email is required." EnableClientScript="False"></asp:RequiredFieldValidator><br />
<asp:ValidationSummary ID="ValidationSummary1"
ValidationGroup="RequiredFields" EnableClientScript="False" />
<asp:Label ID="MessageLabel" />
</fieldset>
</ContentTemplate>
</asp:UpdatePanel>
</div>
</form>
</body>
</html>
Gewusst-wie-Themen und Themen exemplarischer Vorgehensweisen
Exemplarische Vorgehensweise: Animieren von ASP.NET-UpdatePanel-Steuerelementen
Anpassen der Fehlerbehandlung für ASP.NET-UpdatePanel-Steuerelemente
Klassenreferenz
In der folgenden Tabelle sind die Klassen mit Bezug zur PageRequestManager-Klasse aufgelistet.
Klasse |
Beschreibung |
|---|---|
Verwaltet Clientteilaktualisierungen von Seiten und stellt Member zur Erstellung von benutzerdefinierten Clientskripts bereit. |
|
Stellt Ereignisdaten für das initializeRequest-Ereignis bereit, das vor dem Starten der asynchronen Anforderung ausgelöst wird. |
|
Stellt Ereignisdaten für das beginRequest-Ereignis bereit, das nach dem Starten eines asynchronen Postbacks und vor dem Senden des Postbacks an den Server ausgelöst wird. |
|
Stellt Ereignisdaten für das pageLoading-Ereignis bereit, das nach dem Empfang der Antwort auf ein asynchrones Postback ausgelöst wird, jedoch vor der Aktualisierung von Inhalten auf der Seite. Dieses Ereignis wird nicht ausgelöst, wenn das Postback beendet oder auf dem Server bei der Verarbeitung eine nicht behandelte Ausnahme ausgelöst wurde. |
|
Stellt Ereignisdaten für das pageLoaded-Ereignis bereit, das nach dem Aktualisieren aller Inhalte der Seite ausgelöst wird, unabhängig davon, ob dies als Reaktion auf ein synchrones oder ein asynchrones Postback erfolgt. Dieses Ereignis wird nicht ausgelöst, wenn das Postback beendet oder auf dem Server bei der Verarbeitung eine nicht behandelte Ausnahme ausgelöst wurde. |
|
Stellt Ereignisdaten für das endRequest-Ereignis bereit, das nach dem Beenden eines asynchronen Postbacks ausgelöst wird. |