IWebPart 接口

定义

定义由 ASP.NET WebPart 控件使用的公共用户界面 (UI) 属性。Defines common user interface (UI) properties used by ASP.NET WebPart controls.

public interface class IWebPart
public interface IWebPart
type IWebPart = interface
Public Interface IWebPart
派生

示例

下面的代码示例演示如何在用户控件中实现 IWebPart 接口。The following code example demonstrates how to implement the IWebPart interface in a user control. 这是一个简单的实现,演示如何实现属性。This is a simple implementation that shows minimally how to implement the properties.

此代码示例的第一部分演示用户控件。The first part of the code example shows the user control. 用户控件实现 IWebPart 接口的所有属性,以及与用户界面中的控件绑定的其他两个公共属性。The user control implements all the properties of the IWebPart interface, plus two additional public properties tied to controls in the user interface. 这两个自定义属性每个都使用 Personalizable 属性,这将使这些属性中的值能够跨浏览器会话保存。The two custom properties each use the Personalizable attribute, which enables the values in those properties to be saved across browser sessions. 请注意,在基本 WebPart 类实现中,IWebPart 接口的所有属性也实现为可个性化的,尽管它们不在此代码示例中。Note that in the base WebPart class implementation, all the properties of the IWebPart interface are implemented as personalizable as well, though they are not in this code example.

<%@ 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>

此代码示例的第二部分显示了承载用户控件的网页。The second part of the code example shows the Web page that hosts the user control. 页面具有 WebPartZone 的控件,在该控件中引用用户控件。The page has a WebPartZone control, within which the user control is referenced. 请注意,会在用户控件的标记中以声明方式设置几个 IWebPart 接口的属性值,这样,在设计时和运行时,这两个接口的属性值与 WebPart 控件的行为和外观类似。Notice that several of the IWebPart interface's property values are set declaratively in the markup for the user control, which enables it to both behave and appear similar to a WebPart control at design time and run time. 如果在浏览器中加载页面,则可以使用页面上的 UI 来演示在运行时以编程方式更改已实现 IWebPart 属性的值的功能。If you load the page in a browser, you can use the UI on the page to demonstrate the ability to programmatically change the values of the implemented IWebPart properties at run time. 更改某些属性值时,所做的更改在页面上并不明显,但在页面源(TitleIconImageUrl 属性)中可见,或存储在应用程序的状态数据(CatalogIconImageUrl 属性)中。When you change some of the property values, the changes are not evident on the page, but are visible in the page source (the TitleIconImageUrl property), or are stored in the application's state data (the CatalogIconImageUrl property).

重要

此示例具有一个接受用户输入的文本框,这是一个潜在的安全威胁。This example has a text box that accepts user input, which is a potential security threat. 默认情况下,ASP.NET 网页验证用户输入是否不包含脚本或 HTML 元素。By default, ASP.NET Web pages validate that user input does not include script or HTML elements. 有关详细信息,请参阅脚本侵入概述For more information, see 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 控件的用户体验。The IWebPart interface provides several UI-oriented properties that enhance the user experience of working with WebPart controls. 当你创建从基本 WebPart 类派生的控件时,你将获得 IWebPart 接口中的所有属性的实现,因为 WebPart 基类实现了此接口。When you create controls that derive from the base WebPart class, you get an implementation of all the properties in the IWebPart interface, because the WebPart base class implements this interface.

您可以使用现有用户控件、ASP.NET 控件或自定义服务器控件,这些控件不从 WebPart 类继承为 Web 部件应用程序的一部分,并且它们还可以使用 IWebPart 接口声明的这些面向 UI 的属性。You can use existing user controls, ASP.NET controls, or custom server controls that do not inherit from the WebPart class as part of a Web Parts application, and they can also use these UI-oriented properties declared by the IWebPart interface. 如果将现有服务器控件放在 WebPartZoneBase 区域中,则会在运行时使用 GenericWebPart 对象对它们进行包装。If you place existing server controls in a WebPartZoneBase zone, at run time they are wrapped with a GenericWebPart object. 由于 GenericWebPart 类继承自 WebPart 基类,因此它允许现有服务器控件充当 true WebPart 控件,并向其添加 IWebPart 接口的属性。Because the GenericWebPart class inherits from the WebPart base class, it enables existing server controls to act as true WebPart controls and it adds to them the properties of the IWebPart interface.

如果将不 WebPart 控件的服务器控件放置在区域中,则它们可以在运行时使用 IWebPart 属性,还可以在页的标记中的服务器控件上声明这些属性的值(采用页持久性格式)。If you place server controls that are not WebPart controls in zones, they can use the IWebPart properties at run time, and you can also declare values for those properties on server controls in the markup of the page (in page persistence format). 但是,因为这些属性仅在运行时可用于服务器控件,所以 IntelliSense 的设计时编码功能不识别在服务器控件上声明 IWebPart 属性。However, because these properties are only available to the server controls at run time, design-time coding features such as IntelliSense do not recognize IWebPart properties that are declared on server controls. 在加载页面时,这些控件上的声明属性仍然有效,但 Microsoft Visual Studio 不会在设计时将属性识别为有效。Declared properties on these controls still work when you load the page, but Microsoft Visual Studio does not recognize the properties as valid at design time. 如果要将 IWebPart 属性添加到现有服务器和用户控件以提高设计时用户体验,可以在服务器控件中实现 IWebPart 接口。If you want to add the IWebPart properties to existing server and user controls to enhance the design-time user experience, you can implement the IWebPart interface in a server control.

可能是实现 IWebPart 接口的主要原因是对于不支持使用 expando (自定义)属性的控件。Perhaps the main reason to implement the IWebPart interface is for controls that do not support the use of expando (custom) properties. Expando 属性是可通过 IAttributeAccessor 接口动态添加到类的字符串。Expando properties are strings that can be added to a class dynamically as a property, by means of the IAttributeAccessor interface. 实现此接口的控件(包括 WebControl 类及其子级)可以使用 expando 属性。Controls that implement this interface, including the WebControl class and its children, can use expando properties. 因此,所有 ASP.NET 服务器控件、从它们派生的自定义控件、Web 用户控件和 WebPart 控件都支持使用 expando 属性。Therefore, all ASP.NET server controls, custom controls that derive from them, Web user controls, and WebPart controls support the use of expando properties. 但直接从基本 Control 类继承的自定义控件不支持 expando 属性。But custom controls that inherit directly from the base Control class do not support expando properties. 因此,如果在 WebPartZone中声明这些控件,将无法在控件上声明常见 IWebPart 属性,如 TitleDescriptionThus, if you declare these controls within a WebPartZone, you will not be able to declare the common IWebPart properties on the controls, properties such as Title and Description. 如果要将这些属性用于此类控件,则必须实现 IWebPart 接口。If you want to use these properties with such controls, you must implement the IWebPart interface.

实施者说明

通常不需要在自定义 WebPart 控件或服务器控件上实现 IWebPart 接口,因为基 WebPart 类已经实现了接口。Normally you do not need to implement the IWebPart interface, either on custom WebPart controls or server controls, because the base WebPart class already implements the interface. 位于 WebPartZoneBase 区域中的自定义 WebPart 控件和其他服务器控件可以使用所有 IWebPart 属性。Custom WebPart controls, and other server controls that are placed in WebPartZoneBase zones, can use all the IWebPart properties.

自行实现 IWebPart 接口的主要原因是如果你要更改默认实现,无论是在自定义 WebPart 控件中还是在其他服务器控件中。The main reason to implement the IWebPart interface yourself, whether in a custom WebPart control or another server control, is if you want to change the default implementation. 例如,您可能希望为某些属性提供默认值。For example, you might want to provide default values for some of the properties. 在用户或服务器控件中实现该接口的另一个原因是,这样就可以增强在控件上使用这些属性的设计时体验。Another reason to implement the interface in a user or server control is so that the design-time experience of working with these properties on the control will be enhanced.

属性

CatalogIconImageUrl

获取或设置图像的 URL,该图像在控件目录中表示一个 WebPart 控件。Gets or sets the URL to an image that represents a WebPart control in a catalog of controls.

Description

获取或设置一条短语,该短语在 WebPart 控件的工具提示和目录中用来概述该控件的作用。Gets or sets a brief phrase that summarizes what a control does, for use in ToolTips and catalogs of WebPart controls.

Subtitle

获取一个字符串,该字符串与 Title 属性值连接即形成 WebPart 控件的完整标题。Gets a string that is concatenated with the Title property value to form a complete title for a WebPart control.

Title

获取或设置 WebPart 控件的标题。Gets or sets the title of a WebPart control.

TitleIconImageUrl

获取或设置图像的 URL,该图像用于在控件自身的标题栏中表示 Web 部件控件。Gets or sets the URL to an image used to represent a Web Parts control in the control's own title bar.

TitleUrl

获取或设置有关 WebPart 控件补充信息的 URL。Gets or sets a URL to supplemental information about a WebPart control.

适用于

另请参阅