Web 控制項呈現範例

更新：2007 年 11 月

本範例將示範如何建立名為 MailLink 的控制項，透過呈現內容為 mailto: 統一資源識別元 (URI) 的超連結 (<a>) 項目，在 Web 網頁中建立電子郵件連結。控制項會示範呈現衍生自 WebControl 類別的控制項時，您通常需要執行的工作。

MailLink 控制項會公開 (Expose) 電子郵件地址的 Email 屬性，以及包含要在超連結上顯示文字的 Text 屬性。網頁開發人員可以設定這些屬性，如下以粗體顯示的文字：

<aspSample:MailLink id="maillink1" Email="someone@example.com" 
    >
  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 列舉型別 (Enumeration) 的成員，您應該覆寫 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 控制項也會示範內部文字持續顯示 (Persistence) 的狀態。MailLink 可讓網頁開發人員指定控制項標記內的 Text 屬性，如下以粗體顯示的所示：

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

內部持續性會與控制項開頭標記上的預設持續性形成對比，如本範例所示：

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

預設持續性和內部持續性的運作方式相同。若要啟用內部持續性，將以 ParseChildren(true, "Text") 屬性標記 MailLink。ParseChildrenAttribute 建構函式的第一個引數會指定，網頁剖析器 (Parser) 應該剖析控制項標記內的內容做為屬性，而非做為子控制項。第二個引數則提供控制項的內部預設屬性名稱 (在這個範例中是 Text)。以這兩個參數呼叫 ParseChildrenAttribute 建構函式時，控制項標記內的內容必須對應至內部預設屬性。Text 屬性 (Property) 上的 PersistenceMode(PersistenceMode.InnerDefaultProperty) 屬性 (Attribute) 指定視覺化設計工具應該序列化此屬性 (Property)，以做為控制項標記中的內部內容。

WebControl 會以 PersistChildren(false) 和 ParseChildren(true) 屬性 (Attribute) 標記，這兩個屬性會管理設計階段和剖析階段屬性 (Property) 的持續性。這些屬性是從控制項繼承而來，並只有在您要變更繼承的設定時套用。PersistChildrenAttribute 會告知設計人員，伺服器控制項的子控制項是否應該持續做為巢狀內部控制項。引數 false 表示內部內容對應至屬性，而不是對應至子控制項。ParseChildrenAttribute 已在之前的段落中描述。如果 WebControl 類別的設計階段和剖析階段持續性適用於您的控制項，則不需要覆寫繼承自 WebControl 的 PersistChildrenAttribute 和 ParseChildrenAttribute 屬性。

MailLink 控制項的測試網頁

下列範例顯示的是使用 MailLink 控制項的 ASP.NET Web 網頁 (.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" >
  <title>MailLink test page</title>
</head>
<body>
  <form id="Form1" >
    <aspSample:MailLink id="maillink1" Font-Bold="true" 
      ForeColor="Green" Email="someone@example.com" >
      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" >
  <title>MailLink test page</title>
</head>
<body>
  <form id="Form1" >
    <aspSample:MailLink id="maillink1" Font-Bold="true" 
      ForeColor="Green" Email="someone@example.com" >
      Mail Webmaster
    </aspSample:MailLink>
  </form>
</body>
</html>

建置及使用範例

如需建置控制項以及在網頁中使用此控制項的詳細資訊，請參閱建置自訂伺服器控制項範例。

請參閱

其他資源

開發自訂的 ASP.NET 伺服器控制項

Last updated on 2014-10-22

共用方式為

Web 控制項呈現範例

MailLink 控制項的程式碼清單

程式碼討論

MailLink 控制項的測試網頁

建置及使用範例

請參閱

其他資源

其他資源