使用者控制項

發行項
08/21/2008

更新：2007 年 11 月

ASP.NET Mobile 使用者控制項 (User Control) 提供快速、有效率的技術，讓您在 ASP.NET Mobile Web 網頁上建立自己的使用者控制項。您可以藉由使用與控制項關聯的邏輯合併一或多個控制項，並將它們封裝到一個使用者控制項中，以便在其他行動網頁內使用任何行動網頁的內容。除了幾點差異，使用者控制項與 MobilePage 控制項完全相同。

行動使用者控制項：

副檔名必須是 .ascx
不需要 @ Page 指示詞。
必須包含 @ Register 指示詞。

@ Register 指示詞使別名 (Alias) 與命名空間 (Namespace) 和類別 (Class) 產生關聯，讓您能在使用者控制項中宣告行動控制項。

ASP.NET 會區別使用者控制項和複合控制項。使用者控制項會以 .ascx 文字檔保存，而複合控制項則會被編譯並保存在組件之中。正如本主題的範例所示，在 ASP.NET Mobile Web 網頁中，一個使用者控制項可以包含多個控制項。

建立使用者控制項

藉由建立副檔名為 .ascx 的檔案，來建立新的使用者控制項。下列程式碼範例包含使用者控制項，這個使用者控制項使用多重標籤顯示汽車的詳細資訊。

<%@ Control Language="VB" ClassName="CarControl" 
    Inherits="System.Web.UI.MobileControls.MobileUserControl" %>
<%@ Register TagPrefix="mobile" 
    Namespace="System.Web.UI.MobileControls" 
    Assembly="System.Web.Mobile" %>

<script >
    ' Private field of externally defined CarInfo type
    Private _car As New CarInfo()

    ' Public Property for the CarInfo
    Public Property Car() As CarInfo
        Get
            Return _car
        End Get
        Set(ByVal value As CarInfo)
            _car = value
        End Set
    End Property
</script>

<mobile:Panel ID="Panel1" Runat="server" BreakAfter="true">
    <mobile:Label id="Label1"  BreakAfter="true">
        Make: <%# Car.Make %></mobile:Label>
    <mobile:Label id="Label2"  BreakAfter="true">
        Model: <%# Car.Model %></mobile:Label>
    <mobile:Label id="Label3"  BreakAfter="true">
        Year: <%# Car.Year %></mobile:Label>
    <mobile:Label id="Label4"  BreakAfter="true">
        Color: <%# Car.Color %></mobile:Label>
</mobile:Panel>

<%@ Control Language="C#" ClassName="CarControl" 
    Inherits="System.Web.UI.MobileControls.MobileUserControl" %>
<%@ Register TagPrefix="mobile" 
    Namespace="System.Web.UI.MobileControls" 
    Assembly="System.Web.Mobile" %>

<script >
    // Private field of externally defined CarInfo type
    private CarInfo _car = new CarInfo();

    // Public Property for the CarInfo
    public CarInfo Car
    {
        get { return _car; }
        set { _car = value; }
    }
</script>

<mobile:Panel ID="Panel1" Runat="server" BreakAfter="true">
    <mobile:Label id="Label1"  BreakAfter="true">
        Make: <%# Car.Make %></mobile:Label>
    <mobile:Label id="Label2"  BreakAfter="true">
        Model: <%# Car.Model %></mobile:Label>
    <mobile:Label id="Label3"  BreakAfter="true">
        Year: <%# Car.Year %></mobile:Label>
    <mobile:Label id="Label4"  BreakAfter="true">
        Color: <%# Car.Color %></mobile:Label>
</mobile:Panel>

部署使用者控制項

在建立行動使用者控制項之後，您可以用下列方式將其加入至 ASP.NET Mobile Web 網頁：

在網頁上註冊該控制項，然後在標記中進行宣告。
以程式設計方式將控制項載入網頁。

若要註冊使用者控制項，請使用 @ Register 指示詞。若要以程式設計方式載入此控制項，請使用 LoadControl 方法。

下列範例程式碼示範如何在網頁中註冊和以宣告方式使用自訂控制項，以及如何以程式設計方式載入使用者控制項。

<%@ Page Language="VB" 
    Inherits="System.Web.UI.MobileControls.MobilePage" %>
<%@ Register TagPrefix="mobile" 
    Namespace="System.Web.UI.MobileControls" 
    Assembly="System.Web.Mobile" %>
<%@ Register TagPrefix="carp" TagName="CarControl" 
    Src="~/CarControl.ascx" %>

<script >
    Protected Sub Page_Load( _
        ByVal sender As Object, ByVal e As EventArgs)
        ' Set the existing car control's data
        CarCtl.Car = New CarInfo("TreeCars", "Rooter", _
            2003, "Tan")

        ' Load a new car control and set the data
        Dim ccar As CarControl = _
            CType(Page.LoadControl("~/CarControl.ascx"), _
            CarControl)
        ccar.ID = "newCarCtl"
        ' Set the new car control's data
        ccar.Car = New CarInfo("TreeCars", "Climber", _
            2001, "Green")
        ' Add the new car control to form2.Controls
        form2.Controls.Add(ccar)

        ' Bind the data and the controls
        DataBind()
    End Sub
</script>

<html xmlns="http://www.w3.org/1999/xhtml" >
<body>
    <mobile:form id="form1" >
        <carp:CarControl ID="CarCtl"  /><br />
        <mobile:Link ID="Link1" Runat="server"
            href="#form2" Text="Next" />
    </mobile:form>
    <mobile:form ID="form2" Runat="server">
        <mobile:Link  id="Link2" 
            BreakAfter="true" 
            Text="Return" href="#form1" />
        <br />
    </mobile:form>
</body>
</html>

<%@ Page Language="C#" 
    Inherits="System.Web.UI.MobileControls.MobilePage" %>
<%@ Register TagPrefix="mobile" 
    Namespace="System.Web.UI.MobileControls" 
    Assembly="System.Web.Mobile" %>
<%@ Register TagPrefix="carp" TagName="CarControl" 
    Src="CarControl.ascx" %>

<script >
    protected void Page_Load(
        object sender, EventArgs e)
    {
        // Set the existing car control's data
        CarCtl.Car = new CarInfo("TreeCars", "Rooter", 
            2003, "Tan");

        // Load a new car control and set the data
        CarControl ccar = 
            (CarControl)Page.LoadControl("~/CarControl.ascx");
        ccar.ID = "newCarCtl";
        // Set the new car control's data
        ccar.Car = new CarInfo("TreeCars", "Climber", 
            2001, "Green");
        // Add the new car control to form2.Controls
        form2.Controls.Add(ccar);

        // Bind the data and the controls
        DataBind();
    }

    // Toggles the visible form
    protected void Command_Click(
        object sender, EventArgs e)
    {
        if (this.ActiveForm == form1)
            this.ActiveForm = form2;
        else
            this.ActiveForm = form1;
    }
</script>

<html xmlns="http://www.w3.org/1999/xhtml" >
<body>
    <mobile:form id="form1" >
        <carp:CarControl ID="CarCtl"  /><br />
        <mobile:Command ID="Command1" Runat="server" 
            OnClick="Command_Click">Next</mobile:Command>
    </mobile:form>
    <mobile:form ID="form2" Runat="server">
        <mobile:Command ID="Command2" Runat="server" 
            OnClick="Command_Click">Return</mobile:Command>
        <br />
    </mobile:form>
</body>
</html>

解析 URL

當您建立會存取位於不同目錄之使用者控制項的網頁，該使用者控制項中的所有相對 URL 都會相對解析為該使用者控制項目錄，而非相對解析為該網頁的目錄。下列說明一般的案例：

網頁位址是 /Default.aspx。
網頁包含使用者控制項 subfolder/UserControl.ascx。
使用者控制項則又包含使用者控制項 B.ascx。

在此案例中，B.ascx 會解析為 subfolder/B.ascx。以這種方式解析 URL 可讓使用者控制項封裝任何連結，或是其可能需要的其他相對資源。

下列是相對於使用者控制項的 URL 解析：

任何的巡覽 URL，例如，Link 控制項的 URL。
Image 控制項上的影像 URL。
Form 控制項的動作 URL。

在撰寫控制項或控制項配置器時，必須確認已解析需要被解析的相對 URL。在您的控制項和配接器中，呼叫行動控制項的 ResolveUrl 方法，以解析相對於包含網頁或使用者控制項之目錄的 URL。在此配接器基底類別 (Base Class) 中的一些 Helper 方法，可自動呼叫 ResolveUrl 方法以解析超連結 (Hyperlink)。

其中一個例外，就是當您將 DeviceSpecific 控制項包含到自訂使用者控制項，而且該使用者控制項參考 Web.config 檔 <deviceFilters> 區段所列出的裝置篩選條件時。在此情況下，控制項會使用網頁所在目錄中的 Web.config 檔，而非位於控制項之子目錄中的 Web.config 檔。

使用者控制項和表單參考中的格式化和連結

您可以連結到相同網頁上的表單，方法是使用以數字符號 (#) 開頭且隨後接上該表單 ID 的 URL。下列程式碼範例會使用 Link 控制項的 href 屬性來指定 URL。

<mobile:Link ID="Link1" Runat="server"
    href="#form2" Text="Next" />

在一般的案例中，您擁有已插入到最上層網頁的使用者控制項。網頁和使用者控制項能夠包含一或多個表單。在網頁或每個使用者控制項上的控制項，都可以按照以下規則參考彼此所包含的表單：

當網頁上的控制項參考子使用者控制項中的表單時，URL 就必須包含表單的完整唯一 ID。其格式為 ucid:formid，其中的 ucid 是使用者控制項的 ID，formid 則是表單的 ID。
當使用者控制項中的控制項參考表單時，ASP.NET 會先在使用者控制項中搜尋表單，然後在它的父代 (Parent) 搜尋，一直向上搜尋直到網頁層次。

例如，假設網頁包含 ID 為 FormA 和 FormB 的兩個表單。該網頁也包含最上層的使用者控制項，其 ID 為 UserControl1。這個使用者控制項包含 ID 為 FormA 和 FormC 的兩個額外表單。下表舉出這個案例之可能 URL 及其行為的範例。

控制項的位置	表單的 URL	行為
在網頁上	#FormA	連結到網頁本身的 FormA。
在網頁上	#FormC	擲回例外狀況 (Exception)，因為網頁沒有包含具備指定之 ID 的任何表單 (只有使用者控制項具有這種表單)。
在網頁上	#UserControl1:FormA	連結到使用者控制項中的 FormA。
在使用者控制項中	#FormA	連結到使用者控制項中的 FormA，因為 ASP.NET 會先在使用者控制項本身中搜尋。
在使用者控制項中	#FormB	連結到網頁上的 FormB，因為 ASP.NET 會解析相對於使用者控制項之父代的表單參考。

建立行動使用者控制項的特殊考量

在開發行動應用程式的使用者控制項時，必須考慮下列問題。

使用預先定義的樣式

如需獲得使用者控制項中的完整功能樣式支援，當您在建立行動使用者控制項時，您必須從 .ascx 檔中的 MobileUserControl 類別衍生這些控制項，而不是從標準 UserControl 類別衍生這些控制項。下列程式碼範例會示範這點。

<%@ Control Language="C#"
    Inherits="System.Web.UI.MobileControls.MobileUserControl" 
    %>
<%@ Register TagPrefix="mobile" 
    Namespace="System.Web.UI.MobileControls" 
    Assembly="System.Web.Mobile" %>

Web.config 檔的位置會影響它的使用

ASP.NET 會使用目前執行中網頁的目錄來尋找該網頁中控制項的組態資訊。因此，如果您已在 Web.config 檔中定義了裝置特定篩選條件，該 Web.config 檔就必須位於 ASP.NET Web 應用程式之 Mobile Web 網頁區段的根目錄中。例如，如果您有名為 /Reports/Report1.aspx 的網頁，其中包含名為 /Sales/Inventory.ascx 的使用者控制項，而且您也有包含裝置篩選條件的 /Sales/Web.config 檔，/Sales/Inventory.ascx 控制項便會在 /Reports/Web.config 檔中尋找裝置篩選條件定義，而不是在 /Sales/Web.config 檔中尋找。

處理使用者控制項中的常值文字

使用者控制項中的文字剖析為 LiteralControl，而非剖析為 LiteralText 控制項。當使用者控制項包含常值 (Literal) 文字，以及當使用者控制項包含具備內部重新編頁功能的控制項，例如 Form，該文字便會出現在所有的頁面上。若要避免發生這個問題，請將使用者控制項的內容置於 Panel 控制項中，這樣一來，這段文字便會由 ASP.NET 網頁架構進行剖析，並將其視為 LiteralText 控制項處理。

共用方式為