通过

定义选取列表

  • 项目

通过在字段的定义中或者在工作流的某一时间点定义选取列表，你可以为该字段枚举一组值。 你可以指定列表只能包含值，不能包含禁止值，或者可以建议值。 如果你建议值，则用户可以指定选取列表以外的值。

你还可以定义依赖选取列表，在这种情况下你还可以为一个字段定义两个或以上的列表，但根据条件规则的计算结果在运行时只显示一个列表。

主题内容

  • 语法结构

  • GLOBALLIST 和 LISTITEM 元素的语法结构

  • 允许现有值

  • 枚举一组允许值

  • 定义依赖选取列表

备注

要为 FIELD 定义添加或修改选取列表，请使用 witadmin 命令行工具导入和到处工作项类型的定义。请参阅导入、导出和管理工作项类型 [witadmin]。

语法结构

可以使用 ALLOWEDVALUES、SUGGESTEDVALUES 和 PROHIBITEDVALUES 元素指定用户必须、可以或不得指定为字段值的值列表。 如果使用上述每一种元素，则可以枚举项列表或指定全局列表。 如果从选取列表中移除项，则可以使用 ALLOWEXISTINGVALUE 来允许字段存储现有值。

可以将这些元素指定为 FIELD（定义）或 FIELD（工作流）元素的子元素。

  • 使用 ALLOWEDVALUES 定义用户可以在工作项窗体或查询编辑器中指定的值列表。 用户必须指定 GLOBALLIST 或 LISTITEM 条目集中的其中一个值。

    <ALLOWEDVALUES for="userGroupName" not="userGroupName" expanditems="true | false" filteritems="excludegroups">
   <GLOBALLIST name="globalListName" />
   <LISTITEM value="Name1" />
   <LISTITEM value="Name2" />
   <LISTITEM value="Name3" />
. . . 
</ALLOWEDVALUES>

  • 使用 PROHIBITEDVALUES 定义字段无法包含的值列表。 如果字段包含被禁止的值，则用户无法保存工作项。 如果希望限制使用之前允许但已无效的值，请使用此元素。

    <PROHIBITEDVALUES for="userGroupName" not="userGroupName" expanditems="true | false" filteritems="excludegroups">
   <GLOBALLIST name="globalListName" />
   <LISTITEM value="Name1" />
   <LISTITEM value="Name2" />
   <LISTITEM value="Name3" />
. . . 
</PROHIBITEDVALUES>

  • 使用 SUGGESTEDVALUES 定义字段可以包含的值列表。 用户可以指定建议值之外的值。

    <SUGGESTEDVALUES for="userGroupName" not="userGroupName" expanditems="true | false" filteritems="excludegroups">
   <GLOBALLIST name="globalListName" />
   <LISTITEM value="Name1" />
   <LISTITEM value="Name2" />
   <LISTITEM value="Name3" />
. . . 
</SUGGESTEDVALUES>

你可以对上述每个元素指定一个或多个特性，如下表所示：

特性

描述

for

可选。 指定对其应用规则的 Team Foundation 中的用户或组名。 有效名称为一个文本字符串，该字符串含 1 到 255 个字符。

模式值：^[^\\]+\\[^\\]+$

模式值示例：域\用户 ID

not

可选。 指定不对其应用规则的 Team Foundation 中的用户或组名。 有效名称为一个文本字符串，该字符串含 1 到 255 个字符。

模式值：^[^\\]+\\[^\\]+$

模式值示例：域\用户 ID

expanditems

可选。 指定 LISTITEM 元素标识的组是否应该展开以包括列表中的从属组。 默认值为 true。

filteritems

可选。 指定列表中仅包含组成员，而不包含组名称。 此特性的唯一有效值为 excludegroups。

有关详细信息，请参阅在列表中展开列表项以及排除组。

GLOBALLIST 和 LISTITEM 元素的语法结构

可以使用 GLOBALLIST 和 LISTITEM 元素来枚举可以全局更新或特定于单个字段的项列表。

  • 使用 GLOBALLIST 定义一组为团队项目集合存储切可供集合中所有团队项目使用的 LISTITEM 元素。 GLOBALLIST 是 GLOBALLISTS 元素的必需子元素，以及 ALLOWEDVALUES、SUGGESTEDVALUES 和 PROHIBITEDVALUES 元素的可选子元素。 可以在工作流定义、全局列表定义或全局工作流中定义全局列表。

    <GLOBALLIST name="globalListName">
   <LISTITEM value="Name1" />
   <LISTITEM value="Name2" />
   <LISTITEM value="Name3" />
. . . 
</GLOBALLIST>

    globalListName：包含 1 到 255 个字符的文本字符串。

    重要

    如果在定义工作项类型的 XML 文件中定义全局列表，则必须为该列表指定唯一名称。否则，可能会覆盖为集合定义的现有列表。

  • 使用 LISTITEM 枚举一组值。 LISTITEM 是 GLOBALLIST 的必需子元素，以及 ALLOWEDVALUES、SUGGESTEDVALUES 和 PROHIBITEDVALUES 元素的可选子元素。

    <LISTITEM value="listName" />

    listName：包含 1 到 255 个字符的文本字符串。

允许现有值

在使用 ALLOWEDVALUES 元素指定项的选取列表后，可以使用 ALLOWEXISTINGVALUE 元素允许字段保留现有值。 如果未指定 ALLOWEXISTINGVALUE 元素，则需强制用户在编辑时为字段指定一个当前有效值。 ALLOWEXISTINGVALUE 元素仅修改位于同一个块中的元素。

<ALLOWEXISTINGVALUE />

在 FIELD（工作流）元素中指定此元素以将其应用于为该字段定义的规则。 此应用程序包含字段的 STATE、TRANSITION、DEFAULTREASON 和 REASON 元素指定的规则。 在 STATE 元素下指定此元素，不仅可以将它应用于在该字段的状态中定义的规则，还可应用于为该字段的所有转换到该状态的情况定义的规则。

在 TRANSITION 元素下指定此元素，不仅可以将它应用于在该字段的转换中定义的规则，并且可以应用于在 REASON 和 DEFAULTREASON 元素中为该字段定义的规则。

枚举列表

字段列表由各列表项组成。 每个字段必须至少包含一个项。

备注

全局列表不得包含项目范围的组，因为它们的应用范围未限定为项目。

要在字段列表中指定项，请使用 <LISTITEM value=""> 元素。 可以指定字符串、用户名或组名称。

<LISTITEM value="Emergency"/>
<LISTITEM value="Major"/>
<LISTITEM value="Minor"/>
<LISTITEM value="Domain\joe"/>
<LISTITEM value="[Global]\GlobalGroup" />
<LISTITEM value="[Project]\ProjectGroup" />

备注

在运行时，列表中的项将根据运行 Visual Studio Team Foundation Server 的服务器的语言按字母顺序显示。

枚举一组允许值

在此示例中，“客户严重级别”字段可显示以下三个值中的任何一个值：Emergency（紧急）、Major（主要）和 Minor（次要）。 该字段定义为必需字段，且默认值为“Minor”（次要）。 运行时，用户可从下拉列表中指定其中一个值。

<FIELD refname="System.Title" name="Title" type="String">
<HELPTEXT>Provide a brief description of the work item</HELPTEXT>
<REQUIRED/>
</FIELD>
<FIELD refname="MyCorp.CusSeverity" name="Customer Severity" type="String">
<HELPTEXT>Indicate the severity of the problem</HELPTEXT>
    <ALLOWEDVALUES>
        <LISTITEM value="Emergency">
        <LISTITEM value="Major">
        <LISTITEM value="Minor">
    </ALLOWEDVALUES>
<DEFAULT from="value" value="Minor"/>
</FIELD>

定义依赖选取列表

你可以定义仅在父条件子句为真时才处于活动状态的选取列表。 在下面的示例中，为“My Field”（我的字段）定义了两组选取列表。 运行时，基于是否已将已分配给 MyCompany.MyTeam.Discipline 字段，只会显示一组列表。

备注

此例中的 WHEN 和 WHENNOT 规则也可以应用于其他规则，以指定应在何时计算这些规则。有关详细信息，请参阅分配基于条件的值和规则。

<FIELD name="My Field" refname="MyCompany.MyProcess.MyField" type="String" reportable="dimension">
  <WHEN field="MyCompany.MyTeam.Discipline" value="Requirements"> 
    <ALLOWEDVALUES> 
      <LISTITEM value="Planning" /> 
      <LISTITEM value="Review" /> 
    </ALLOWEDVALUES> 
  </WHEN> 
  <WHENNOT field=" MyCompany.MyTeam.Discipline" value="Requirements"> 
    <ALLOWEDVALUES> 
      <LISTITEM value="Process Management" /> 
      <LISTITEM value="Planning" /> 
      <LISTITEM value="Review" /> 
    </ALLOWEDVALUES> 
  </WHENNOT>
</FIELD>

请参见

其他资源

工作项跟踪：XML 元素定义的索引

定义工作项字段