WebLayout 和 Control 元素

项目
07/19/2022

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

使用 WebLayout 元素定义在通过 Web 门户显示的工作项窗体上显示的布局和控件。它支持新的工作项体验。除了 Layout 元素之外，它还定义通过 Visual Studio 和其他非 Web 客户端查看时显示的窗体元素。

重要

本文适用于托管 XML 和本地 XML (TFS 2017 及更高版本) 进程模型的项目自定义。有关 TFS 2015 和早期版本，请参阅 Layout XML 元素参考。

有关继承过程模型，请参阅自定义进程。有关流程模型的概述，请参阅自定义工作跟踪体验。

WebLayout 元素是 FORM 元素的必需子元素。本主题记录 WebLayout 元素及其子元素。使用本指南可以进一步自定义包含新 WebLayout 部分的 WIT 定义。若要了解有关这些更改的详细信息，请参阅博客文章，宣布弃用 TFS 中的旧工作项表单。

若要修改 Web 布局，请使用本主题中提供的信息修改特定工作项类型的 XML 定义文件。若要导入和导出更改，请参阅自定义工作跟踪 Web 窗体。

若要自定义 Windows 客户端布局，请参阅 Layout XML 元素。

启用新窗体和 WebLayout 部分

启用新窗体推出后，集合中所有工作项类型的 XML 定义 (WIT) 将更新为在 FORM 节中包含 WebLayout 节。

新窗体提供了多个新功能，如 “新建工作项”体验中所述。帐户或项目集合管理员管理切换到新窗体。

对于继承过程模型，切换到新窗体对所有用户帐户都是自动的。
对于托管 XML 进程模型，管理员必须启用新窗体。
对于 TFS 2017，将项目添加到新集合时，新窗体将自动可用。对于现有项目，管理员必须启用新窗体。
对于 TFS 2015，新窗体不可用。必须升级到 TFS 2017 或更高版本才能访问新窗体。

元素和属性摘要

WebLayout 和更新的 Control 元素引入了多个新元素，并弃用多个元素和属性。总的来说，它比前身更简单的语法结构。

新元素	维护的元素	已弃用的元素	已弃用的属性
- ControlContribution - GroupContribution - 输入 - 输入 - 页面 - PageContribution - 节 - SystemControls - WebLayout	- FORM - 布局 - 组 - 控件	- 列 - 拆分器 - Tab - TabGroup	- ControlSpacing - FixedWidth - LabelPosition - LabelSpacing - 边距 - MinimumSize - 填充 - PercentWidth

提示

Page 元素类似于已弃用的 Tab 元素。但是，无法对 Page 元素进行分组或嵌套。一页定义 Web 窗体中的一个选项卡。

标头自定义

在新 Web 窗体布局中，系统管理 SystemControls 元素中的多个标头元素。其中包括：

字段：工作项 ID、标题、分配给、状态、原因、区域路径、迭代路径和标记
页面：历史记录、链接和附件。

Header element within web form

导出 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 元素。

使用“节”和“组”元素对页面中显示的元素进行分组。使用 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 元素参考。

元素

说明

控制

WebLayout 中组的可选子元素。定义要在工作项窗体上显示的字段、文本、超链接或其他控件元素。

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

有关每个属性的信息，请参阅 Control 元素属性和控件类型。

ControlContribution

WebLayout 中组的可选子元素，用于指定要显示在窗体上的字段级工作项扩展。

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

指定的 ContributionId 必须安装在帐户或项目集合上。导出的 WIT 定义文件包含已安装的贡献列表。

扩展名

Extensions 的必需子元素。用于指定工作项控件扩展的扩展 ID，以在工作项窗体中显示。必须指定 ControlContribution、GroupContribution 或 PageContribution 元素的布局中使用的每个扩展。

<Extension Id="ExtensionId" />

指定的 ExtensionId 必须安装在帐户或项目集合上。导出的 WIT 定义文件包含已安装的扩展列表。

扩展

用于支持指定一个或多个扩展元素的 WebLayout 的可选容器子元素。如果在窗体中使用扩展，请在 Page 元素之前指定它们。

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

形式

WITD 的必需子元素，用于指定要显示在工作项窗体上的布局和控件。布局 (客户端窗体布局) 和 WebLayout (Web 窗体布局) 元素的父元素。

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

组

Section 的必需子元素。提供可标记的节中的元素的视觉分组。

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

GroupContribution

WebLayout 中 Section< 的可选子元素，用于指定要显示在窗体上的组级工作项扩展。该扩展将作为窗体中的组显示。

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

指定的 ContributionId 必须安装在帐户或项目集合上。导出的 WIT 定义文件包含已安装的贡献列表。

输入

输入的必需子元素，用于指定扩展的输入数据。

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

输入

ControlContribution 的可选容器子元素，用于支持扩展的输入数据的规范。

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

第

WebLayout 的必需子元素。定义 Web 窗体中页面的布局。
指定要使用的页的名称和布局。

<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 的必需子元素。定义 Web 窗体页中节的布局。支持变量大小调整的节窗体组。可以在 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 的必需子元素。定义 Web 门户中显示的工作项窗体的布局。包括一个或多个 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：用于显示布尔值、纯文本、数值字段、人名字段和选取列表。支持数据类型为 Boolean、 Double、 Identity、 Integer、PlainText 和 String 的字段。

注意

功能可用性： TFS 2017 及更高版本支持布尔数据类型字段。

HtmlFieldControl：用于显示具有 HTML 字段类型的多行格式的字段格式。
LabelControl：用于显示与字段不关联的文本。文本可以是纯文本或超链接。可以使用 LabelText、 Link 和 Text 元素指定其他控件。
网页控制：用于显示由 URI 定义的基于 HTML 的内容，或嵌入在 CDATA 标记中。此控件没有关联的字段或字段类型。指定使用 网页控件Options 元素显示的内容和链接。

EmptyText

可选。指定字段为空时显示的长度为 1 到 255 个字符之间的文本字符串。

标签

可选。指定窗体上标识控件的可见文本。指定一个不超过 80 个字符的字符串。如果未指定，则使用友好 FieldName 名称。

ReadOnly

可选。指定字段为只读：

True：控件字段为只读。
False：控件字段不是只读的。

名称

可选。唯一地标识控件。如果窗体上的多个控件与同一工作项字段相关联，则名称非常重要。

注意

如果要在窗体上的多个页面上显示相同的字段，请使用 Name 属性。为这两个控件条目指定 Name 属性的唯一值，以便系统唯一标识每个控件。

Visible

可选。指定 Visible="false" 何时要隐藏标头区域中通常包含的字段。只能将此属性与 System.Reason、System.AreaPath 或 System.IterationPath 字段结合使用。如果指定此属性，则无法指定 Replaces 该属性。

取代

可选。指定 FieldName="ReplacementFieldRefName" Replaces="FieldRefName" 何时要将标题区域中的字段替换为另一个字段。只能将此属性与 System.Reason、System.AreaPath 或 System.IterationPath 字段结合使用。如果指定此属性，则无法指定 Visible 该属性。此外，还需要从节内删除要替换的字段的条目。

Control 元素类型属性语法

类型

说明

DateTimeControl

Use to display formatted date fields with a data type of DateTime. 用于 FieldControl 为 DateTime 字段的输入或显示提供文本字段。

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

用于 DateTimeControl 提供日历选取器来选择字段的日期，如下图所示。

Date-Time control, Calendar field

<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 工作项窗体中的复选框。

Boolean field display in web work item form

HTMLFieldControl

用于显示多行格式的富文本控件。为字段 Type=HTML指定此控件类型。
HTML field shown on work item form
例如：

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

LabelControl

用于显示与字段不关联的文本。文本可以是纯文本或超链接。可以使用 LabelText、 Link 和 Text 元素指定其他控件。请参阅 LabelText 和 Text XML 元素引用以及链接和 Param XML 元素引用。

WebpageControlOptions

用于显示由 URI 定义的基于 HTML 的内容，或嵌入在 CDATA 标记中。此控件没有关联的字段或字段类型。指定使用 网页控件Options 元素显示的内容和链接。

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/>

可以使用 Content、 LabelText 和 Link 元素来定义纯文本或超链接标签、向字段添加超链接，或在工作项窗体中显示网页内容。有关语法的详细信息，请参阅工作项窗体上的帮助文本、超链接或 Web 内容。

如果刚开始使用新窗体，请参阅以下附加主题来管理推出或自定义它：

若要详细了解流程模型以及每个模型支持的内容，请参阅自定义工作跟踪体验。

市场扩展

访问 Azure DevOps 市场以查找可以开始使用的扩展。

表单扩展

ControlContribution、GroupContribution 和 PageContribution 元素引用Id已为项目集合或帐户安装的扩展的贡献。从 Visual Studio Marketplace 安装扩展。若要创建扩展，请参阅创建第一个扩展。

安装扩展后，将 “贡献 ”元素添加到工作项类型的 XML 定义中。可以通过导出进程或导出 WIT 定义文件来导出这些文件。

导出 XML 定义时，它将包含一个注释部分，其中列出了已安装的扩展、其 ID 和任何必需的输入。例如：

<!--**********************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
-->

在上述示例中，可以通过指定扩展 ID 将以下代码片段添加到工作项类型定义，以打开用户语音组 vsts-uservoice-ui 扩展：

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

导入更新的 WIT 定义后，组扩展将自动显示在工作项窗体上。

下次导出 WIT 定义时，会看到已添加元素 GroupContribution 。可以像任何其他控件一样在 WebLayout 节中移动此元素。

WebLayout 和 Control 元素

启用新窗体和 WebLayout 部分

元素和属性摘要

标头自定义

WebLayout 示例

WebLayout 元素语法

属性

Control 元素语法

Control 元素属性语法

Control 元素类型属性语法

相关文章

市场扩展

表单扩展