ASP.NET PageRequestManager 类概述
更新：2007 年 11 月
Microsoft AJAX Library 中的 PageRequestManager 类可管理浏览器中的部分页更新。当页中包含一个 ScriptManager 控件和一个或多个 UpdatePanel 控件时，该页将会自动启用部分页呈现。PageRequestManager 类公开属性、方法和事件，它们使您能够用客户端脚本来自定义部分页更新。PageRequestManager 类公开客户端页事件模型，可以通过与使用服务器页事件模型类似的方法来使用此模型。
本主题包括：
方案
功能
背景
代码示例
帮助和演练主题
类参考
方案
可通过使用 ScriptManager 和 UpdatePanel Web 服务器控件来启用部分页更新。部分页更新不需要客户端脚本。但是，当您要执行以下操作时，可使用 PageRequestManager 类和客户端脚本：
控制如何处理多个异步回发。默认行为是将最后的回发优先。PageRequestManager 类使您能够为某个特定回发赋予优先级，并取消正在进行中的其他回发。
提供视觉提示或其他通知以标记因上一次异步回发而更新或创建的页区域。这可以增强用户体验，特别是在使用多个 UpdatePanel 控件的方案中。
在异步回发过程中显示状态消息。如果回发的处理时间很长，则可以显示一个进度指示器（例如动画图像）。还可以为用户提供用于取消回发的选项。
提供用于部分页更新的自定义错误消息处理。如果在异步回发期间发生错误，则可以在客户端脚本中处理该错误。
访问用于异步回发的基础请求和响应对象。
功能
Microsoft AJAX Library 中的部分页更新功能包括：
在部分页更新过程中的关键时刻引发的客户端页生命周期事件。
有关在异步回发期间删除、更新或创建的 UpdatePanel 控件的信息。
使您能够在客户端脚本中确定页是否正在处理异步回发的属性和方法。也可以使用这些方法来停止正在进行中的异步回发或取消新的回发。
有关发送到未参与部分页更新的控件的服务器数据的信息。
背景
在由异步回发启动的部分页更新过程中，PageRequestManager 类将协调浏览器中对页内容进行增量更新的方式。UpdatePanel 服务器控件和 PageRequestManager 客户端类将部分页更新的大部分复杂性抽象化。当使用客户端脚本和 PageRequestManager 类的成员时，可以在浏览器中自定义部分页更新行为。
部分页更新事件处理
在回发和异步回发的页处理过程中，可以处理浏览器文档对象模型 (DOM) 事件以运行自定义脚本。例如，可以在浏览器加载或卸载页时运行脚本。
但是，这些 DOM 事件不能让您在异步回发和部分页更新过程中访问所有相关信息或控制行为。因此，PageRequestManager 类公开下面的事件，这些事件使您能够自定义部分页更新：
有关这些事件的更多信息，请参见处理 PageRequestManager 事件。
代码示例
下面的示例演示当在异步回发之后对页进行更新时，如何使用 PageRequestManager 类的 pageLoaded 事件对 UpdatePanel 控件进行动画处理。在此示例中，用户可以选择一个日期并在窗体中输入电子邮件地址以发出票证请求。当发生异步回发时（由 UpdatePanel 控件外部的链接触发），将对面板进行短暂动画处理以通知用户已在文本框中输入日期值。页面包含一个弹出窗口，该窗口显示 Calendar 控件。使用该控件的 Visible 属性来显示或隐藏日历。当显示或隐藏日历时或选定了某个日期时，不必刷新整个页面，因为 Calendar 控件位于 UpdatePanel 控件内。
<%@ Page Language="VB" %>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<script runat="server">
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" runat="server">
<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" runat="server">
<asp:ScriptManager ID="ScriptManager1" runat="server" />
<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" runat="server" OnClick="ExtraShow_Click" />
and
<asp:LinkButton ID="ExtraShow2" runat="server" OnClick="ExtraShow_Click" />.
Don't forget curtain time is at 7:00pm sharp. No late arrivals.
</p>
<hr />
<div class="UpdatePanelContainer">
<asp:UpdatePanel runat="server" ID="UpdatePanel1" UpdateMode="Conditional">
<Triggers>
<asp:AsyncPostBackTrigger ControlID="ExtraShow1" />
<asp:AsyncPostBackTrigger ControlID="ExtraShow2" />
</Triggers>
<ContentTemplate>
<fieldset >
<legend>Check Ticket Availability</legend>Date
<asp:TextBox runat="server" ID="ChosenDate" OnTextChanged="ChosenDate_TextChanged" />
<asp:ImageButton runat="server" 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" runat="server">
<asp:Calendar ID="CalendarPicker" runat="server" OnSelectionChanged="CalendarPicker_SelectionChanged">
</asp:Calendar>
<br />
<asp:LinkButton ID="CloseDatePickerPopOut" runat="server" Font-Size="small"
OnClick="Close_Click" ToolTip="Close Pop out">
Close
</asp:LinkButton>
</asp:Panel>
<br />
Email
<asp:TextBox runat="server" ID="EmailTextBox" />
<br />
<br />
<asp:Button ID="SubmitButton" Text="Check" runat="server" ValidationGroup="RequiredFields"
OnClick="SubmitButton_Click" />
<br />
<asp:CompareValidator ID="CompareValidatorDate" runat="server"
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" runat="server"
ControlToValidate="ChosenDate" Display="None" ErrorMessage="Date is required."
ValidationGroup="RequiredFields" EnableClientScript="False"></asp:RequiredFieldValidator>
<asp:RegularExpressionValidator ID="RegularExpressionValidatorEmail"
runat="server" 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"
runat="server" ValidationGroup="RequiredFields" ControlToValidate="EmailTextBox"
Display="None" ErrorMessage="Email is required." EnableClientScript="False"></asp:RequiredFieldValidator><br />
<asp:ValidationSummary ID="ValidationSummary1" runat="server"
ValidationGroup="RequiredFields" EnableClientScript="False" />
<asp:Label ID="MessageLabel" runat="server" />
</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 runat="server">
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" runat="server">
<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" runat="server">
<asp:ScriptManager ID="ScriptManager1" runat="server" />
<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" runat="server" OnClick="ExtraShow_Click" />
and
<asp:LinkButton ID="ExtraShow2" runat="server" OnClick="ExtraShow_Click" />.
Don't forget curtain time is at 7:00pm sharp. No late arrivals.
</p>
<hr />
<div class="UpdatePanelContainer">
<asp:UpdatePanel runat="server" ID="UpdatePanel1" UpdateMode="Conditional">
<Triggers>
<asp:AsyncPostBackTrigger ControlID="ExtraShow1" />
<asp:AsyncPostBackTrigger ControlID="ExtraShow2" />
</Triggers>
<ContentTemplate>
<fieldset>
<legend>Check Ticket Availability</legend>Date
<asp:TextBox runat="server" ID="ChosenDate" OnTextChanged="ChosenDate_TextChanged" />
<asp:ImageButton runat="server" 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" runat="server">
<asp:Calendar ID="CalendarPicker" runat="server" OnSelectionChanged="CalendarPicker_SelectionChanged">
</asp:Calendar>
<br />
<asp:LinkButton ID="CloseDatePickerPopOut" runat="server" Font-Size="small"
OnClick="Close_Click" ToolTip="Close Pop out">
Close
</asp:LinkButton>
</asp:Panel>
<br />
Email
<asp:TextBox runat="server" ID="EmailTextBox" />
<br />
<br />
<asp:Button ID="SubmitButton" Text="Check" runat="server" ValidationGroup="RequiredFields"
OnClick="SubmitButton_Click" />
<br />
<asp:CompareValidator ID="CompareValidatorDate" runat="server"
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" runat="server"
ControlToValidate="ChosenDate" Display="None" ErrorMessage="Date is required."
ValidationGroup="RequiredFields" EnableClientScript="False"></asp:RequiredFieldValidator>
<asp:RegularExpressionValidator ID="RegularExpressionValidatorEmail"
runat="server" 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"
runat="server" ValidationGroup="RequiredFields" ControlToValidate="EmailTextBox"
Display="None" ErrorMessage="Email is required." EnableClientScript="False"></asp:RequiredFieldValidator><br />
<asp:ValidationSummary ID="ValidationSummary1" runat="server"
ValidationGroup="RequiredFields" EnableClientScript="False" />
<asp:Label ID="MessageLabel" runat="server" />
</fieldset>
</ContentTemplate>
</asp:UpdatePanel>
</div>
</form>
</body>
</html>
帮助和演练主题
类参考
下表列出了与 PageRequestManager 类相关的类。
类 |
说明 |
|---|---|
管理客户端部分页更新，并公开用于自定义客户端脚本撰写的成员。 |
|
为 initializeRequest 事件提供事件数据，该事件在异步请求启动之前引发。 |
|
为 beginRequest 事件提供事件数据，该事件在异步回发启动之后但在发送到服务器之前引发。 |
|
为 pageLoading 事件提供事件数据，该事件在收到对异步回发的响应之后但在页上的任何内容更新之前引发。如果回发停止或在处理过程中服务器上引发未处理的异常，则不引发此事件。 |
|
为 pageLoaded 事件提供事件数据，该事件在页上的所有内容刷新（无论是因同步回发还是异步回发引起）之后引发。如果回发停止或在处理过程中服务器上引发未处理的异常，则不引发此事件。 |
|
为 endRequest 事件提供事件数据，该事件在异步回发完成之后引发。 |