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 屬性，例如 Title 和 Description 等屬性。如果您想要將這些屬性與這類控制項搭配使用，則必須實作 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 介面

定義

範例

備註

給實施者的注意事項

屬性

適用於

另請參閱

意見反應

其他資源