定义选取列表

项目
08/12/2011

更新：2011 年 1 月

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

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

主题内容

枚举选取列表的语法结构
GLOBALLIST 和 LISTITEM 元素的语法结构
允许现有值
枚举一组允许值
定义相关选取列表

枚举选取列表的语法结构

可以使用 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 个字符的文本字符串。

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

返回页首

允许现有值

在使用 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>

返回页首

定义相关选取列表

您可以定义仅在父条件子句为 true 时才处于活动状态的选取列表。在下面的示例中，为“My Field”（我的字段）定义了两组选取列表。在运行时，根据是否已将“Requirements”（要求）指派给 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 元素定义的索引

自定义全局工作流

定义工作项字段

修订记录

日期	修订记录	原因
2011 年 1 月	增加了语法结构和更多示例。	信息补充。

2011 年 1 月

增加了语法结构和更多示例。

信息补充。