逐步解說：建立堆疊面板控制項擴充功能

發行項
06/10/2015

以下將逐步解說並示範如何建立 LightSwitch 的堆疊面板控制項擴充功能。使用堆疊面板，您可以在指定方向堆疊項目。一些在 LightSwitch 螢幕設計工具中堆疊面板控制項的範例，例如， 垂直配置 和 水平配置群組控制項中。

必要條件

Visual Studio 2013 Professional
Visual Studio 2013 SDK
Visual Studio 2013 的 LightSwitch 擴充性工具組

建立控制項擴充功能的專案

第一步就是建立專案並加入 LightSwitch Control範本。

建立擴充功能專案

在 Visual Studio的功能表列，選擇 [ 檔案]，新增，專案。
在 新的專案對話方塊中，展開 Visual Basic]或 **Visual C#**節點，然後展開 LightSwitch節點，選取 擴充性節點，然後選取 LightSwitch 擴充程式庫範本。
在名稱欄位中，輸入 MyStackPanelExtension 做為擴充功能程式庫的名字。這個名稱會出現在 LightSwitch 應用程式設計工具 的 擴充功能索引標籤。
選擇好按鈕以建立方案，其包含七個擴充功能所需的專案。

選取擴充功能類型

在 方案總管中，選取 MyStackPanelExtension.Lspkg 檔案。
在功能表列中，選擇 [專案]、[加入新項目]。
在加入新項目對話方塊中選擇 LightSwitch 控制項。
在名稱欄位中，輸入 MyStackPanel 做為擴充功能的名字。這個名稱會出現在 LightSwitch 螢幕設計工具上。
選擇 [確定] 按鈕。檔案會加入至您方案中的數個專案。

更新控制項圖示。

這兩個名為MyStackPanel.png的影像檔案已加入至您的方案：一個在 MyStackPanelExtension.Client.Design專案的ControlImages資料夾，其他在 MyStackPanelExtension.Design專案的ControlImages資料夾。檔案中的影像會顯示為圖示。您可以使用其他影像取代預設的控制項影像。

修改圖示影像

在 方案總管中，於 MyStackPanel.png 檔案的捷徑功能表中 MyStackPanelExtension.Client.Design 專案的 ControlImages 資料夾，請選取 開啟檔案。
在開啟檔案對話方塊中，選取繪製，然後選擇好按鈕。
在繪製中變更影像；舉例來說，在變更色彩或添加圖形後，儲存檔案並傳回 Visual Studio。
選取MyStackPanel.png檔案，然後在功能表列上，選擇編輯後，按下複製。
選取 MyStackPanelExtension.Design專案的 ControlImages 資料夾，然後在功能表列上，選擇編輯後，按下貼上。在詢問您是否要取代檔案的訊息中，請選擇是按鈕。

更新在 LightSwitch 中繼資料檔的控制項定義。

定義控制項的中繼資料包含在 MyStackPanelExtension.Common]專案的 .lsml 檔案中。針對智慧配置控制項，您可以為您的控制項自訂適合的值，例如控制項型別和顯示名稱。您也可以加入子項目的預留位置和定義 AttachedLabelPosition 設定的行為。

更新控制項的中繼資料。

在 方案總管中，於 MyStackPanelExtension.Common 專案的 Controls資料夾中，開啟 MyStackPanel.lsml檔案的捷徑功能表，並選擇 開啟檔案。
在開啟檔案 對話方塊中，選取 XML (文字) 編輯器，然後選擇好按鈕。
將 SupportedContentItemKind 項目變更為 SupportedContentItemKind="Group"。

這會告訴 LightSwitch 此為群組控制項。
將 SupportedContentItemKind 項目插入在 AttachedLabelSupport="DisplayedByControl" 項目之後。

這會告訴 LightSwitch 群組控制項處理所有子控制項的 AttachedLabelPosition 屬性。
變更 DisplayName 項目如下: <DisplayName Value="$(MyStackPanel_DisplayName)" />。

$(ResourceName) 標記法告訴 LightSwitch 從資源檔擷取值。

在 Control.Attributes 區塊後面貼上下列程式碼：

<!-- Override AttachedLabelPosition so it can be shown on the property sheet. -->
    <Control.PropertyOverrides>
      <ControlPropertyOverride
          Property=":RootControl/Properties[AttachedLabelPosition]"
          EditorVisibility="PropertySheet">
              </ControlPropertyOverride>
    </Control.PropertyOverrides>

這會告訴 LightSwitch 顯示在屬性工作表的 AttachedLabelPosition 屬性，以便讓開發人員為子控制項指定預設值。

刪除 Control.SupportedDataTypes 區塊。因為群組控制項無法直接顯示資料，此區塊是必要的。

MyStackPanel.lsml file 檔案的完整程式碼現在應該會與下列範例類似。

 <ModelFragment
  xmlns="https://schemas.microsoft.com/LightSwitch/2010/xaml/model"
  xmlns:x="https://schemas.microsoft.com/winfx/2006/xaml">

  <Control Name="MyStackPanel"
    SupportedContentItemKind="Group"
    AttachedLabelSupport="DisplayedByControl"
    DesignerImageResource="MyStackPanelExtension.MyStackPanel::ControlImage">
    <Control.Attributes>
      <DisplayName Value="$(MyStackPanel_DisplayName)" />
    </Control.Attributes>

    <!-- Override AttachedLabelPosition so it can be shown on the property sheet. -->
    Add the following xaml code
      <ControlPropertyOverride
          Property=":RootControl/Properties[AttachedLabelPosition]"
          EditorVisibility="PropertySheet">
      </ControlPropertyOverride>
    </Control.PropertyOverrides>

  </Control>

</ModelFragment>

加入字串資源

MyStackPanelExtension.Common專案的 ModuleResources.resx 檔案包含控制項所使用的資源。您可以將您在MyStackPanel.lsml檔案指定顯示名稱的字串資源。

若要加入字串資源

在方案總管中，展開 MyStackPanelExtension.Common專案的資源節點，然後開啟 ModuleResources.resx 檔案。
將下列的值加入到 ModuleResources.resx 檔案中。

名稱

值

註解

MyStackPanel_DisplayName

我的堆疊面板控制項

顯示名稱的控制項;要顯示在螢幕設計工具。

名稱	值	註解
MyStackPanel_DisplayName	我的堆疊面板控制項	顯示名稱的控制項;要顯示在螢幕設計工具。

更新控制項的 XAML 檔案。

MyStackPanelExtension.Client專案的 MyStackPanel.xaml 檔案包含定義 Silverlight 控制項的標記語言。預設控制項為 TextBox；將它變更為可顯示子控制項的容器。

更新 XAML

在 方案總管中，開啟 MyStackPanelExtension.Client專案的 MyStackPanel.xaml 檔案。

以下列 XAML 程式碼取代這個檔案的內容。

<UserControl x:Class="MyStackPanelExtension.Presentation.Controls.MyStackPanel"
             xmlns="https://schemas.microsoft.com/winfx/2006/xaml/presentation"
             xmlns:framework ="clr-namespace:Microsoft.LightSwitch.Presentation.Framework;assembly=Microsoft.LightSwitch.Client"
             xmlns:x="https://schemas.microsoft.com/winfx/2006/xaml">

    <!-- An ItemsControl is used here to create ContentItemPresenter for all child items in the LightSwitch content tree. -->
    <ItemsControl ItemsSource="{Binding ChildItems}" >

        <!-- ItemsPanel enables the use of a stack panel to arrange all child items. Different group controls typically use different layout panels here. -->
        <ItemsControl.ItemsPanel>
            <ItemsPanelTemplate>
                <StackPanel Orientation="Vertical" />
            </ItemsPanelTemplate>
        </ItemsControl.ItemsPanel>

        <!--
           ItemTemplate enables the mapping of a content item to a Silverlight control. Use a ContentItemPresenter here; 
           bind its ContentItem to the ContentItem in the LightSwitch screen content tree.  -->
        <ItemsControl.ItemTemplate>
            <DataTemplate>
                <framework:ContentItemPresenter ContentItem="{Binding}" />
            </DataTemplate>
        </ItemsControl.ItemTemplate>
    </ItemsControl>
</UserControl>

An ItemsControl is used to map child items of the group node to Silverlight controls, and host them in a stack panel.LightSwitch 控制項的 DataContext 都是 IContentItem 物件，則為 ContentItemPresenter ，並用來顯示 ContentItem 做為 Silverlight 控制項。

在螢幕內容樹狀結構中定義子項目的框線屬性

此時，您可以測試控制項，不過，外觀可能並非您所預期。您加入至控制項的子控制項就會出現，不需要間隔這兩者。您可以藉由定義 Margin 屬性修正這個問題。

使用 Margin 屬性，開發人員可以指定間距均等控制項之間的錯誤訊息。您可以定義一定數目的空間，不過，公開屬性讓開發人員更多的彈性。

定義邊界屬性

在 方案總管中，開啟 MyStackPanelExtension.Common專案的控制項 資料夾的 MyStackPanel.lsml檔案。

將下列xaml程式碼加入 Control.PropertyOverrides 區塊之後。

<!-- Define New Control Properties -->
    <Control.Properties>

      <!-- 
        Define a Margin property for all immediate children of the stack panel.
        It must be an attachable property, just like a Grid in Silverlight adds the Grid.Row property to its children.
      -->
      <ControlProperty Name="Margin"
                       PropertyType=":Double"
                       IsAttachable="True"
                       AttachedPropertyAvailability="ImmediateChildren"
                       EditorVisibility="PropertySheet"
                       >
        <ControlProperty.Attributes>
          <!--  Reference to the localized name in ModuleResources.resx -->
          <DisplayName Value="$(Margin_DisplayName)" />

          <!--  Reference to the localized description string in ModuleResources.resx -->
          <Description Value="$(Margin_Description)" />
        </ControlProperty.Attributes>

        <!-- Define the default value of Margin to 0. -->
        <ControlProperty.DefaultValueSource>
          <ScreenExpressionTree>
            <ConstantExpression ResultType=":Double" Value="0"/>
          </ScreenExpressionTree>
        </ControlProperty.DefaultValueSource>
      </ControlProperty>
    </Control.Properties>

在 MyStackPanelExtension.Common 中展開資源節點，然後開啟 ModuleResources.resx檔案。
將下列的值加入到 ModuleResources.resx 檔案中。

名稱

值

描述

Margin_DisplayName

Margin

屬性名稱

Margin_Description

子系控制項之間的間距。

用於螢幕設計工具的屬性描述。

名稱	值	描述
Margin_DisplayName	Margin	屬性名稱
Margin_Description	子系控制項之間的間距。	用於螢幕設計工具的屬性描述。

建立值轉換器將控制項的屬性值加入至 Silverlight 值

Silverlight 控制使用 Thickness 型別表示邊框。因此，您必須建立轉換子轉換 Double 屬性值為 Margin 的 Thickness 型別。

建立值轉換器

在 方案總管中，選取 MyStackPanelExtension.Client 專案的 Controls 節點。
在功能表列上，選擇專案、新增類別。
在 **加入新項目。**對話方塊中，將類別命名為 DoubleToThicknessConverter，然後選擇加入按鈕。

將下列程式碼加入至類別模組：

Imports System.Windows
Imports System.Windows.Data
Namespace MyStackPanelExtension.Presentation.Controls

' A value converter to convert a Double value defined in the control property to a Thickness value used in the Silverlight control.
Public Class DoubleToThicknessConverter
Implements IValueConverter

Public Function Convert(value As Object, targetType As Type, parameter As Object, culture As System.Globalization.CultureInfo) As Object Implements IValueConverter.Convert
Return New Thickness(CDbl(value))
End Function

Public Function ConvertBack(value As Object, targetType As Type, parameter As Object, culture As System.Globalization.CultureInfo) As Object Implements IValueConverter.ConvertBack
Throw New NotSupportedException()
End Function
End Class
End Namespace

using System;
using System.Windows;
using System.Windows.Data;


namespace MyStackPanelExtension.Presentation.Controls
{
    /// <summary>
    /// A value converter to convert double value defined in the control property to a Thickness value used in the Silverlight control.
    /// </summary>
    public class DoubleToThicknessConverter
        : IValueConverter
    {

        public object Convert(object value, Type targetType, object parameter, System.Globalization.CultureInfo culture)
        {
            return new Thickness((double)value);
        }

        public object ConvertBack(object value, Type targetType, object parameter, System.Globalization.CultureInfo culture)
        {
            throw new NotSupportedException();
        }
    }
}

將框線屬性加入至控制項

最後一個步驟是繫結 LightSwitch 控制項的 Margin 屬性設定為 Silverlight 實作。

加入邊界

在 方案總管中，開啟 MyStackPanelExtension.Client專案的 MyStackPanel.xaml 檔案。

將下列命名空間對應。

xmlns:controls="clr-namespace:MyStackPanelExtension.Presentation.Controls;assembly=MyStackPanelExtension.Client"

將轉換器當做控制項的靜態資源。

<UserControl.Resources>
        <!-- Define a converter to convert a LightSwitch control property to the value that is used in Silverlight controls. -->        
        <controls:DoubleToThicknessConverter x:Key="DoubleToThicknessConverter" />
    </UserControl.Resources>

將 Margin 屬性加入至 ContentPresenterItem項目。

<framework:ContentItemPresenter ContentItem="{Binding}" 
                                                Margin="{Binding Path=Properties[MyStackPanelExtension:MyStackPanel/Margin], Converter={StaticResource DoubleToThicknessConverter}}" />

MyStackPanel.xaml 檔案的完整程式碼現在應該會與下列範例類似。

<UserControl x:Class="MyStackPanelExtension.Presentation.Controls.MyStackPanel"
             xmlns="https://schemas.microsoft.com/winfx/2006/xaml/presentation"
             xmlns:framework ="clr-namespace:Microsoft.LightSwitch.Presentation.Framework;assembly=Microsoft.LightSwitch.Client"
             xmlns:controls="clr-namespace:MyStackPanelExtension.Presentation.Controls;assembly=MyStackPanelExtension.Client"
             xmlns:x="https://schemas.microsoft.com/winfx/2006/xaml">

    <UserControl.Resources>
        <!-- Define a converter to convert a LightSwitch control property to the value used in Silverlight controls. -->
        <controls:DoubleToThicknessConverter x:Key="DoubleToThicknessConverter" />
    </UserControl.Resources>

    <!-- An ItemsControl is used here to create ContentItemPresenter for all child items in the LightSwitch content tree. -->
    <ItemsControl ItemsSource="{Binding ChildItems}" >

        <!-- ItemsPanel enables the use of a stack panel to arrange all child items. Different group controls typically use different layout panels here. -->
        <ItemsControl.ItemsPanel>
            <ItemsPanelTemplate>
                <StackPanel Orientation="Vertical" />
            </ItemsPanelTemplate>
        </ItemsControl.ItemsPanel>

        <!--
           ItemTemplate enables the mapping of a content item to a Silverlight control. Use a ContentItemPresenter here; bind 
           its ContentItem to the ContentItem in the LightSwitch screen content tree.  -->
        <ItemsControl.ItemTemplate>
            <DataTemplate>
                <framework:ContentItemPresenter ContentItem="{Binding}" 
                                                Margin="{Binding Path=Properties[MyStackPanelExtension:MyStackPanel/Margin], Converter={StaticResource DoubleToThicknessConverter}}" />

            </DataTemplate>
        </ItemsControl.ItemTemplate>
    </ItemsControl>
</UserControl>

測試堆疊面板控制項

智慧型配置控制項現在已完成。您可以在 Visual Studio 的實驗執行個體中進行測試。如果您尚未測試其他 LightSwitch 擴充性專案，您必須先啟用實驗執行個體。

啟用實驗執行個體

在 方案總管中，選擇 BusinessTypeExtension.Vsix專案。
選擇功能表列上的專案、BusinessTypeExtension.Vsix 屬性。
在偵錯索引標籤的 啟動動作底下，選取 啟動外部程式。
輸入 Visual Studio 可執行檔 devenv.exe 的路徑。

在 32 位元系統上，預設路徑是 C:\Program Files\Microsoft Visual Studio 12.0\Common7\IDE\devenv.exe；在 64 位元系統上，則是 C:\Program Files (x86)\Microsoft Visual Studio 12.0\Common7\IDE\devenv.exe。
在 命令列引數欄位中，輸入 /rootsuffix Exp。

注意事項

所有後續的 LightSwitch 擴充性專案也會預設使用這個設定。

注意事項
所有後續的 LightSwitch 擴充性專案也會預設使用這個設定。

若要測試堆疊面板控制項

在功能表列上，選擇 [偵錯]、[開始偵錯]。 Visual Studio 的實驗執行個體隨即開啟。
在實驗個體功能列表中，選擇檔案、新增、專案。
在 新增專案 對話方塊中，展開Visual Basic 或 **Visual C#**節點，然後選擇 LightSwitch節點，再選擇 LightSwitch 桌面應用程式範本。
在名稱欄位中，輸入 MyStackPanelTest，然後選擇好按鈕以建立測試專案。
然後選擇功能表列上的專案、MyStackPanelTest屬性。
在專案設計工具中，請在擴充功能索引標籤上，選取MyStackPanelExtension 核取方塊。
建立具有 清單和詳細資料畫面的 LightSwitch 應用程式，然後在螢幕設計工具中，將資料行配置控制項加入至 我的堆疊面板。

選取子項目在我的堆疊面板 下。請注意 Margin 屬性會出現在屬性視窗中。
在功能表列上，選擇 [偵錯]、[開始偵錯]。檢視我的堆疊面板控制項的行為在應用程式的。

請參閱

工作

如何：建立 LightSwitch 控制項

概念

定義、覆寫和使用 LightSwitch 控制項屬性

Visual Studio 2013 的 LightSwitch 擴充性工具組

共用方式為