WebLayout 和 Control 元素

Azure DevOps Services |Azure DevOps Server 2022 |Azure DevOps Server 2020 |Azure DevOps Server 2019 |TFS 2018

您可以使用 WebLayout 元素來定義透過入口網站顯示的工作專案表單上顯示的版面配置和控制項。 它支援 新的工作專案體驗。 除了Layout元素之外,還會定義透過 Visual Studio 和其他非 Web 用戶端檢視時出現的表單元素。

重要

本文適用于裝載 XML 和內部部署 XML (TFS 2017 和更新版本的專案自訂,) 處理模型。 如需 TFS 2015 和舊版,請參閱 版面配置 XML 元素參考

如需繼承進程模型,請參閱 自訂程式。 如需程式模型的概觀,請參閱 自訂您的工作追蹤體驗

WebLayout元素是FORM元素的必要子專案。 本主題記載 WebLayout 元素及其子項目。 使用本指南進一步自訂包含新 WebLayout 區段的 WIT 定義。 若要深入瞭解這些變更,請參閱部落格文章: 宣佈在 TFS 中淘汰舊的工作專案表單

若要修改網頁版面配置,請使用本主題中提供的資訊來修改特定工作專案類型的 XML 定義檔。 若要匯入和匯出變更,請參閱 自訂工作追蹤 Web 表單

若要自訂 Windows 用戶端配置,請參閱 Layout XML 元素

啟用新表單和 WebLayout 區段

啟用新的表單推出時,集合中所有工作專案類型的 XML 定義 (WIT) 都會更新為在 FORM區段中包含WebLayout區段。

新的表單提供數個新功能,如 新增工作專案體驗中所述。 您的帳戶或專案集合管理員會管理 切換至新表單

元素和屬性摘要

WebLayout和更新的Control元素引進數個新元素,並取代數個元素和屬性。 整體來說,它是比其前置詞更簡單的語法結構。

新元素 維護的專案 已被取代的專案 已過時的屬性
- ControlContribution
- GroupContribution
- 輸入
- 輸入
- 頁面
- PageContribution
- 區段
- SystemControls
- WebLayout
- FORM
- 版面配置
- 群組
- 控制項
- 資料行
- 分割器
- 索引標籤
- TabGroup
- ControlSpacing
- FixedWidth
- LabelPosition
- LabelSpacing
- 邊界
- MinimumSize
- 填補
- PercentWidth

提示

Page元素類似于已被取代的Tab元素。 不過, Page 元素無法分組或巢狀。 一個頁面會在 Web 表單內定義一個索引標籤。

標頭自訂

在新的 Web 表單配置中,系統會管理 SystemControls 元素內的數個標頭元素。 其中包含:

  • 欄位:工作專案識別碼、標題、指派給、狀態、原因、區域路徑、反復專案路徑和標籤
  • 頁面歷程記錄頁面圖示 [歷程記錄 ]、 [連結] 頁面圖示 [連結 ] 和 [ 附件] 頁面圖示 [附件 ]。

Web 表單中的 Header 元素

當您匯出 WIT 定義時,您會看到WebLayout區段開頭的SystemControls區段,如下所示:

<WebLayout ShowEmptyReadOnlyFields="true"> 
    <SystemControls>
      <Control Type="FieldControl" FieldName="System.Title" EmptyText="Enter title" />
      <Control Label="Assi&amp;gned To" Type="FieldControl" FieldName="System.AssignedTo" />
      <Control Label="Stat&amp;e" Type="FieldControl" FieldName="System.State" />
      <Control Label="Reason" Type="FieldControl" FieldName="System.Reason" />
      <Control Label="&amp;Area" Type="WorkItemClassificationControl" FieldName="System.AreaPath" />
      <Control Label="Ite&amp;ration" Type="WorkItemClassificationControl" FieldName="System.IterationPath" />
      <Control Label="History" Type="WorkItemLogControl" FieldName="System.History" />
      <Control Label="Links" Type="LinksControl" Name="Links" />
      <Control Label="Attachments" Type="AttachmentsControl" Name="Attachments" />
    </SystemControls>
...

注意

Link元素不是SystemControls區段中允許的專案。

針對 TFS 2017,內部部署 XML 進程模型:您可以修改SystemControls區段中的選取元素,例如變更System.Title欄位的EmptyText屬性值。 一般而言,我們建議您不要自訂此區段遠超過此區段。 例如,您無法從此區段移除欄位,或新增其他欄位。

針對 TFS 2018、內部部署 XML 和Azure DevOps Services、託管的 XML 進程模型:您可以指定ShowEmptyReadOnlyFields屬性,或選取以隱藏或取代SystemControls區段中定義的選取欄位。

例如,若要隱藏 Reason 欄位,您可以使用 屬性來修改 Control 元素 Visible

<Control Label="Reason" Type="FieldControl" FieldName="System.Reason" Visible="false" />

若要將 Reason 欄位取代為另一個欄位,請使用 Replaces 屬性。 此外,請從 區段中移除 [原因] 欄位的專案。

<Control Label="Milestone" Type="FieldControl" FieldName="Fabrikam.Milestone" Replaces="System.Reason" />

您可以隱藏或取代 [原因]、[區域路徑] 和 [反復專案路徑] 欄位。 如果您想要,請將這些欄位新增至 [詳細資料] 頁面或其他自訂頁面。 您無法隱藏或取代 [標題]、[指派給] 或 [狀態] 欄位。

WebLayout 範例

下列範例顯示FORM區段中WebLayout區段的整體結構。 WebLayout會針對您想要出現在表單上的每個欄位指定Control元素。

您可以使用SectionGroup元素,將元素分組在Page內。 您可以使用 Control 元素來定義您想要出現在表單上的每個欄位或控制項。

下列範例會指定本主題先前所示的 [詳細資料] 頁面語法。

<FORM>
. . .
  <WebLayout>
       <SystemControls>
          <Control Type="FieldControl" FieldName="System.Title" EmptyText="Enter title" />
          <Control Label="Assi&amp;gned To" Type="FieldControl" FieldName="System.AssignedTo" />
          <Control Label="Stat&amp;e" Type="FieldControl" FieldName="System.State" />
          <Control Label="Reason" Type="FieldControl" FieldName="System.Reason" />
          <Control Label="&amp;Area" Type="WorkItemClassificationControl" FieldName="System.AreaPath" />
          <Control Label="Ite&amp;ration" Type="WorkItemClassificationControl" FieldName="System.IterationPath" />
          <Control Label="History" Type="WorkItemLogControl" FieldName="System.History" />
          <Control Label="Links" Type="LinksControl" Name="Links" />
          <Control Label="Attachments" Type="AttachmentsControl" Name="Attachments" />
        </SystemControls>
    <Page Label="Details" LayoutMode="FirstColumnWide">
        <Section>
          <Group Label="Description">
             <Control Label="Description" Type="HtmlFieldControl" FieldName="System.Description" />
          </Group>
        </Section>
        <Section>
      <Group Label="Planning">
          <Control Label="Story Points" Type="FieldControl" FieldName="Microsoft.VSTS.Scheduling.StoryPoints" />
          <Control Label="Priority" Type="FieldControl" FieldName="Microsoft.VSTS.Common.Priority" />
        </Group>
        <Group Label="Classification">
          <Control Label="Value area" Type="FieldControl" FieldName="Microsoft.VSTS.Common.ValueArea" />
        </Group>
      </Section>
      <Section>
        <Group Label="Development">
          <Control Type="LinksControl" Name="Development">
            <LinksControlOptions ViewMode="Dynamic" ZeroDataExperience="Development" ShowCallToAction="true">
              <ListViewOptions GroupLinks="false">
              </ListViewOptions>
              <LinkFilters>
                <ExternalLinkFilter Type="Build" />
                <ExternalLinkFilter Type="Pull Request" />
                <ExternalLinkFilter Type="Branch" />
                <ExternalLinkFilter Type="Fixed in Commit" />
                <ExternalLinkFilter Type="Fixed in Changeset" />
                <ExternalLinkFilter Type="Source Code File" />
              </LinkFilters>
            </LinksControlOptions>
          </Control>
        </Group>
       <Group Label="Related Work">
          <Control Type="LinksControl" Name="Related Work">
            <LinksControlOptions>
              <LinkFilters>
                <WorkItemLinkFilter Type="System.LinkTypes.Hierarchy-Reverse" />
                <WorkItemLinkFilter Type="System.LinkTypes.Hierarchy-Forward" />
                <WorkItemLinkFilter Type="System.LinkTypes.Related" />
              </LinkFilters>
              <Columns>
                <Column Name="System.State" />
                <Column Name="System.ChangedDate" />
                <Column Name="System.Links.Comment" />
              </Columns>
            </LinksControlOptions>
          </Control>
        </Group>
      </Section>
    </Page>
  </WebLayout>
</FORM>

WebLayout 元素語法

您可以使用下表中說明的項目,指定要如何將資訊和工作項目欄位分組並顯示在工作項目表單中。

<WebLayout ShowEmptyReadOnlyFields="true | false">
   ...
</WebLayout>

屬性

屬性 描述
ShowEmptyReadOnlyFields 選擇性 WebLayout 屬性。 指定要顯示唯讀和空白欄位的值 true , (預設) ,並 false 隱藏這些欄位。

提示

工作專案追蹤的架構定義會將所有 FORM 子項目定義為 camel 大小寫,而所有其他元素則定義為所有大寫。 如果在驗證型別定義檔時發生錯誤,請檢查項目的大小寫結構。 此外,開頭和結尾標記的大小寫結構也必須符合 XML 語法的規則。 如需詳細資訊,請參閱 Control XML 元素參考

Element

說明


控制

WebLayoutGroup的選擇性子專案。 定義要顯示在工作項目表單上的欄位、文字、超連結或其他控制項項目。

<Control FieldName="FieldName" Type="DateTimeControl | ExtensionsControl |  
FieldControl | HtmlFieldControl | LabelControl | WebpageControl"  
Label="LabelText" EmptyText="TextString" 
ReadOnly="True | False" Name="InstanceName" />

如需每個屬性的相關資訊 ,請參閱 Control 元素屬性控制項類型

ControlContribution

WebLayoutGroup的選擇性子專案,用來指定要在表單上顯示的欄位層級工作專案延伸。

<ControlContribution Id="ContributionId" Label="Name">  
<Inputs>  
<Input Id="FieldName" Value="Value" />  
</Inputs>  
</ControlContribution>  

您指定的 ContributionId 必須安裝在帳戶或專案集合上。 您匯出的 WIT 定義檔案包含 已安裝的貢獻清單

延伸模組

Extensions的必要子專案。 用來指定工作專案控制項延伸模組的延伸模組識別碼,以顯示在工作專案表單中。 您必須指定 ControlContributionGroupContributionPageContribution 元素配置中使用的每個延伸模組。

<Extension Id="ExtensionId" />  

您指定的 ExtensionId 必須安裝在帳戶或專案集合上。 您匯出的 WIT 定義檔案包含 已安裝的延伸模組清單

擴充功能

WebLayout的選擇性容器子專案,用來支援指定一或多個Extension元素。 如果在表單中使用延伸模組,請在 Page 元素之前指定它們。

<WebLayout >  
<Extensions >  
<Extension Id="ExtensionId" />  
. . .   
</Extensions>   
. . .
</WebLayout>  

形式

WITD的必要子專案,用來指定要顯示在工作專案表單上的版面配置和控制項。 Layout (用戶端表單配置) 和WebLayout (Web表單配置) 元素的父元素。

<FORM>  
<Layout> . . . </Layout>  
<WebLayout> . . . </WebLayout>  
</FORM>  

群組

Section的必要子專案。 提供區段中元素的視覺群組,您可以標記。

<Group Label="LabelText"   
<Control> . . . </Control>  
</Group>  

GroupContribution

WebLayoutSection <的選擇性子專案,用來指定要顯示在表單上的群組層級工作專案延伸模組。 延伸模組會顯示為表單內的群組。

<GroupContribution Id="ContributionId" Label="Name" />  

您指定的 ContributionId 必須安裝在帳戶或專案集合上。 您匯出的 WIT 定義檔案包含 已安裝的貢獻清單

輸入

Inputs的必要子專案,指定延伸模組的輸入資料。

<Input Id="FieldName" Value="Value" />  

輸入

ControlContribution的選擇性容器子專案,用於支援延伸模組的輸入資料規格。

<Inputs>
<Input Id="FieldName" Value="Value" />  
</Inputs>

頁面

WebLayout的必要子項目。 定義網頁表單中頁面的版面配置。
指定要使用的頁面名稱和版面配置。

<Page Label="PageName" LayoutMode="FirstColumnWide | EqualColumns ">  
<Section>    
<Group> . . .   
<Control> . . . </Control>  
<Control> . . . </Control>  
</Group>  
</Section>  
</Page>  

PageContribution

WebLayout的選擇性子專案,用來指定要顯示在表單上的頁面層級工作專案延伸模組。 延伸模組會顯示為表單內的頁面。

<PageContribution Id="ContributionId" Label="Name"  />  

您指定的 ContributionId 必須安裝在帳戶或專案集合上。 您匯出的 WIT 定義檔案包含 已安裝的貢獻清單

小節

Page的必要子專案。 定義網頁表單頁面內區段的配置。 區段支援 變數調整大小的表單群組。 您可以在 Page內定義四個區段的限制。

<Page>  
<Section>    
<Group> . . .   
<Control> . . . </Control>  
<Control> . . . </Control>  
</Group>  
</Section>  
</Page>  

SystemControls

WebLayout的必要子專案。 定義 Web 表單標頭中存在控制項的標籤和空白文字值。 這也包括 [歷程記錄]、[ 連結] 和 [附件] 頁面 標籤

<SystemControls>    
<Control Type="FieldControl" FieldName="System.Title" EmptyText="Enter title" />   
<Control Label="Assi&gned To" Type="FieldControl" FieldName="System.AssignedTo" />  
<Control Label="Stat&e" Type="FieldControl" FieldName="System.State" />  
<Control Label="Reason" Type="FieldControl" FieldName="System.Reason" />  
<Control Label="&Area" Type="WorkItemClassificationControl" FieldName="System.AreaPath" />  
<Control Label="Ite&ration" Type="WorkItemClassificationControl" FieldName="System.IterationPath" />  
<Control Label="History" Type="WorkItemLogControl" FieldName="System.History" />  
<Control Label="Links" Type="LinksControl" Name="Links" />  
<Control Label="Attachments" Type="AttachmentsControl" Name="Attachments" />  
</SystemControls>  

WebLayout

FORM的必要子專案。 定義入口網站中顯示的工作專案表單配置。 包含一或多個 Page 元素。

<WebLayout>  
<Page>  
<Section>  
<Group> . . . 
<Control> . . . </Control>  
<Control> . . . </Control>  
</Group>  
</Section>  
</Page>  
. . .
</WebLayout>

Control 元素語法

您可以使用 Control 元素來定義工作專案欄位、文字、超連結或其他表單類型,以顯示在工作專案表單中。 您在WebLayout區段中指定的Control元素應該符合下列語法:

<Control FieldName="FieldRefName" Type="DateTimeControl | FieldControl | 
HtmlFieldControl | LabelControl | WebpageControl Label="LabelText" 
LabelPosition="Top | Bottom | Left | Right" EmptyText="TextString" 
ReadOnly="True | False" Name="InstanceName" [Visible="false" | 
FieldName="ReplacementFieldRefName" Replaces="FieldRefName"] />

Control 元素屬性語法

Attribute

說明

FieldName

選擇性。 指定與控制項相關聯的工作項目欄位。 指定欄位的參考名稱,其長度應介於 1 到 70 個字元之間。

型別

必要。 指定控制項的資料型別。 從下列其中一個內建類型指定字串:

  • DateTimeControl:用來顯示具有 DateTime欄位類型的格式化日期欄位。
  • FieldControl:用來顯示布林值、純文字、數值欄位、人員名稱欄位,以及挑選清單。 支援資料類型為 BooleanDoubleIdentityIntegerPlainTextString的欄位。

注意

功能可用性: TFS 2017 和更新版本支援布林資料類型欄位。

  • HtmlFieldControl:用來顯示具有 HTML欄位類型的多行 RTF 格式欄位。
  • LabelControl:用來顯示與欄位無關的文字。 文字可以是純文字或超連結文字。 您可以使用 LabelTextLinkText 元素來指定其他控制項。
  • 網頁Control:用來顯示由 URI 或內嵌在 CDATA 標籤內的 HTML 型內容。 此控制項沒有相關聯的欄位或欄位型別。 您可以使用 網頁ControlOptions 元素指定要顯示的內容和連結。

EmptyText

選擇性。 指定欄位為空白時顯示的 1 到 255 個字元長度的文字字串。

標籤

選擇性。 指定表單上可識別控制項的可見文字。 指定長度不超過 80 個字元的字串。 如果未指定,則會使用 的 FieldName 易記名稱。

ReadOnly

選擇性。 指定欄位是唯讀的:

  • True:控制項欄位是唯讀的。
  • False:控制項欄位不是唯讀的。

名稱

選擇性。 唯一識別控制項。 如果表單上的多個控制項與相同的工作專案欄位相關聯, 則 Name 很重要。

注意

當您想要在表單上的多個頁面上顯示相同的欄位時,請使用Name屬性。 您會為這兩個控制項專案指定 Name 屬性的唯一值,讓系統能夠唯一識別每個控制項。

Visible

選擇性。 指定 Visible="false" 當您想要隱藏一般包含在標頭區域內的欄位時。 您只能搭配 System.Reason、System.AreaPath 或 System.IterationPath 欄位來指定此屬性。 如果您指定此屬性,則無法指定 Replaces 屬性。

取代

選擇性。 指定 FieldName="ReplacementFieldRefName" Replaces="FieldRefName" 何時要將標頭區域內的欄位取代為另一個欄位。 您只能搭配 System.Reason、System.AreaPath 或 System.IterationPath 欄位來指定此屬性。 如果您指定此屬性,則無法指定 Visible 屬性。 此外,您必須從 區段內移除您要取代之欄位的專案。

Control 元素 Type 屬性語法

型別

說明

DateTimeControl

使用 來顯示資料類型為 DateTime 的格式化日期欄位。 用來 FieldControl 提供輸入或顯示 DateTime 欄位的文字欄位。

<Control FieldName=" MyCompany.Group1.StartDate " Type="FieldControl" 
Label="Start Date" LabelPosition="Left" />

使用 DateTimeControl 提供行事曆選擇器來選取欄位的日期,如下圖所示。

日期時間控制項、行事曆欄位

<Control Type="DateTimeControl" FieldName="FabrikamFiber.Schedule.SubmittedDate" 
Label="Submitted Date:" LabelPosition="Left"  Format="Short" />

注意

顯示的日期時間格式符合 使用者設定檔使用者設定檔。 WebLayout 區段不接受 Layout 元素 CustomFormat 屬性。

FieldControl

用來顯示資料類型為 Boolean、String、Identity、Integer、Double 和 PlainText 的欄位。 例如:

<Control Type="FieldControl" FieldName="FabrikamFiber.Milestone" 
Label="Milestone" Name="Milestone" LabelPosition="Left" />

功能可用性: 只有 TFS 2017 和更新版本才支援布林資料類型欄位。 在用戶端工作專案表單中,例如 Visual Studio 或 Eclipse,將會顯示 True 或 False 的值。

布林值欄位會顯示為 Web 工作專案表單內的核取方塊。

Web 工作專案表單中的布林值欄位顯示

HTMLFieldControl

用來顯示多行、RTF 格式的控制項。 針對 的 Type=HTML 欄位指定此控制項類型。
工作項目表單上顯示的 HTML 欄位
例如:

<Control Type="HtmlFieldControl" FieldName="FabrikamFiber.ReleaseNotes" 
Label="Release Notes" Dock="Fill" />

LabelControl

使用 來顯示與欄位無關的文字。 文字可以是純文字或超連結文字。 您可以使用 LabelTextLinkText 元素來指定其他控制項。 請參閱 LabelText 和 Text XML 元素參考Link 和 Param XML 元素參考

WebpageControlOptions

用來顯示由 URI 或內嵌在 CDATA 標籤內的 HTML 型內容。 此控制項沒有相關聯的欄位或欄位型別。 您可以使用 網頁ControlOptions 元素指定要顯示的內容和連結。

WebControlOptions元素及其子項目具有下列語法結構:

<WebpageControlOptions AllowScript="true | false" ReloadOnParamChange="true | false" >  
<Link UrlRoot="UrlRoot" UrlPath ="UrlPathWithParameters" >  
<Param index="IndexValue" value="ParamValue" type ="Original | Current">  
</Link>  
<Content>  
<![CDATA[Contents of HTML]]/>  
<Content/>  
<WebpageControlOptions/>

您可以使用 ContentLabelTextLink 元素來定義純文字或超連結標籤、將超連結新增至欄位,或在工作專案表單中顯示網頁內容。 如需語法的詳細資訊 ,請參閱在工作專案表單上提供解說文字、超連結或 Web 內容

如果您剛開始使用新的表單,請參閱下列其他主題來管理推出或自訂它:

若要深入瞭解程式模型以及每個模型支援的專案,請參閱 自訂您的工作追蹤體驗

Marketplace 擴充功能

請造訪 Azure DevOps Marketplace 來尋找您可以開始使用的擴充功能。

表單延伸模組

ControlContributionGroupContribution 和 PageContribution元素會參考 Id 已針對專案集合或帳戶安裝之延伸模組的貢獻。 您可以從 Visual Studio Marketplace安裝擴充功能。 若要建立延伸模組,請參閱 建立您的第一個延伸模組

安裝延伸模組之後,您會將 Contribution 元素新增至工作專案類型的 XML 定義。 您可以 匯出進程匯出 WIT 定義檔來匯出這些檔案

當您匯出 XML 定義時,它將會包含批註區段,其中列出已安裝的延伸模組、其識別碼,以及任何必要的輸入。 例如:

<!--**********************Work Item Extensions**********************
Extension:
    Name: color-control-dev
    Id: mariamclaughlin.color-control-dev
    Control contribution:
        Id: mariamclaughlin.color-control-dev.color-control-contribution
        Description: 
        Inputs:
            Id: FieldName
            Description: The field associated with the control.
            Type: Field
            IsRequired: true
            Id: Labels
            Description: The list of values to select from.
            Type: String
            IsRequired: false
            Id: Colors
            Description: The field associated with the control.
            Type: String
            IsRequired: false  
Extension:
    Name: vsts-workitem-recentlyviewed
    Id: mmanela.vsts-workitem-recentlyviewed  
    Group contribution:
        Id: mmanela.vsts-workitem-recentlyviewed.recently-viewed-form-group
        Description: Recently viewed work item form group  
Extension:
    Name: vsts-extensions-multi-values-control
    Id: ms-devlabs.vsts-extensions-multi-values-control   
    Control contribution:
        Id: ms-devlabs.vsts-extensions-multi-values-control.multi-values-form-control
        Description: Multi Values Selection Control.
        Inputs:
            Id: FieldName
            Description: The field associated with the control.
            Type: Field
            IsRequired: true
            Id: Values
            Description: The list of values to select from.
            Type: String
            IsRequired: false
Extension:
    Name: vsts-extension-workitem-activities
    Id: ms-devlabs.vsts-extension-workitem-activities   
Extension:
    Name: vsts-uservoice-ui
    Id: ms-devlabs.vsts-uservoice-ui   
    Group contribution:
        Id: ms-devlabs.vsts-uservoice-ui.vsts-uservoice-ui-wi-group
        Description: Shows User Voice details on the work item form
-->

在上述範例中,您可以藉由指定擴充功能識別碼,將下列程式碼片段新增至工作專案類型定義,以開啟使用者語音群組 vsts-uservoice-ui 擴充功能:

<WebLayout>
... 
 <Extensions>
     <Extension Id="ms-devlabs.vsts-uservoice-ui" />
 </Extensions>
...
</WebLayout> 

匯入更新的 WIT 定義時,群組延伸模組會自動出現在您的工作專案表單上。

下次匯出 WIT 定義時,您會看到 GroupContribution 已新增元素。 您可以在 區段中移動此元素 WebLayout ,就像任何其他控制項一樣。