WebPartManager 類別
定義
重要
部分資訊涉及發行前產品，在發行之前可能會有大幅修改。 Microsoft 對此處提供的資訊，不做任何明確或隱含的瑕疵擔保。
作為 Web 組件控制項集合的中心類別，管理在網頁上發生的所有 Web 組件控制項、功能和事件。
public ref class WebPartManager : System::Web::UI::Control, System::Web::UI::INamingContainer, System::Web::UI::WebControls::WebParts::IPersonalizable[System.ComponentModel.Bindable(false)]
public class WebPartManager : System.Web.UI.Control, System.Web.UI.INamingContainer, System.Web.UI.WebControls.WebParts.IPersonalizable[<System.ComponentModel.Bindable(false)>]
type WebPartManager = class
inherit Control
interface INamingContainer
interface IPersonalizablePublic Class WebPartManager
Inherits Control
Implements INamingContainer, IPersonalizable- 繼承
- 屬性
- 實作
範例
下列程式碼範例示範控制項的 WebPartManager 宣告式和程式設計用法。
程式碼範例有四個部分：
使用者控制項，可讓您變更網頁元件頁面上的顯示模式。
網頁，包含兩個可連接的自訂 WebPart 控制項，以及 一個
<asp:webpartmanager>元素。包含兩個自訂 WebPart 控制項和自訂介面的原始程式碼檔案。
說明範例在瀏覽器中的運作方式。
使用者控制項有一個下拉式清單控制項，可在頁面上顯示可能的顯示模式，並指定頁面上存在的網頁元件控制項。 在此程式碼範例的網頁中，這個使用者控制項宣告在頁面標記的 元素正下方 WebPartManager ，而且網頁頂端有 Register 指示詞可註冊控制項。 如需此控制項中顯示模式和原始程式碼描述的詳細資訊，請參閱逐步解說 ：變更網頁元件頁面上的顯示模式。
<%@ control language="C#" classname="DisplayModeMenuCS"%>
<script runat="server">
// Use a field to reference the current WebPartManager.
WebPartManager _manager;
void Page_Init(object sender, EventArgs e)
{
Page.InitComplete += new EventHandler(InitComplete);
}
void InitComplete(object sender, System.EventArgs e)
{
_manager = WebPartManager.GetCurrentWebPartManager(Page);
String browseModeName = WebPartManager.BrowseDisplayMode.Name;
// Fill the dropdown with the names of supported display modes.
foreach (WebPartDisplayMode mode in _manager.SupportedDisplayModes)
{
String modeName = mode.Name;
// Make sure a mode is enabled before adding it.
if (mode.IsEnabled(_manager))
{
ListItem item = new ListItem(modeName, modeName);
DisplayModeDropdown.Items.Add(item);
}
}
// If shared scope is allowed for this user, display the scope-switching
// UI and select the appropriate radio button for the current user scope.
if (_manager.Personalization.CanEnterSharedScope)
{
Panel2.Visible = true;
if (_manager.Personalization.Scope == PersonalizationScope.User)
RadioButton1.Checked = true;
else
RadioButton2.Checked = true;
}
}
// Change the page to the selected display mode.
void DisplayModeDropdown_SelectedIndexChanged(object sender, EventArgs e)
{
String selectedMode = DisplayModeDropdown.SelectedValue;
WebPartDisplayMode mode = _manager.SupportedDisplayModes[selectedMode];
if (mode != null)
_manager.DisplayMode = mode;
}
// Set the selected item equal to the current display mode.
void Page_PreRender(object sender, EventArgs e)
{
ListItemCollection items = DisplayModeDropdown.Items;
int selectedIndex =
items.IndexOf(items.FindByText(_manager.DisplayMode.Name));
DisplayModeDropdown.SelectedIndex = selectedIndex;
}
// Reset all of a user's personalization data for the page.
protected void LinkButton1_Click(object sender, EventArgs e)
{
_manager.Personalization.ResetPersonalizationState();
}
// If not in User personalization scope, toggle into it.
protected void RadioButton1_CheckedChanged(object sender, EventArgs e)
{
if (_manager.Personalization.Scope == PersonalizationScope.Shared)
_manager.Personalization.ToggleScope();
}
// If not in Shared scope, and if user is allowed, toggle the scope.
protected void RadioButton2_CheckedChanged(object sender, EventArgs e)
{
if (_manager.Personalization.CanEnterSharedScope &&
_manager.Personalization.Scope == PersonalizationScope.User)
_manager.Personalization.ToggleScope();
}
</script>
<div>
<asp:Panel ID="Panel1" runat="server"
Borderwidth="1"
Width="230"
BackColor="lightgray"
Font-Names="Verdana, Arial, Sans Serif" >
<asp:Label ID="Label1" runat="server"
Text=" Display Mode"
Font-Bold="true"
Font-Size="8"
Width="120"
AssociatedControlID="DisplayModeDropdown"/>
<asp:DropDownList ID="DisplayModeDropdown" runat="server"
AutoPostBack="true"
Width="120"
OnSelectedIndexChanged="DisplayModeDropdown_SelectedIndexChanged" />
<asp:LinkButton ID="LinkButton1" runat="server"
Text="Reset User State"
ToolTip="Reset the current user's personalization data for the page."
Font-Size="8"
OnClick="LinkButton1_Click" />
<asp:Panel ID="Panel2" runat="server"
GroupingText="Personalization Scope"
Font-Bold="true"
Font-Size="8"
Visible="false" >
<asp:RadioButton ID="RadioButton1" runat="server"
Text="User"
AutoPostBack="true"
GroupName="Scope" OnCheckedChanged="RadioButton1_CheckedChanged" />
<asp:RadioButton ID="RadioButton2" runat="server"
Text="Shared"
AutoPostBack="true"
GroupName="Scope"
OnCheckedChanged="RadioButton2_CheckedChanged" />
</asp:Panel>
</asp:Panel>
</div>
<%@ control language="vb" classname="DisplayModeMenuVB"%>
<script runat="server">
' Use a field to reference the current WebPartManager.
Dim _manager As WebPartManager
Sub Page_Init(ByVal sender As Object, ByVal e As EventArgs)
AddHandler Page.InitComplete, AddressOf InitComplete
End Sub
Sub InitComplete(ByVal sender As Object, ByVal e As System.EventArgs)
_manager = WebPartManager.GetCurrentWebPartManager(Page)
Dim browseModeName As String = WebPartManager.BrowseDisplayMode.Name
' Fill the dropdown with the names of supported display modes.
Dim mode As WebPartDisplayMode
For Each mode In _manager.SupportedDisplayModes
Dim modeName As String = mode.Name
' Make sure a mode is enabled before adding it.
If mode.IsEnabled(_manager) Then
Dim item As New ListItem(modeName, modeName)
DisplayModeDropdown.Items.Add(item)
End If
Next mode
' If shared scope is allowed for this user, display the scope-switching
' UI and select the appropriate radio button for the current user scope.
If _manager.Personalization.CanEnterSharedScope Then
Panel2.Visible = True
If _manager.Personalization.Scope = PersonalizationScope.User Then
RadioButton1.Checked = True
Else
RadioButton2.Checked = True
End If
End If
End Sub
' Change the page to the selected display mode.
Sub DisplayModeDropdown_SelectedIndexChanged(ByVal sender As Object, _
ByVal e As EventArgs)
Dim selectedMode As String = DisplayModeDropdown.SelectedValue
Dim mode As WebPartDisplayMode = _
_manager.SupportedDisplayModes(selectedMode)
If Not (mode Is Nothing) Then
_manager.DisplayMode = mode
End If
End Sub
' Set the selected item equal to the current display mode.
Sub Page_PreRender(ByVal sender As Object, ByVal e As EventArgs)
Dim items As ListItemCollection = DisplayModeDropdown.Items
Dim selectedIndex As Integer = _
items.IndexOf(items.FindByText(_manager.DisplayMode.Name))
DisplayModeDropdown.SelectedIndex = selectedIndex
End Sub
' Reset all of a user's personalization data for the page.
Protected Sub LinkButton1_Click(ByVal sender As Object, _
ByVal e As EventArgs)
_manager.Personalization.ResetPersonalizationState()
End Sub
' If not in User personalization scope, toggle into it.
Protected Sub RadioButton1_CheckedChanged(ByVal sender As Object, _
ByVal e As EventArgs)
If _manager.Personalization.Scope = PersonalizationScope.Shared Then
_manager.Personalization.ToggleScope()
End If
End Sub
' If not in Shared scope, and if user is allowed, toggle the scope.
Protected Sub RadioButton2_CheckedChanged(ByVal sender As Object, _
ByVal e As EventArgs)
If _manager.Personalization.CanEnterSharedScope AndAlso _
_manager.Personalization.Scope = PersonalizationScope.User Then
_manager.Personalization.ToggleScope()
End If
End Sub
</script>
<div>
<asp:Panel ID="Panel1" runat="server"
Borderwidth="1"
Width="230"
BackColor="lightgray"
Font-Names="Verdana, Arial, Sans Serif" >
<asp:Label ID="Label1" runat="server"
Text=" Display Mode"
Font-Bold="true"
Font-Size="8"
Width="120"
AssociatedControlID="DisplayModeDropdown"/>
<asp:DropDownList ID="DisplayModeDropdown" runat="server"
AutoPostBack="true"
Width="120"
OnSelectedIndexChanged="DisplayModeDropdown_SelectedIndexChanged" />
<asp:LinkButton ID="LinkButton1" runat="server"
Text="Reset User State"
ToolTip="Reset the current user's personalization data for the page."
Font-Size="8"
OnClick="LinkButton1_Click" />
<asp:Panel ID="Panel2" runat="server"
GroupingText="Personalization Scope"
Font-Bold="true"
Font-Size="8"
Visible="false" >
<asp:RadioButton ID="RadioButton1" runat="server"
Text="User"
AutoPostBack="true"
GroupName="Scope" OnCheckedChanged="RadioButton1_CheckedChanged" />
<asp:RadioButton ID="RadioButton2" runat="server"
Text="Shared"
AutoPostBack="true"
GroupName="Scope"
OnCheckedChanged="RadioButton2_CheckedChanged" />
</asp:Panel>
</asp:Panel>
</div>
網頁的宣告式標記包含 Register 使用者控制項和自訂控制項的指示詞。 有專案 <asp:webpartmanager> 、 <asp:webpartzone> 要包含自訂控制項的 元素，以及 專案 <asp:connectionszone> 。 頁面也包含一些內嵌程式碼，可處理控制項的連接 WebPartManager 相關事件;當您連接和中斷連線控制項時，您可以看到此程式碼的效果。
<%@ Page Language="C#" %>
<%@ register TagPrefix="uc1"
TagName="DisplayModeMenuCS"
Src="DisplayModeMenuCS.ascx" %>
<%@ register tagprefix="aspSample"
Namespace="Samples.AspNet.CS.Controls"
Assembly="ConnectionSampleCS" %>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<script runat="server">
private void UpdateLabelData(int wpCount, int connCount)
{
Label1.Text = "WebPart Control Count: " + wpCount.ToString();
Label2.Text = "Connections Count: " + connCount.ToString();
}
protected void WebPartManager1_WebPartsConnected(object sender, WebPartConnectionsEventArgs e)
{
UpdateLabelData(WebPartManager1.WebParts.Count,
WebPartManager1.Connections.Count);
}
protected void WebPartManager1_WebPartsDisconnected(object sender, WebPartConnectionsEventArgs e)
{
UpdateLabelData(WebPartManager1.WebParts.Count,
WebPartManager1.Connections.Count);
}
</script>
<html xmlns="http://www.w3.org/1999/xhtml" >
<head id="Head1" runat="server">
<title>ASP.NET Example</title>
</head>
<body>
<form id="form1" runat="server">
<!-- Reference the WebPartManager control. -->
<asp:WebPartManager ID="WebPartManager1" runat="server"
OnWebPartsConnected="WebPartManager1_WebPartsConnected"
OnWebPartsDisconnected="WebPartManager1_WebPartsDisconnected" />
<div>
<uc1:DisplayModeMenuCS ID="displaymode1" runat="server" />
<!-- Reference consumer and provider controls in a zone. -->
<asp:WebPartZone ID="WebPartZone1" runat="server">
<ZoneTemplate>
<aspSample:ZipCodeWebPart ID="zip1"
runat="server"
Title="Zip Code Control"/>
<aspSample:WeatherWebPart ID="weather1"
runat="server"
Title="Weather Control" />
</ZoneTemplate>
</asp:WebPartZone>
<hr />
<asp:Label ID="Label1" runat="server" Text=""></asp:Label>
<br />
<asp:Label ID="Label2" runat="server" Text=""></asp:Label>
<!-- Add a ConnectionsZone so users can connect controls. -->
<asp:ConnectionsZone ID="ConnectionsZone1" runat="server" />
</div>
</form>
</body>
</html>
<%@ Page Language="vb" %>
<%@ register TagPrefix="uc1"
TagName="DisplayModeMenuVB"
Src="DisplayModeMenuVB.ascx" %>
<%@ register tagprefix="aspSample"
Namespace="Samples.AspNet.VB.Controls"
Assembly="ConnectionSampleVB" %>
<!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 WebPartManager1_WebPartsConnected( _
ByVal sender As Object, _
ByVal e As System.Web.UI.WebControls.WebParts.WebPartConnectionsEventArgs)
UpdateLabelData(WebPartManager1.WebParts.Count, _
WebPartManager1.Connections.Count)
End Sub
Protected Sub WebPartManager1_WebPartsDisconnected( _
ByVal sender As Object, _
ByVal e As System.Web.UI.WebControls.WebParts.WebPartConnectionsEventArgs)
UpdateLabelData(WebPartManager1.WebParts.Count, _
WebPartManager1.Connections.Count)
End Sub
Private Sub UpdateLabelData(ByVal wpCount As Integer, _
ByVal connCount As Integer)
Label1.Text = "WebPart Control Count: " & wpCount.ToString()
Label2.Text = "Connections Count: " & connCount.ToString()
End Sub
</script>
<html xmlns="http://www.w3.org/1999/xhtml" >
<head runat="server">
<title>ASP.NET Example</title>
</head>
<body>
<form id="form1" runat="server">
<!-- Reference the WebPartManager control. -->
<asp:WebPartManager ID="WebPartManager1" runat="server" OnWebPartsConnected="WebPartManager1_WebPartsConnected" OnWebPartsDisconnected="WebPartManager1_WebPartsDisconnected" />
<div>
<uc1:DisplayModeMenuVB ID="displaymode1" runat="server" />
<!-- Reference consumer and provider controls in a zone. -->
<asp:WebPartZone ID="WebPartZone1" runat="server">
<ZoneTemplate>
<aspSample:ZipCodeWebPart ID="zip1"
runat="server"
Title="Zip Code Control"/>
<aspSample:WeatherWebPart ID="weather1"
runat="server"
Title="Weather Control" />
</ZoneTemplate>
</asp:WebPartZone>
<hr />
<asp:Label ID="Label1" runat="server" Text=""></asp:Label>
<br />
<asp:Label ID="Label2" runat="server" Text=""></asp:Label>
<!-- Add a ConnectionsZone so users can connect controls. -->
<asp:ConnectionsZone ID="ConnectionsZone1" runat="server" />
</div>
</form>
</body>
</html>
範例的第三個部分是控制項的原始程式碼。 請注意，有一個名為 的 IZipCode 介面，而且這個介面會在 類別中實作 ZipCodeWebPart 。 這個類別具有名為 ProvideIZipCode 的特殊回呼方法，可作為提供者。 另一個名為 WeatherWebPart 的型別也會使用名為 GetIZipCode 的特殊方法實作，讓控制項可作為另一個控制項的取用者。
若要執行程式碼範例，您必須編譯此原始程式碼。 您可以明確地編譯它，並將產生的元件放在網站的 Bin 資料夾或全域組件快取中。 或者，您可以將原始程式碼放在月臺的 App_Code 資料夾中，其將在執行時間動態編譯。 此程式碼範例假設您已將來源編譯成元件，而 Register 網頁中的 指示詞會參考元件名稱。 如需示範如何編譯的逐步解說，請參閱逐步解說 ：開發和使用自訂 Web 服務器控制項。
namespace Samples.AspNet.CS.Controls
{
using System;
using System.Web;
using System.Web.Security;
using System.Security.Permissions;
using System.Web.UI;
using System.Web.UI.WebControls;
using System.Web.UI.WebControls.WebParts;
[AspNetHostingPermission(SecurityAction.Demand,
Level = AspNetHostingPermissionLevel.Minimal)]
[AspNetHostingPermission(SecurityAction.InheritanceDemand,
Level = AspNetHostingPermissionLevel.Minimal)]
public interface IZipCode
{
string ZipCode { get; set;}
}
[AspNetHostingPermission(SecurityAction.Demand,
Level = AspNetHostingPermissionLevel.Minimal)]
[AspNetHostingPermission(SecurityAction.InheritanceDemand,
Level = AspNetHostingPermissionLevel.Minimal)]
public class ZipCodeWebPart : WebPart, IZipCode
{
string zipCodeText = String.Empty;
TextBox input;
Button send;
public ZipCodeWebPart()
{
}
// Make the implemented property personalizable to save
// the Zip Code between browser sessions.
[Personalizable()]
public virtual string ZipCode
{
get { return zipCodeText; }
set { zipCodeText = value; }
}
// This is the callback method that returns the provider.
[ConnectionProvider("Zip Code")]
public IZipCode ProvideIZipCode()
{
return this;
}
protected override void CreateChildControls()
{
Controls.Clear();
input = new TextBox();
this.Controls.Add(input);
send = new Button();
send.Text = "Enter 5-digit Zip Code";
send.Click += new EventHandler(this.submit_Click);
this.Controls.Add(send);
}
private void submit_Click(object sender, EventArgs e)
{
if (!string.IsNullOrEmpty(input.Text))
{
zipCodeText = Page.Server.HtmlEncode(input.Text);
input.Text = String.Empty;
}
}
}
[AspNetHostingPermission(SecurityAction.Demand,
Level = AspNetHostingPermissionLevel.Minimal)]
[AspNetHostingPermission(SecurityAction.InheritanceDemand,
Level = AspNetHostingPermissionLevel.Minimal)]
public class WeatherWebPart : WebPart
{
private IZipCode _provider;
string _zipSearch;
Label DisplayContent;
// This method is identified by the ConnectionConsumer
// attribute, and is the mechanism for connecting with
// the provider.
[ConnectionConsumer("Zip Code")]
public void GetIZipCode(IZipCode Provider)
{
_provider = Provider;
}
protected override void OnPreRender(EventArgs e)
{
EnsureChildControls();
if (this._provider != null)
{
_zipSearch = _provider.ZipCode.Trim();
DisplayContent.Text = "My Zip Code is: " + _zipSearch;
}
}
protected override void CreateChildControls()
{
Controls.Clear();
DisplayContent = new Label();
this.Controls.Add(DisplayContent);
}
}
}
Imports System.Web
Imports System.Web.Security
Imports System.Security.Permissions
Imports System.Web.UI
Imports System.Web.UI.WebControls
Imports System.Web.UI.WebControls.WebParts
Namespace Samples.AspNet.VB.Controls
<AspNetHostingPermission(SecurityAction.Demand, _
Level:=AspNetHostingPermissionLevel.Minimal)> _
<AspNetHostingPermission(SecurityAction.InheritanceDemand, _
Level:=AspNetHostingPermissionLevel.Minimal)> _
Public Interface IZipCode
Property ZipCode() As String
End Interface
<AspNetHostingPermission(SecurityAction.Demand, _
Level:=AspNetHostingPermissionLevel.Minimal)> _
<AspNetHostingPermission(SecurityAction.InheritanceDemand, _
Level:=AspNetHostingPermissionLevel.Minimal)> _
Public Class ZipCodeWebPart
Inherits WebPart
Implements IZipCode
Private zipCodeText As String = String.Empty
Private input As TextBox
Private send As Button
Public Sub New()
End Sub
' Make the implemented property personalizable to save
' the Zip Code between browser sessions.
<Personalizable()> _
Public Property ZipCode() As String _
Implements IZipCode.ZipCode
Get
Return zipCodeText
End Get
Set(ByVal value As String)
zipCodeText = value
End Set
End Property
' This is the callback method that returns the provider.
<ConnectionProvider("Zip Code")> _
Public Function ProvideIZipCode() As IZipCode
Return Me
End Function
Protected Overrides Sub CreateChildControls()
Controls.Clear()
input = New TextBox()
Me.Controls.Add(input)
send = New Button()
send.Text = "Enter 5-digit Zip Code"
AddHandler send.Click, AddressOf Me.submit_Click
Me.Controls.Add(send)
End Sub
Private Sub submit_Click(ByVal sender As Object, _
ByVal e As EventArgs)
If input.Text <> String.Empty Then
zipCodeText = Page.Server.HtmlEncode(input.Text)
input.Text = String.Empty
End If
End Sub
End Class
<AspNetHostingPermission(SecurityAction.Demand, _
Level:=AspNetHostingPermissionLevel.Minimal)> _
<AspNetHostingPermission(SecurityAction.InheritanceDemand, _
Level:=AspNetHostingPermissionLevel.Minimal)> _
Public Class WeatherWebPart
Inherits WebPart
Private _provider As IZipCode
Private _zipSearch As String
Private DisplayContent As Label
' This method is identified by the ConnectionConsumer
' attribute, and is the mechanism for connecting with
' the provider.
<ConnectionConsumer("Zip Code")> _
Public Sub GetIZipCode(ByVal Provider As IZipCode)
_provider = Provider
End Sub
Protected Overrides Sub OnPreRender(ByVal e As EventArgs)
EnsureChildControls()
If Not (Me._provider Is Nothing) Then
_zipSearch = _provider.ZipCode.Trim()
DisplayContent.Text = "My Zip Code is: " + _zipSearch
End If
End Sub
Protected Overrides Sub CreateChildControls()
Controls.Clear()
DisplayContent = New Label()
Me.Controls.Add(DisplayContent)
End Sub
End Class
End Namespace
在瀏覽器中載入網頁之後，按一下 [ 顯示模式 ] 下拉式清單控制項，然後選取 [ 連線 ] 以切換頁面以連線模式。 連接模式會 <asp:connectionszone> 使用 元素，讓您建立控制項之間的連線。 在連線模式中，按一下 郵遞區號 控制項標題列中的向下箭號，以啟動其動詞功能表，然後按一下 [ 連接]。 連線 UI 出現之後，按一下 [ 建立取用者連線] 連結。 有下拉式清單控制項的儲存格隨即出現。 在下拉式清單中選取 [天氣控制項 ]，然後按一下 [ 連線 ] 以完成兩個控制項的連接。 按一下 [關閉]，然後使用 [ 顯示模式 ] 下拉式清單，將頁面傳回正常瀏覽模式。 您可以輸入郵遞區號，而取用者控制項將會以您輸入的值進行更新。 ZipCode因為屬性在原始程式碼中以 屬性標示 Personalizable ，所以這個屬性值會在瀏覽器會話之間保存，因此會儲存使用者輸入的值。 更複雜的取用者控制項可以取得郵遞區號資訊、根據程式碼查閱天氣資訊，並將其顯示給使用者。
備註
控制項 WebPartManager 可作為 Web 元件應用程式的中樞或控制中心。 每個使用 Web 元件控制項的頁面都必須有一個且唯一 WebPartManager 的控制項實例。 如同 Web 元件應用程式的大部分層面，控制項 WebPartManager 只適用于已驗證的使用者。 此外，其功能幾乎完全與繼承自 WebZone 類別之 Web 元件區域內的伺服器控制項搭配運作。 位於這些區域外部頁面的伺服器控制項，可以有非常少的網頁元件功能或與 WebPartManager 控制項的互動。
做為頁面上網頁元件功能的中樞， WebPartManager 控制項會執行下表所述的工作種類。
| 工作類別 | 控制項的功能 |
|---|---|
| 追蹤網頁元件控制項 | 在提供 Web 元件功能的頁面上，持續追蹤許多不同類型的控制項，包括 WebPart 控制項、連線、區域等等。 |
| 新增和移除網頁元件控制項 | 提供在頁面上新增、刪除和關閉 WebPart 控制項的方法。 |
| 管理連線 | 建立控制項之間的連線，並監視連線以及新增和移除它們的程式。 |
| 個人化控制項和頁面 | 可讓使用者將控制項移至頁面上的不同位置，並啟動使用者可以編輯控制項的外觀、屬性和行為的檢視。 在每個頁面上維護使用者特定的個人化設定。 |
| 在不同頁面檢視之間切換 | 在頁面的不同特製化檢視之間切換頁面，讓使用者可以執行某些工作，例如變更版面配置或編輯控制項。 |
| 引發 Web 元件生命週期事件 | 定義、引發及讓開發人員處理 Web 元件控制項的生命週期事件，例如新增、移動、連接或刪除控制項時。 |
| 啟用控制項的匯入和匯出 | 匯出包含控制項屬性狀態的 WebPart XML 資料流程，並允許使用者匯入檔案，以方便將其他頁面或網站中的複雜控制項個人化。 |
類別 WebPartManager 有一組大型的屬性。 與 WebPartManager 追蹤其他控制項的角色一致，它有一些屬性參考 Web 元件控制項或其他特殊網頁元件物件的集合。 、、、、、 DynamicConnectionsSupportedDisplayModes 、 WebParts 和 Zones 屬性是 控制項用於追蹤和其他管理工作的所有集合 WebPartManager 。 DisplayModesControlsConnectionsAvailableTransformers
另一組屬性包含可自訂的警告，這些警告適用于在 Web 元件應用程式中發生的特定案例中。 這些包括 CloseProviderWarning 、 DeleteWarning 和 ExportSensitiveDataWarning 屬性。
類別 WebPartManager 會覆寫其部分基底繼承的屬性，這些屬性是由許多 Web 服務器控制項使用。 這些包括 EnableTheming 、 SkinID 和 Visible 屬性。
最後，有一組屬性可用於存取應用程式的目前狀態。 屬性 DisplayMode 表示頁面所在的目前顯示模式。 屬性 EnableClientScript 指出是否允許控制項轉譯用戶端腳本，這在使用者可能有不同功能的瀏覽器或已關閉腳本的情況下相關。 屬性 Internals 適用于參考公用程式類別，其中包含一些用於擴充性案例的重要 Web 元件方法呼叫。 藉由隱藏對個別類別的 WebPartManagerInternals 呼叫， (類別) ， WebPartManager 就會簡化類別本身的 API。 屬性 Personalization 可讓您存取儲存使用者個人化設定的個人化物件，並將該資料保存到永久儲存區。 屬性 SelectedWebPart 會指出使用者或應用程式目前選取頁面上的哪個 WebPart 控制項。 屬性 IPersonalizable.IsDirty 會指出控制項上的 WebPart 自訂個人化資料是否已變更。
控制項 WebPartManager 包含五種內建顯示模式，或網頁的檢視。 開發人員可以擴充這項功能，藉由擴充類別或 ToolZone 類別之類的 WebZone 類型來建立自訂顯示模式。 使用者可以將頁面切換成各種顯示模式，前提是對應至指定顯示模式的適當控制項種類會出現在頁面上。
注意
您可以擴充這項功能，讓使用者可以切換到自訂顯示模式，而不需要頁面上有對應的區域。 不過，預設行為是顯示模式對應到區域。
標準顯示模式是由 類別中的 WebPartManager 公用欄位表示。 下表摘要說明欄位及其參考的顯示模式。 如上所述，頁面目前的顯示模式一律會在 屬性中 DisplayMode 參考，而且特定頁面上可能顯示模式集合，因為頁面上存在的區域種類包含在 屬性中 SupportedDisplayModes 。
| 欄位 | 顯示模式詳細資料 |
|---|---|
| BrowseDisplayMode | 網頁的一般使用者檢視;預設和最常見的顯示模式。 |
| DesignDisplayMode | 使用者可以重新排列或刪除控制項以變更版面配置的檢視。 |
| EditDisplayMode | 編輯使用者介面 (UI) 可見的檢視;使用者可以編輯在一般瀏覽模式中可見之控制項的外觀、屬性和行為。 |
| CatalogDisplayMode | 目錄 UI 變成可見的檢視;使用者可以從可用控制項目錄將控制項新增至頁面。 |
| ConnectDisplayMode | 顯示連接 UI 的檢視;使用者可以連接、管理或中斷控制項之間的連線。 |
控制項 WebPartManager 也包含一些事件，這些事件在網頁元件頁面和控制項的生命週期中很重要。 這些事件提供 Web 元件控制項行為的精確程式設計控制。 大部分的方法都直接與 WebPart 控制項 (或其他放置在 WebPartZoneBase 區域中的伺服器或使用者控制項有關，讓控制項可以做為 WebPart 控制項) 。 不過，有些事件與頁面上頁面或連線的狀態有關。 下表列出可用的事件，並摘要說明其用途。
注意
在下表的所有情況下，「control」 這個字是指 WebPart 位於區域中的控制項或任何伺服器控制項，並在執行時間以 GenericWebPart 物件包裝。
| 事件 | 描述 |
|---|---|
| AuthorizeWebPart | 在控制項新增至頁面之前發生，以確認它已獲授權。 |
| ConnectionsActivated | 會在頁面上的所有連線都啟用之後發生。 |
| ConnectionsActivating | 發生在啟動頁面上所有連線的程式之前。 |
| DisplayModeChanged | 發生于頁面目前的顯示模式變更之後。 |
| DisplayModeChanging | 發生在變更頁面顯示模式的程式之前。 |
| SelectedWebPartChanged | 發生于取消選取控制項之後。 |
| SelectedWebPartChanging | 發生在取消選取控制項的程式之前。 |
| WebPartAdded | 發生于控制項新增至區域之後。 |
| WebPartAdding | 發生于將控制項加入區域的程式之前。 |
| WebPartClosed | 發生于控制項關閉 (從頁面) 移除之後。 |
| WebPartClosing | 發生在關閉控制項的程式之前。 |
| WebPartDeleted | 發生于動態控制項的實例 (以程式設計方式建立或從目錄) 新增的實例已永久刪除之後。 |
| WebPartDeleting | 發生在刪除動態控制項的程式之前。 |
| WebPartMoved | 發生于控制項在其區域內或移至另一個區域之後。 |
| WebPartMoving | 發生于移動控制項的程式之前。 |
| WebPartsConnected | 發生在選取參與連線的兩個控制項已建立連接之後。 |
| WebPartsConnecting | 發生在連接兩個控制項的程式之前。 |
| WebPartsDisconnected | 發生于兩個連接控制項已中斷連線之後。 |
| WebPartsDisconnecting | 發生在中斷兩個控制項的連接之前。 |
控制項 WebPartManager 有許多管理網頁元件頁面的方法。 此處未列出的一組大型方法，是名稱採用 OnEventName格式的方法。 這些方法通常會引發其相關聯的事件，並提供 類型 WebPartEventHandler 為 的處理常式。 大部分的方法都可以由繼承自 類別的 WebPartManager 開發人員覆寫。 此外，頁面開發人員可以為與這些方法相關聯的事件提供自訂處理常式。 例如，在事件的情況下 WebPartAdded ，頁面開發人員可以將屬性新增 OnWebPartAdded 至 <asp:webpartmanager> 網頁標記中的 元素，然後將自訂方法名稱指派給 屬性，以提供事件的自訂處理。 屬性會對應至 OnWebPartAdded 方法，而這個基本事件處理模式適用于大部分的 Web 元件事件及其相關聯的方法。
此外， WebPartManager 控制項具有管理控制項 (和伺服器或使用者控制項做為 WebPart 控制項) 工作的特定 WebPart 方法。 這些方法包括 、、、 CloseWebPartCopyWebPartDisconnectWebPartDeleteWebPartCreateWebPart 、 BeginWebPartEditing 、 EndWebPartEditingIsAuthorizedGetGenericWebPartExportWebPartImportWebPart 和 。 MoveWebPartAuthorizeWebPartAddWebPart
另一組方法特別適用于連線。 這包括 、 BeginWebPartConnecting 、、 ConnectWebPartsCanConnectWebParts 、 CreateAvailableTransformers 、 DisconnectWebPart 、 DisconnectWebParts 、 EndWebPartConnecting 、 GetConsumerConnectionPoints 和 GetProviderConnectionPoints 等 ActivateConnections 方法。
最後，某些 WebPartManager 方法著重于個人化功能。 這些包括 CreatePersonalization、LoadControlState、SaveCustomPersonalizationState、SetPersonalizationDirty、IPersonalizable.Load、IPersonalizable.Save 和 SaveControlState。
如需可透過 Internals 屬性存取之其他 WebPartManager 方法的詳細資訊，請參閱 類別 WebPartManagerInternals 的檔。
給繼承者的注意事項
控制項 WebPartManager 的設計目的是要擴充。 由於它是 Web 元件應用程式的核心，因此當您想要在 Web 元件控制項集中擴充某些特定類型或控制項時，在許多情況下，您也必須擴充 WebPartManager 類別，因為可能需要有一些屬性或方法，才能讓自訂類型在 Web 元件應用程式的內容中運作。 網頁元件參考檔 (請參閱 System.Web.UI.WebControls.WebParts) 、討論如何擴充網頁元件類型時，經常提及擴充類別所需執行 WebPartManager 哪些動作，或示範如何在程式碼範例中擴充它。
建構函式
| WebPartManager() |
初始化 WebPartManager 類別的新執行個體。 |
欄位
| BrowseDisplayMode |
表示包含 Web 組件控制項之頁面的預設顯示模式。 此欄位是唯讀的。 |
| CatalogDisplayMode |
表示從控制項目錄將伺服器控制項加入至網頁時所使用的顯示模式。 此欄位是唯讀的。 |
| ConnectDisplayMode |
表示用來顯示特別使用者介面 (UI) 的顯示模式，供使用者管理 WebPart 控制項之間的連接。 此欄位是唯讀的。 |
| DesignDisplayMode |
表示包含 Web 組件控制項之網頁的配置變更時所使用的顯示模式。 此欄位是唯讀的。 |
| EditDisplayMode |
表示使用者可用來編輯和修改伺服器控制項的顯示模式。 此欄位是唯讀的。 |
屬性
| Adapter |
針對控制項取得瀏覽器的特定配置器。 (繼承來源 Control) |
| AppRelativeTemplateSourceDirectory |
取得或設定包含了此控制項之 Page 或 UserControl 物件的相對應用程式虛擬目錄。 (繼承來源 Control) |
| AvailableTransformers |
取得 WebPartTransformer 物件的集合，這些物件可用於建立伺服器控制項之間的 Web 組件連接。 |
| BindingContainer |
取得包含了此控制項之資料繫結的控制項。 (繼承來源 Control) |
| ChildControlsCreated |
取得值，指出是否已經建立伺服器控制項的子控制項。 (繼承來源 Control) |
| ClientID |
取得 ASP.NET 所產生之 HTML 標記的控制項識別碼。 (繼承來源 Control) |
| ClientIDMode |
取得或設定用來產生 ClientID 屬性值的演算法。 (繼承來源 Control) |
| ClientIDSeparator |
取得字元值，表示在 ClientID 屬性中所使用的分隔字元。 (繼承來源 Control) |
| CloseProviderWarning |
取得或設定警告，當使用者關閉連接中做為其他控制項之提供者的控制項時顯示此警告。 |
| Connections |
取得網頁上所有目前連接之集合的參考。 |
| Context |
取得與目前 Web 要求的伺服器控制項關聯的 HttpContext 物件。 (繼承來源 Control) |
| Controls |
取得網頁的 WebPart 區域中所包含並且由 WebPartZoneBase 控制項管理之所有 WebPartManager、伺服器或使用者控制項的集合。 |
| DataItemContainer |
如果命名容器實作 IDataItemContainer，則取得命名容器的參考。 (繼承來源 Control) |
| DataKeysContainer |
如果命名容器實作 IDataKeysControl，則取得命名容器的參考。 (繼承來源 Control) |
| DeleteWarning |
取得或設定自訂警告訊息，當使用者刪除控制項時，向使用者顯示這則訊息。 |
| DesignMode |
取得值，指出控制項是否正用於設計介面上。 (繼承來源 Control) |
| DisplayMode |
取得或設定包含 Web 組件控制項之網頁的現用顯示模式。 |
| DisplayModes |
取得與 WebPartManager 控制項關聯之所有顯示模式的唯讀集合。 |
| DynamicConnections |
取得網頁上目前所有動態連接的集合。 |
| EnableClientScript |
取得或設定值，判斷在包含了 WebPartManager 控制項的網頁上是否啟用用戶端指令碼。 |
| EnableTheming |
取得值，指出網頁上是否允許佈景主題之使用。 |
| EnableViewState |
取得或設定值，該值表示伺服器控制項是否對要求的用戶端而言保持其檢視狀態，以及它包含的任何子控制項狀態。 (繼承來源 Control) |
| Events |
取得控制項事件處理常式委派 (Delegate) 的清單。 這個屬性是唯讀的。 (繼承來源 Control) |
| ExportSensitiveDataWarning |
取得或設定警告訊息的文字，當使用者嘗試從 WebPart 控制項匯出敏感性狀態資料時，會顯示此警告訊息文字。 |
| HasChildViewState |
取得值，指出目前伺服器控制項的子控制項是否有任何已儲存的檢視狀態設定。 (繼承來源 Control) |
| ID |
取得或設定指派給伺服器控制項的程式設計識別項。 (繼承來源 Control) |
| IdSeparator |
取得用來分隔控制項識別項的字元。 (繼承來源 Control) |
| Internals |
取得 WebPartManagerInternals 類別的參考，用來結合和分離 WebPartManager 類別中實際實作、但對控制項開發人員非常有用的一組方法。 |
| IsChildControlStateCleared |
取得值，指出這個控制項中所包含的控制項是否有控制項狀態。 (繼承來源 Control) |
| IsCustomPersonalizationStateDirty |
取得值，指出是否已執行個人化變更，並影響 WebPartManager 控制項所控制的頁面層次個人化細節。 |
| IsTrackingViewState |
取得值，指出伺服器控制項是否正在儲存檢視狀態的變更。 (繼承來源 Control) |
| IsViewStateEnabled |
取得值，指出這個控制項是否已啟用檢視狀態。 (繼承來源 Control) |
| LoadViewStateByID |
取得值，指出控制項是否依 ID (而不是索引) 參與載入其檢視狀態。 (繼承來源 Control) |
| MediumPermissionSet |
取得 PermissionSet 物件，該物件僅允許 Execution 使用權限和 Medium 使用權限。 |
| MinimalPermissionSet |
取得 PermissionSet 物件，該物件僅允許 Execution 使用權限和 Minimal 使用權限。 |
| NamingContainer |
取得伺服器控制項命名容器的參考，其建立唯一命名空間，在具有相同 ID 屬性值的伺服器控制項之間作區別。 (繼承來源 Control) |
| Page |
取得含有伺服器控制項的 Page 執行個體的參考。 (繼承來源 Control) |
| Parent |
在網頁控制階層架構中取得伺服器控制項之父控制項的參考。 (繼承來源 Control) |
| Personalization |
取得包含網頁個人化資料之物件的參考。 |
| RenderingCompatibility |
取得值，這個值會指定將與呈現 HTML 相容的 ASP.NET 版本。 (繼承來源 Control) |
| SelectedWebPart |
取得 WebPart 或其他伺服器控制項的參考，這個控制項目前選為要進行編輯或建立與另一個控制項的連接。 |
| Site |
當呈現在設計介面上時，取得裝載目前控制項之容器的資訊。 (繼承來源 Control) |
| SkinID |
取得或設定空字串 ("")，不讓任何面板套用至 WebPartManager 控制項。 |
| StaticConnections |
取得網頁上定義為靜態連接之所有 WebPartConnection 物件集合的參考。 |
| SupportedDisplayModes |
取得特定網頁上所有可用顯示模式的唯讀集合。 |
| TemplateControl |
取得或設定包含了此控制項之樣板的參考。 (繼承來源 Control) |
| TemplateSourceDirectory |
取得包含目前伺服器控制項的 Page 或 UserControl 的虛擬目錄。 (繼承來源 Control) |
| UniqueID |
取得伺服器控制項唯一的、符合階層架構的識別項。 (繼承來源 Control) |
| ValidateRequestMode |
取得或設定值，指出控制項是否對來自瀏覽器的用戶端輸入檢查潛在的危險值。 (繼承來源 Control) |
| ViewState |
取得狀態資訊的字典，允許您在相同網頁的多個要求之間，儲存和還原伺服器控制項的檢視狀態。 (繼承來源 Control) |
| ViewStateIgnoresCase |
取得值，指出 StateBag 物件是否不區分大小寫。 (繼承來源 Control) |
| ViewStateMode |
取得或設定這個控制項的檢視狀態模式。 (繼承來源 Control) |
| Visible |
取得允許子控制項為可見的值。 |
| WebParts |
取得網頁上 WebPart 控制項所追蹤之所有 WebPartManager 控制項的參考。 |
| Zones |
取得網頁上所有 WebPartZoneBase 區域之集合的參考。 |
方法
事件
| AuthorizeWebPart |
當呼叫 IsAuthorized 方法，以判斷 WebPart 或伺服器控制項是否可以加入至頁面時發生。 |
| ConnectionsActivated |
在頁面上所有目前的 Web 組件連接不僅已建立，而且每個連接中的消費者和提供者控制項也已經開始共用資料之後發生。 |
| ConnectionsActivating |
在網頁上啟動所有已建立之 Web 組件連接的程序中發生。 |
| DataBinding |
發生於伺服器控制項繫結至資料來源時。 (繼承來源 Control) |
| DisplayModeChanged |
Web 組件頁面目前的顯示模式變更之後發生。 |
| DisplayModeChanging |
使用者按一下網頁上的動詞命令，而開始切換至不同顯示模式的程序之後發生。 |
| Disposed |
發生於伺服器控制項從記憶體釋放時，這是在要求 ASP.NET 網頁時，伺服器控制項生命週期的最後階段。 (繼承來源 Control) |
| Init |
發生於初始化伺服器控制項時，是其生命週期中的第一個步驟。 (繼承來源 Control) |
| Load |
發生於載入伺服器控制項至 Page 物件時。 (繼承來源 Control) |
| PreRender |
在 Control 物件載入之後但在呈現之前發生。 (繼承來源 Control) |
| SelectedWebPartChanged |
某個 WebPart 控制項的選取範圍已變更並移至網頁上的另一個控制項之後發生。 |
| SelectedWebPartChanging |
在網頁上變更目前選取之 WebPart 或伺服器控制項的程序中發生。 |
| Unload |
發生於伺服器控制項從記憶體卸載時。 (繼承來源 Control) |
| WebPartAdded |
在動態 WebPart 或其他伺服器控制項已加入至 WebPartZoneBase 區域之後發生，以表示控制項已成功加入。 |
| WebPartAdding |
將動態 WebPart 或其他伺服器控制項加入至 WebPartZoneBase 區域的程序中發生。 |
| WebPartClosed |
當 WebPart 控制項 (或伺服器或使用者控制項) 從頁面移除時發生。 |
| WebPartClosing |
從頁面移除 WebPart 控制項 (或伺服器或使用者控制項) 的程序中發生。 |
| WebPartDeleted |
從 WebPart 區域中已刪除 WebPartZoneBase 或其他伺服器控制項之後發生。 |
| WebPartDeleting |
將動態 WebPart 或其他伺服器控制項的執行個體從 WebPartZoneBase 區域永久刪除的程序中發生。 |
| WebPartMoved |
WebPart 或伺服器控制項已移至網頁上的不同位置之後發生。 |
| WebPartMoving |
在移動 WebPart 區域所包含之 WebPartZoneBase 或其他伺服器控制項的程序中發生。 |
| WebPartsConnected |
在 WebPart 控制項 (或伺服器或使用者控制項) 之間建立特定連接之後發生。 |
| WebPartsConnecting |
在建立 WebPart 控制項 (或位於 WebPartZoneBase 區域中的伺服器或使用者控制項) 之間的連接程序中發生。 |
| WebPartsDisconnected |
兩個 WebPart 或伺服器控制項之間的連接已結束之後發生。 |
| WebPartsDisconnecting |
在結束先前連接之 WebPart 或伺服器控制項的連接程序中發生。 |
明確介面實作
擴充方法
| FindDataSourceControl(Control) |
傳回與指定之控制項的資料控制項相關聯的資料來源。 |
| FindFieldTemplate(Control, String) |
傳回在指定之控制項的命名容器中所指定資料行的欄位樣板。 |
| FindMetaTable(Control) |
傳回包含資料控制項的中繼資料表物件。 |
| GetDefaultValues(INamingContainer) |
取得所指定資料控制項的預設值集合。 |
| GetMetaTable(INamingContainer) |
取得所指定資料控制項中的資料表中繼資料。 |
| SetMetaTable(INamingContainer, MetaTable) |
設定所指定資料控制項中的資料表中繼資料。 |
| SetMetaTable(INamingContainer, MetaTable, IDictionary<String,Object>) |
設定所指定資料控制項的資料表中繼資料及預設值對應。 |
| SetMetaTable(INamingContainer, MetaTable, Object) |
設定所指定資料控制項的資料表中繼資料及預設值對應。 |
| TryGetMetaTable(INamingContainer, MetaTable) |
判斷資料表中繼資料是否可供使用。 |
| EnableDynamicData(INamingContainer, Type) |
針對指定的資料控制項啟用動態資料行為。 |
| EnableDynamicData(INamingContainer, Type, IDictionary<String,Object>) |
針對指定的資料控制項啟用動態資料行為。 |
| EnableDynamicData(INamingContainer, Type, Object) |
針對指定的資料控制項啟用動態資料行為。 |
適用於
另請參閱
意見反應
即將登場：在 2024 年，我們將逐步淘汰 GitHub 問題作為內容的意見反應機制，並將它取代為新的意見反應系統。 如需詳細資訊，請參閱：https://aka.ms/ContentUserFeedback。
提交並檢視相關的意見反應