IWebPart 介面

參考

定義

命名空間:: System.Web.UI.WebControls.WebParts

組件:: System.Web.dll

重要

部分資訊涉及發行前產品，在發行之前可能會有大幅修改。 Microsoft 對此處提供的資訊，不做任何明確或隱含的瑕疵擔保。

定義由 ASP.NET WebPart 控制項使用的通用使用者介面 (UI) 屬性。

public interface class IWebPart

public interface IWebPart

type IWebPart = interface

Public Interface IWebPart

衍生: System.Web.UI.WebControls.WebParts.WebPart

範例

下列程式代碼範例示範如何在使用者控件中實 IWebPart 作介面。這是一個簡單的實作，會以最少的方式示範如何實作屬性。

程式代碼範例的第一個部分會顯示使用者控制項。使用者控件會實作介面的所有屬性 IWebPart ，再加上兩個系結至使用者介面中控件的額外公用屬性。這兩個自定義屬性會使用 Personalizable 屬性，讓這些屬性中的值可以跨瀏覽器會話儲存。請注意，在基 WebPart 類實作中，介面的所有屬性 IWebPart 也會實作為可個人化，但不是在此程式代碼範例中。

<%@ control language="C#" classname="AccountUserControlCS"%>
<%@ implements interface="System.Web.UI.WebControls.WebParts.IWebPart" %>

<script runat="server">

  private string m_Description;
  private string m_Title;
  private string m_TitleIconImageUrl;
  private string m_TitleUrl;
  private string m_CatalogIconImageUrl;
  
  [Personalizable]
  public string UserName
  {
    get
    {
      if(String.IsNullOrEmpty(Textbox1.Text))
        return String.Empty;
      else
        return Textbox1.Text;
    }
    
    set
    {
      Textbox1.Text = value;
    }
  }
    
  [Personalizable]
  public string Phone
  {
    get
    {
      if(String.IsNullOrEmpty(Textbox2.Text))
        return String.Empty;
      else
        return Textbox2.Text;
    }
    
    set
    {
      Textbox2.Text = value;
    }
  }

  // <snippet3>
  public string Description
  {
    get
    {
      object objTitle = ViewState["Description"];
      if (objTitle == null)
        return String.Empty;

      return (string)objTitle;
    }
    set
    {
      ViewState["Description"] = value;
    }
  }
  // </snippet3>

  // <snippet4>
  public string Title
  {
    get
    {
      object objTitle = ViewState["Title"];
      if (objTitle == null)
        return String.Empty;

      return (string)objTitle;
    }
    set
    {
      ViewState["Title"] = value;
    }
  }
  // </snippet4>

  // <snippet5>
  public string Subtitle
  {
    get
    {
      object objSubTitle = ViewState["Subtitle"];
      if (objSubTitle == null)
        return "My Subtitle";

      return (string)objSubTitle;
    }

  }
  // </snippet5>

  // <snippet6>
  public string TitleIconImageUrl
  {
    get
    {
      object objTitle = ViewState["TitleIconImageUrl"];
      if (objTitle == null)
        return String.Empty;

      return (string)objTitle;
    }
    set
    {
      ViewState["TitleIconImageUrl"] = value;
    }
  }
  // </snippet6>

  // <snippet7>
  public string TitleUrl
  {
    get
    {
      object objTitle = ViewState["TitleUrl"];
      if (objTitle == null)
        return String.Empty;

      return (string)objTitle;
    }
    set
    {
      ViewState["TitleUrl"] = value;
    }
  }
  // </snippet7>

  // <snippet8>
  public string CatalogIconImageUrl
  {
    get
    {
      object objTitle = ViewState["CatalogIconImageUrl"];
      if (objTitle == null)
        return String.Empty;

      return (string)objTitle;
    }
    set
    {
      ViewState["CatalogIconImageUrl"] = value;
    }
  }
  // </snippet8>
  
  // <snippet9>
  // Update the selected IWebPart property value.
  void Button1_Click(object sender, EventArgs e)
  {
    String propertyValue = Server.HtmlEncode(TextBox3.Text);
    TextBox3.Text = String.Empty;

    switch (RadioButtonList1.SelectedValue)
    {
      case "title":
        this.Title = propertyValue;
        break;
      case "description":
        this.Description = propertyValue;
        break;
      case "catalogiconimageurl":
        this.CatalogIconImageUrl = propertyValue;
        break;
      case "titleiconimageurl":
        this.TitleIconImageUrl = propertyValue;
        break;
      case "titleurl":
        this.TitleUrl = propertyValue;
        break;
      default:
        break;
    }
  }
  // </snippet9>
  
</script>
<div>
<asp:label id="Label1" runat="server" AssociatedControlID="Textbox1">
  Name</asp:label>
<asp:textbox id="Textbox1" runat="server" />
</div>
<div>
<asp:label id="Label2" runat="server" AssociatedControlID="Textbox2">
  Phone</asp:label>
<asp:textbox id="Textbox2" runat="server"></asp:textbox>
</div>
<div>
<asp:button id="Button2" runat="server" text="Save Form Values" />
</div>
<hr />
<asp:Label ID="Label3" Runat="server" Text="Label" 
  AssociatedControlID="RadioButtonList1">
  <h3>Update selected IWebPart property values.</h3>
</asp:Label>
<asp:RadioButtonList ID="RadioButtonList1" Runat="server">
  <asp:ListItem Value="title">Title</asp:ListItem>
  <asp:ListItem Value="description">Description</asp:ListItem>
  <asp:ListItem Value="catalogiconimageurl">CatalogIconImageUrl</asp:ListItem>
  <asp:ListItem Value="titleiconimageurl">TitleIconImageUrl</asp:ListItem>
  <asp:ListItem Value="titleurl">TitleUrl</asp:ListItem>
</asp:RadioButtonList>
<br />
<asp:Label ID="Label4" runat="server" Text="Label"
  AssociatedControlID="TextBox3">
Property Value:  
</asp:Label>
<asp:TextBox ID="TextBox3" runat="server">
</asp:TextBox>  
<br />  
<asp:Button ID="Button1" runat="server" 
  Text="Update Property" 
  OnClick="Button1_Click">
</asp:Button>

<%@ control language="VB" classname="AccountUserControlVB"%>
<%@ implements interface="System.Web.UI.WebControls.WebParts.IWebPart" %>

<script runat="server">

  Private m_Description As String
  Private m_Title As String
  Private m_TitleIconImageUrl As String
  Private m_TitleUrl As String
  Private m_CatalogIconImageUrl As String


  <Personalizable()> _
  Public Property UserName() As String
    Get
      If String.IsNullOrEmpty(Textbox1.Text) Then
        Return String.Empty
      Else
        Return Textbox1.Text
      End If
    End Get
    Set(ByVal value As String)
      Textbox1.Text = Value
    End Set
  End Property

  <Personalizable()> _
  Public Property Phone() As String
    Get
      If String.IsNullOrEmpty(Textbox2.Text) Then
        Return String.Empty
      Else
        Return Textbox2.Text
      End If
    End Get
    Set(ByVal value As String)
      Textbox2.Text = Value
    End Set
  End Property

  ' <snippet3>
  Public Property Description() As String _
    Implements IWebPart.Description
    Get
      Dim objTitle As Object = ViewState("Description")
      If objTitle Is Nothing Then
        Return String.Empty
      End If
      Return CStr(objTitle)
    End Get
    Set(ByVal value As String)
      ViewState("Description") = value
    End Set
  End Property
  ' </snippet3>
  
  ' <snippet4>
  Public Property Title() As String _
    Implements IWebPart.Title
    Get
      Dim objTitle As Object = ViewState("Title")
      If objTitle Is Nothing Then
        Return String.Empty
      End If
      Return CStr(objTitle)
    End Get
    Set(ByVal value As String)
      ViewState("Title") = value
    End Set
  End Property
  ' </snippet4>
  
  ' <snippet5>
  ReadOnly Property Subtitle() As String _
    Implements IWebPart.Subtitle
    Get
      Dim objSubTitle As Object = ViewState("Subtitle")
      If objSubTitle Is Nothing Then
        Return "My Subtitle"
      End If
      Return CStr(objSubTitle)
    End Get
  End Property
  ' </snippet5>
  
  ' <snippet6>
  Public Property TitleIconImageUrl() As String _
    Implements IWebPart.TitleIconImageUrl
    Get
      Dim objTitle As Object = ViewState("TitleIconImageUrl")
      If objTitle Is Nothing Then
        Return String.Empty
      End If
      Return CStr(objTitle)
    End Get
    Set(ByVal value As String)
      ViewState("TitleIconImageUrl") = value
    End Set
  End Property
  ' </snippet6>
  
  ' <snippet7>
  Public Property TitleUrl() As String _
    Implements IWebPart.TitleUrl
    Get
      Dim objTitle As Object = ViewState("TitleUrl")
      If objTitle Is Nothing Then
        Return String.Empty
      End If
      Return CStr(objTitle)
    End Get
    Set(ByVal value As String)
      ViewState("TitleUrl") = value
    End Set
  End Property
  ' </snippet7>
  
  ' <snippet8>
  Public Property CatalogIconImageUrl() As String _
    Implements IWebPart.CatalogIconImageUrl
    Get
      Dim objTitle As Object = ViewState("CatalogIconImageUrl")
      If objTitle Is Nothing Then
        Return String.Empty
      End If
      Return CStr(objTitle)
    End Get
    Set(ByVal value As String)
      ViewState("CatalogIconImageUrl") = value
    End Set
  End Property
  ' </snippet8>
  
  ' <snippet9>
  ' Update the selected IWebPart property value.
  Sub Button1_Click(ByVal sender As Object, ByVal e As EventArgs)
    Dim propertyValue As String = Server.HtmlEncode(TextBox3.Text)
    TextBox3.Text = String.Empty
      
    Select Case RadioButtonList1.SelectedValue
      Case "title"
        Me.Title = propertyValue
      Case "description"
        Me.Description = propertyValue
      Case "catalogiconimageurl"
        Me.CatalogIconImageUrl = propertyValue
      Case "titleiconimageurl"
        Me.TitleIconImageUrl = propertyValue
      Case "titleurl"
        Me.TitleUrl = propertyValue
      Case Else
    End Select

  End Sub 'Button1_Click
  ' </snippet9>
  
</script>
<div>
<asp:label id="Label1" runat="server" AssociatedControlID="Textbox1">
  Name</asp:label>
<asp:textbox id="Textbox1" runat="server" />
</div>
<div>
<asp:label id="Label2" runat="server" AssociatedControlID="Textbox2">
  Phone</asp:label>
<asp:textbox id="Textbox2" runat="server"></asp:textbox>
</div>
<div>
<asp:button id="Button2" runat="server" text="Save Form Values" />
</div>
<hr />
<asp:Label ID="Label3" Runat="server" AssociatedControlID="RadioButtonList1">
  <h3>Update selected IWebPart property values.</h3>
</asp:Label>
<asp:RadioButtonList ID="RadioButtonList1" Runat="server">
  <asp:ListItem Value="title">Title</asp:ListItem>
  <asp:ListItem Value="description">Description</asp:ListItem>
  <asp:ListItem Value="catalogiconimageurl">CatalogIconImageUrl</asp:ListItem>
  <asp:ListItem Value="titleiconimageurl">TitleIconImageUrl</asp:ListItem>
  <asp:ListItem Value="titleurl">TitleUrl</asp:ListItem>
</asp:RadioButtonList>
<br />
<asp:Label ID="Label4" runat="server" AssociatedControlID="TextBox3">
Property Value:  
</asp:Label>
<asp:TextBox ID="TextBox3" runat="server">
</asp:TextBox>  
<br />  
<asp:Button ID="Button1" runat="server" 
  Text="Update Property" 
  OnClick="Button1_Click">
</asp:Button>

程式代碼範例的第二個部分會顯示裝載使用者控件的網頁。頁面有控件 WebPartZone ，其中會參考使用者控件。請注意，使用者控件的標記中會以宣告方式設定數 IWebPart 個介面的屬性值，這可讓控件在設計時間和運行時間的行為和看起來類似 WebPart 控制件。如果您在瀏覽器中載入頁面，則可以使用頁面上的UI來示範在運行時間以程式設計方式變更實 IWebPart 作屬性值的能力。當您變更某些屬性值時，頁面上的變更並不明顯，但在屬性) (TitleIconImageUrl 頁面來源中會顯示，或儲存在應用程式的狀態數據中， (CatalogIconImageUrl 屬性) 。

重要

這個範例有一個可接受使用者輸入的文字方塊，這可能會造成安全性威脅。根據預設，ASP.NET Web 網頁會驗證使用者輸入未包含指令碼或 HTML 項目。如需詳細資訊，請參閱 Script Exploits Overview (指令碼攻擊概觀)。

<%@ page language="c#" %>
<%@ register tagprefix="uc1" 
    tagname="AccountUserControlCS" 
    src="AccountUserControlcs.ascx"%>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" >
  <head runat="server">
    <title>
      Personalizable User Control with IWebPart Properties
    </title>
  </head>
  <body>
    <form id="form1" runat="server">
      <asp:webpartmanager id="WebPartManager1" runat="server" />
      <asp:webpartzone 
        id="zone1" 
        runat="server" 
        headertext="Main" 
        CloseVerb-Enabled="false">
        <zonetemplate>
          <uc1:AccountUserControlCS 
            runat="server" 
            id="accountwebpart" 
            title="Account Form"
            Description="Account Form with default values."
            CatalogIconImageUrl="MyCatalogIcon.gif"
            TitleIconImageUrl="MyTitleIcon.gif"
            TitleUrl="MyUrl.html"/>
        </zonetemplate>
      </asp:webpartzone>    
    </form>
  </body>
</html>

<%@ page language="VB" %>
<%@ register tagprefix="uc1" 
    tagname="AccountUserControlVB" 
    src="AccountUserControlvb.ascx"%>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" >
  <head runat="server">
    <title>
      Personalizable User Control with IWebPart Properties
    </title>
  </head>
  <body>
    <form id="form1" runat="server">
      <asp:webpartmanager id="WebPartManager1" runat="server" />
      <asp:webpartzone 
        id="zone1" 
        runat="server" 
        headertext="Main" 
        CloseVerb-Enabled="false">
        <zonetemplate>
          <uc1:AccountUserControlVB 
            runat="server" 
            id="accountwebpart" 
            title="Account Form"
            Description="Account Form with default values."
            CatalogIconImageUrl="MyCatalogIcon.gif"
            TitleIconImageUrl="MyTitleIcon.gif"
            TitleUrl="MyUrl.html"/>
        </zonetemplate>
      </asp:webpartzone>    
    </form>
  </body>
</html>

備註

介面 IWebPart 提供數個UI導向屬性，可增強使用 WebPart 控件的用戶體驗。當您建立衍生自基 WebPart 類的控件時，您會取得介面中所有屬性的 IWebPart 實作，因為 WebPart 基類會實作這個介面。

您可以使用現有的使用者控件、ASP.NET 控件，或不是繼承自 WebPart 類別的自定義伺服器控制件作為 Web 元件應用程式的一部分，而且也可以使用介面所 IWebPart 宣告的這些 UI 導向屬性。如果您將現有的伺服器控制件放在 WebPartZoneBase 區域中，在運行時間會以 GenericWebPart 對象包裝它們。因為類別 GenericWebPart 繼承自 WebPart 基類，所以它可讓現有的伺服器控件做為 true WebPart 控件，並將其新增至介面的屬性 IWebPart 。

如果您將不是 WebPart 控件的伺服器控件放在區域中，它們可以在運行時間使用 IWebPart 屬性，也可以在頁面的標記中宣告這些屬性的值， (頁面持續性格式) 。不過，由於這些屬性僅適用於運行時間的伺服器控制項，因此 IntelliSense 等設計時間編碼功能無法辨識 IWebPart 在伺服器控制項上宣告的屬性。當您載入頁面時，這些控件上的宣告屬性仍可運作，但 Microsoft Visual Studio 在設計時間無法將屬性辨識為有效。如果您想要將 IWebPart 屬性新增至現有的伺服器和使用者控制項，以增強設計時間用戶體驗，您可以在伺服器控制項中實 IWebPart 作介面。

實作 IWebPart 介面的主要原因是不支援使用 expando (自定義) 屬性的控件。 Expando 屬性是字串，可透過 IAttributeAccessor 介面動態新增至類別做為屬性。實作此介面的控件，包括 WebControl 類別及其子系，都可以使用 expando 屬性。因此，所有 ASP.NET 伺服器控制件、衍生自它們的自定義控制件、Web 使用者控制項和 WebPart 控制項都支援使用 expando 屬性。但直接繼承自基 Control 類的自定義控件不支援 expando 屬性。因此，如果您在內WebPartZone宣告這些控制件，您將無法在控件上宣告通用IWebPart屬性，例如和 Description。Title 如果您想要搭配這類控件使用這些屬性，您必須實作 IWebPart 介面。

給實施者的注意事項

通常您不需要在自定義WebPart控件或伺服器控件上實IWebPart作介面，因為基WebPart類已經實作介面。自定義 WebPart 控制項和其他放置在 WebPartZoneBase 區域中的伺服器控制項都可以使用所有 IWebPart 屬性。

無論是在自定義WebPart控件或其他伺服器控件中，自行實IWebPart作介面的主要原因，是如果您想要變更默認實作。例如，您可能想要提供某些屬性的預設值。在使用者或伺服器控制項中實作介面的另一個原因，就是增強在控件上使用這些屬性的設計時間體驗。

屬性

CatalogIconImageUrl	取得或設定至影像的 URL，該影像表示控制項目錄中的 WebPart 控制項。
Description	取得或設定摘要說明控制項功能的簡短片語，用於 WebPart 控制項的工具提示和目錄。
Subtitle	取得與 Title 屬性值串連的字串，組成 WebPart 控制項的完整標題。
Title	取得或設定 WebPart 控制項的標題。
TitleIconImageUrl	取得或設定影像的 URL，用來表示控制項所擁有標題列中的 Web 組件控制項。
TitleUrl	取得或設定至 WebPart 控制項之補充資訊的 URL。

適用於

共用方式為

IWebPart 介面

定義

範例

備註

給實施者的注意事項

屬性

適用於

另請參閱

其他資源