Web 控件呈现示例

项目
10/22/2014

更新：2007 年 11 月

此示例演示如何创建一个名为 MailLink 的控件，该控件通过呈现包含 mailto: URI 的超链接 (<a>) 元素，在网页中创建了一个电子邮件链接。该控件演示在呈现从 WebControl 类派生的控件时通常执行的任务。

MailLink 控件公开与电子邮件地址对应的 Email 属性，以及与超链接上显示的文本对应的 Text 属性。页开发人员可以按照突出显示的文本所显示的内容设置这些属性：

<aspSample:MailLink id="maillink1" Email="someone@example.com" 
    runat="server">
  Mail Webmaster
</aspSample:MailLink>

如果在客户端上查看控件呈现的标记，该标记将显示如下：

<a id="maillink1" href="mailto:someone@example.com">
  Mail Webmaster
</a>

在不同的浏览器中，mailto: URI 的行为可能不同。在 Internet Explorer 中，当用户单击 mailto: 超链接时，浏览器将启动用户的默认电子邮件客户端（如果该电子邮件客户端已安装并且与浏览器兼容）。MailLink 控件的代码在本主题后面的“代码讨论”部分中有描述。

MailLink 控件的代码清单

' MailLink.vb
Option Strict On
Imports System
Imports System.ComponentModel
Imports System.Security
Imports System.Security.Permissions
Imports System.Web
Imports System.Web.UI
Imports System.Web.UI.WebControls

Namespace Samples.AspNet.VB.Controls
    < _
    AspNetHostingPermission(SecurityAction.Demand, _
        Level:=AspNetHostingPermissionLevel.Minimal), _
    AspNetHostingPermission(SecurityAction.InheritanceDemand, _
        Level:=AspNetHostingPermissionLevel.Minimal), _
    DefaultProperty("Email"), _
    ParseChildren(True, "Text"), _
    ToolboxData("<{0}:MailLink runat=""server""> </{0}:MailLink>") _
    > _
    Public Class MailLink
        Inherits WebControl
        < _
        Bindable(True), _
        Category("Appearance"), _
        DefaultValue(""), _
        Description("The e-mail address.") _
        > _
        Public Overridable Property Email() As String
            Get
                Dim s As String = CStr(ViewState("Email"))
                If s Is Nothing Then s = String.Empty
                Return s
            End Get
            Set(ByVal value As String)
                ViewState("Email") = value
            End Set
        End Property

        < _
        Bindable(True), _
        Category("Appearance"), _
        DefaultValue(""), _
        Description("The text to display on the link."), _
        Localizable(True), _
        PersistenceMode(PersistenceMode.InnerDefaultProperty) _
        > _
        Public Overridable Property Text() As String
            Get
                Dim s As String = CStr(ViewState("Text"))
                If s Is Nothing Then s = String.Empty
                Return s
            End Get
            Set(ByVal value As String)
                ViewState("Text") = value
            End Set
        End Property

        Protected Overrides ReadOnly Property TagKey() _
            As HtmlTextWriterTag
            Get
                Return HtmlTextWriterTag.A
            End Get
        End Property


        Protected Overrides Sub AddAttributesToRender( _
            ByVal writer As HtmlTextWriter)
            MyBase.AddAttributesToRender(writer)
            writer.AddAttribute(HtmlTextWriterAttribute.Href, _
                "mailto:" & Email)
        End Sub

        Protected Overrides Sub RenderContents( _
            ByVal writer As HtmlTextWriter)
            If (Text = String.Empty) Then
                Text = Email
            End If
            writer.WriteEncodedText(Text)
        End Sub

    End Class
End Namespace

// MailLink.cs
using System;
using System.ComponentModel;
using System.Security;
using System.Security.Permissions;
using System.Web;
using System.Web.UI;
using System.Web.UI.WebControls;

namespace Samples.AspNet.CS.Controls
{
    [
    AspNetHostingPermission(SecurityAction.Demand,
        Level = AspNetHostingPermissionLevel.Minimal),
    AspNetHostingPermission(SecurityAction.InheritanceDemand, 
        Level=AspNetHostingPermissionLevel.Minimal),
    DefaultProperty("Email"),
    ParseChildren(true, "Text"),
    ToolboxData("<{0}:MailLink runat=\"server\"> </{0}:MailLink>")
    ]
    public class MailLink : WebControl
    {
        [
        Bindable(true),
        Category("Appearance"),
        DefaultValue(""),
        Description("The e-mail address.")
        ]
        public virtual string Email
        {
            get
            {
                string s = (string)ViewState["Email"];
                return (s == null) ? String.Empty : s;
            }
            set
            {
                ViewState["Email"] = value;
            }
        }

        [
        Bindable(true),
        Category("Appearance"),
        DefaultValue(""),
        Description("The text to display on the link."),
        Localizable(true),
        PersistenceMode(PersistenceMode.InnerDefaultProperty)
        ]
        public virtual string Text
        {
            get
            {
                string s = (string)ViewState["Text"];
                return (s == null) ? String.Empty : s;
            }
            set
            {
                ViewState["Text"] = value;
            }
        }

        protected override HtmlTextWriterTag TagKey
        {
            get
            {
                return HtmlTextWriterTag.A;
            }
        }

        protected override void AddAttributesToRender(
            HtmlTextWriter writer)
        {
            base.AddAttributesToRender(writer);
            writer.AddAttribute(HtmlTextWriterAttribute.Href, 
                "mailto:" + Email);
        }

        protected override void RenderContents(HtmlTextWriter writer)
        {
            if (Text == String.Empty)
            {
                Text = Email;
            }
            writer.WriteEncodedText(Text);
        }
    }
}

代码讨论

MailLink 控件示例阐释以下任务：

呈现控件的非默认元素。
呈现控件开始标记中的属性。
呈现控件标记中的内容。

MailLink 控件重写 TagKey 属性以呈现 <a> 元素，而不会呈现 WebControl 类所呈现的默认 <span> 元素。如果要呈现的元素是 HtmlTextWriterTag 枚举的成员，则应重写 TagKey 属性。许多常见的 HTML 元素标记被映射为 HtmlTextWriterTag 枚举的值。例如，HtmlTextWriterTag.A 与 <a> 元素对应，而 HtmlTextWriterTag.Table 与 <table> 元素对应。如果要呈现的元素不是由 HtmlTextWriterTag 枚举的成员表示，请重写 TagName 属性，并返回要作为元素呈现的字符串。

MailLink 控件重写 WebControl 类的以下呈现方法：

AddAttributesToRender，用于添加由控件呈现的开始标记中的 href 属性。重写 AddAttributesToRender 时，应始终按照 MailLink 控件演示的方式调用对应的基类方法。WebControl 类的 AddAttributesToRender 方法实现相关逻辑，以添加 Web 控件呈现的元素上的样式和其他属性。此类将由 WebControl 的 RenderBeginTag 方法调用。必须在呈现开始标记前添加属性。这意味着对 AddAttributesToRender 或 AddAttribute 的调用在对 RenderBeginTag 的调用之前。
RenderContents，用于在控件的标记中写超链接的文本（由 Text 属性指定）。MailLink 控件将调用 HtmlTextWriter 实例的 WriteEncodedText 方法，以对页开发人员输入的文本进行 HTML 编码。一般情况下，为了安全起见，应该对用户提供的文本进行 HTML 编码。

MailLink 控件还演示内部文本持久性。通过 MailLink，页开发人员可以在控件标记内指定 Text 属性，如突出显示的文本所示：

<aspSample:MailLink id="maillink1" Email="someone@example.com" 
    runat="server">
  Mail Webmaster
</aspSample:MailLink>

内部持久性与控件开始标记中的默认持久性相反，如此示例所示：

<aspSample:MailLink Text="Mail Webmaster" runat="server" />

默认持久性和内部持久性功能相同。若要实现内部持久性，应使用 ParseChildren(true, "Text") 属性标记 MailLink。ParseChildrenAttribute 构造函数的第一个参数指定页分析器应将控件标记内的内容分析为属性，而不是子控件。第二个参数提供控件的内部默认属性名称（在此示例中为 Text）。使用这两个参数调用 ParseChildrenAttribute 构造函数时，控件标记内的内容必须与内部默认属性对应。Text 属性 (Property) 的 PersistenceMode(PersistenceMode.InnerDefaultProperty) 属性 (Attribute) 指定可视化设计器应将此属性 (Property) 作为控件标记中的内部内容进行序列化。

WebControl 使用 PersistChildren(false) 和 ParseChildren(true) 属性 (Attribute) 进行标记，这两个属性 (Attribute) 控制设计时和分析时属性 (Property) 的持久性。这两个属性将被控件继承，且仅在要更改继承的设置时需要应用。PersistChildrenAttribute 告知设计器是否应将服务器控件的子控件作为嵌套的内部控件保存。false 参数指示内部内容与属性对应，而不是与子控件对应。ParseChildrenAttribute 已在上一段中加以说明。如果 WebControl 类的设计时和分析时持久性适用于您的控件，则不必重写从 WebControl 继承的 PersistChildrenAttribute 和 ParseChildrenAttribute 属性。

MailLink 控件的测试页

下面的示例演示一个使用 MailLink 控件的 ASP.NET 网页（.aspx 文件）。

<%@ Page Language="VB" %>
<!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 id="Head1" runat="server">
  <title>MailLink test page</title>
</head>
<body>
  <form id="Form1" runat="server">
    <aspSample:MailLink id="maillink1" Font-Bold="true" 
      ForeColor="Green" Email="someone@example.com" runat="server">
      Mail Webmaster
    </aspSample:MailLink>
  </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">
<html xmlns="http://www.w3.org/1999/xhtml" >
<head id="Head1" runat="server">
  <title>MailLink test page</title>
</head>
<body>
  <form id="Form1" runat="server">
    <aspSample:MailLink id="maillink1" Font-Bold="true" 
      ForeColor="Green" Email="someone@example.com" runat="server">
      Mail Webmaster
    </aspSample:MailLink>
  </form>
</body>
</html>

生成和使用示例

有关生成控件和在页中使用该控件的信息，请参见生成自定义服务器控件示例。

请参见

其他资源

开发自定义 ASP.NET 服务器控件