通过

All FIELD XML 元素引用

  • 项目

本主题中的信息可用作定义工作项类型的数据字段的所有元素和主要特性的快速参考。在 FIELD（定义）元素容器中指定这些元素。通过在 FIELDS（定义）元素中指定 FIELD（定义）元素，可以添加工作项类型的字段。可以在工作项类型定义中或作为全局工作流的一部分指定这些元素。可以创建本主题描述的子元素来指定字段的行为、定义默认值或定义值的选取列表。可以将各个字段规则元素相互组合使用。可将大多数规则的范围限定为适用于一个或多个用户或组，或被一个或多个用户或组忽略。

FIELD 元素的所有子元素均为可选项。除 HELPTEXT 元素，可以将所有元素指定为 FIELD (定义)，FIELD (工作流) 和 FIELD (全局工作流) 元素的子元素。使用 FIELD（定义）元素，可以定义工作项字段和指定应用于它的规则和条件。可以为 FIELD（工作流）元素指定规则，以便当工作项从一个状态转换为另一个状态时定义字段的值或应用规则。可以基于其父 FIELDS 元素是子元素的 STATE、TRANSITION、DEFAULTREASON 或 REASON 元素指定字段规则。有关更多信息，请参见使用工作项字段和设计工作流。

主题内容

  • FIELD（定义）容器元素

  • FIELD 子元素

  • GLOBALLIST 和 LISTITEM 子元素

  • FIELD 子元素指定的特性

FIELD（定义）容器元素

使用以下语法可以定义工作项类型的数据字段。此示例演示 FIELD（定义）元素和所有可选子元素的格式。有关更多信息，请参见FIELD（定义）元素。

<FIELD name="fieldDisplayName" refname="fieldReferenceName" type="String | Integer | Double | DateTime | PlainText | HTML | History | TreePath | GUID "
syncnamechanges="true | false" reportingname="reportingDisplayName" reportingrefname="reportingReferenceName"
reportable="Dimension | Detail | Measure" formula="avg" >
   <ALLOWEDVALUES> . . . </ALLOWEDVALUES>
   <ALLOWEXISTINGVALUE />
   <CANNOTLOSEVALUE />
   <COPY />
   <DEFAULT />
   <EMPTY />
   <FROZEN />
   <HELPTEXT> . . . </HELPTEXT>
   <MATCH />
   <NOTSAMEAS />
   <PROHIBITEDVALUES /> . . . </PROHIBITEDVALUES>
   <READONLY />
   <REQUIRED />
   <SERVERDEFAULT />
   <SUGGESTEDVALUES /> . . . </SUGGESTEDVALUES>
   <VALIDUSER />
   <WHEN>> . . . </WHEN>
   <WHENNOT> . . . </WHENNOT>
   <WHENCHANGED> . . . </WHENCHANGED>
   <WHENNOTCHANGED> . . . </WHENNOTCHANGED>
</FIELD>

FIELD 子元素

下表描述可以指定以便为向字段分配值而应用规则的子元素。所有子元素均为可选项。可以限制大多数子元素的范围，以便仅应用于某个组或除某个组中的用户外的所有人。

元素

说明和语法

ALLOWEDVALUES

定义用户可以在工作项窗体上和查询编辑器中的字段列表中指定的值列表。用户必须指定所列值之一。

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

有关更多信息，请参见定义选取列表。

ALLOWEXISTINGVALUE

指定字段可以保留现有值，即使该值不再处于选取列表中。所有新的字段值均须处于该列表中。

<ALLOWEXISTINGVALUE />

有关更多信息，请参见定义选取列表。

CANNOTLOSEVALUE

指定在指定值后用户将无法清除字段的所有值。字段包含值后，该字段必须始终包含非 NULL 值。

<CANNOTLOSEVALUE for="userGroupName" not="userGroupName" />

有关更多信息，请参见对工作项字段设置条件。

COPY

在用户创建或修改工作项时将指定的值复制到字段。

<COPY for="userGroupName" not="userGroupName"  
from="value | field | clock | currentuser" 
value="valueToCopy" field="fieldReferenceName" />

有关更多信息，请参见定义默认值或将值复制到字段。

DEFAULT

在用户创建或修改工作项时为空字段指定值。如果字段已具有值，则忽略默认规则。

<DEFAULT for="userGroupName" not="userGroupName" 
from="value | field | clock | currentuser" 
value="value to copy" field="field reference name" />

有关更多信息，请参见定义默认值或将值复制到字段。

EMPTY

清除字段包含的任何值。EMPTY 规则还会使字段变为只读，并且不应与 READONLY 规则一起使用。

用户保存工作项时字段值将被清除，并且您无法指定任何值。此规则主要在状态转换期间用来清除应用于项转换到的状态的字段。

<EMPTY for="userGroupName" not=" userGroupName" />

有关更多信息，请参见对工作项字段设置条件。

FROZEN

指定在提交更改后，您无法将字段更改为非空值。一旦用户用该字段中的值保存工作项，该值即不能再修改。

<FROZEN for="userGroupName" not="userGroupName" />

有关更多信息，请参见对工作项字段设置条件。

HELPTEXT

定义要在用户将鼠标指针指向工作项窗体中的字段时显示的文本。

tooltipText：包含 1 至 255 个字符的文本字符串。

<HELPTEXT>tooltipText </HELPTEXT>

有关更多信息，请参见定义工作项字段的帮助文本。

MATCH

定义 String 类型的字段的值必须匹配的模式

<MATCH pattern="patternValue" for="userGroupName" not="userGroupName" />

有关更多信息，请参见使字符串字段与模式匹配。

NOTSAMEAS

指定字段未赋值和另一个指定字段分配的值相同。field 特性的值必须为有效的字段引用名称。

<NOTSAMEAS field="fieldReferenceName" for="userGroupName" not="userGroupName" />

有关更多信息，请参见对工作项字段设置条件。

PROHIBITEDVALUES

定义字段不能包含的值列表。如果字段包含禁止值，则用户无法保存工作项。

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

有关更多信息，请参见定义选取列表。

READONLY

指定不能修改字段分配的值。

<READONLY for="userGroupName" not="userGroupName" />
说明说明
使用 EMPTY 元素时不要使用此元素，因为 EMPTY 也会使字段变为只读。如果组合使用这些元素，会导致不一致。

有关更多信息，请参见对工作项字段设置条件。

REQUIRED

指定用户必须为字段指定值。必填字段不能为空。在用户向所有必需字段分配值之前，他们无法保存工作项。

<REQUIRED for="userGroupName" not="userGroupName" />

有关更多信息，请参见对工作项字段设置条件。

SERVERDEFAULT

在用户保存工作项时将指定的服务器值复制到字段。这些字段通常在窗体中以只读形式显示。

<SERVERDEFAULT for="userGroupName" not="userGroupName" 
from="clock | currentuser" />

有关更多信息，请参见定义默认值或将值复制到字段。

SUGGESTEDVALUES

定义用户可以在工作项窗体上和查询编辑器中的字段列表中指定的建议值列表。用户可以指定与推荐值不同的值。

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

有关更多信息，请参见定义选取列表。

VALIDUSER

限制属于所指定组的用户修改工作项。默认组为“Team Foundation Valid Users”组。

所有特性都是可选的。所有特性都必须是包含 1 至 255 个字符的文本字符串。可以使用标记指定组。有关更多信息，请参见用标记引用用户和组。

< VALIDUSER group="groupName" for="userName" not="userName" />

有关更多信息，请参见管理创建或修改工作项的权限。

WHEN

指定在另一个字段具有特定值时要应用于当前字段的一个或多个规则。父 FIELD 元素用于定义当前字段。

<WHEN field="fieldReferenceName" value="value">
    <ALLOWEDVALUES> . . . </ALLOWEDVALUES>
    <ALLOWEXISTINGVALUE> . . . <ALLOWEXISTINGVALUE>
    <CANNOTLOSEVALUE> . . . </CANNOTLOSEVALUE>
    <COPY> . . . </COPY>
    <DEFAULT> . . . </DEFAULT>
    <EMPTY> . . . </EMPTY>
    <FROZEN> . . . </FROZEN>
    <MATCH> . . . </MATCH>
    <NOTSAMEAS> . . . </NOTSAMEAS>
    <PROHIBITEDVALUES> . . . </PROHIBITEDVALUES>
    <READONLY> . . . </READONLY>
    <REQUIRED> . . . </REQUIRED>
    <SERVERDEFAULT> . . . </SERVERDEFAULT>        
    <SUGGESTEDVALUES> . . . </SUGGESTEDVALUES>
    <VALIDUSER> . . . </VALIDUSER>
</WHEN>

有关更多信息，请参阅分配基于条件的值和规则。

WHENNOT

指定在另一个字段没有特定值时要应用于当前字段的一个或多个规则。父 FIELD 元素用于定义当前字段。

<WHENNOT field="fieldReferenceName" value="value">
    <ALLOWEDVALUES> . . . </ALLOWEDVALUES>
    <ALLOWEXISTINGVALUE> . . . <ALLOWEXISTINGVALUE>
    <CANNOTLOSEVALUE> . . . </CANNOTLOSEVALUE>
    <COPY> . . . </COPY>
    <DEFAULT> . . . </DEFAULT>
    <EMPTY> . . . </EMPTY>
    <FROZEN> . . . </FROZEN>
    <MATCH> . . . </MATCH>
    <NOTSAMEAS> . . . </NOTSAMEAS>
    <PROHIBITEDVALUES> . . . </PROHIBITEDVALUES>
    <READONLY> . . . </READONLY>
    <REQUIRED> . . . </REQUIRED>
    <SERVERDEFAULT> . . . </SERVERDEFAULT>        
    <SUGGESTEDVALUES> . . . </SUGGESTEDVALUES>
    <VALIDUSER> . . . </VALIDUSER>
</WHENNOT>

有关更多信息，请参见分配基于条件的值和规则。

WHENCHANGED

指定当在工作项修订过程中更改另一个字段时要应用于当前字段的一个或多个规则。父 FIELD 元素用于定义当前字段。

<WHENCHANGED field="fieldReferenceName" >
    <ALLOWEDVALUES> . . . </ALLOWEDVALUES>
    <ALLOWEXISTINGVALUE> . . . <ALLOWEXISTINGVALUE>
    <CANNOTLOSEVALUE> . . . </CANNOTLOSEVALUE>
    <COPY> . . . </COPY>
    <DEFAULT> . . . </DEFAULT>
    <EMPTY> . . . </EMPTY>
    <FROZEN> . . . </FROZEN>
    <MATCH> . . . </MATCH>
    <NOTSAMEAS> . . . </NOTSAMEAS>
    <PROHIBITEDVALUES> . . . </PROHIBITEDVALUES>
    <READONLY> . . . </READONLY>
    <REQUIRED> . . . </REQUIRED>
    <SERVERDEFAULT> . . . </SERVERDEFAULT>        
    <SUGGESTEDVALUES> . . . </SUGGESTEDVALUES>
    <VALIDUSER> . . . </VALIDUSER>      
</WHENCHANGED>

有关更多信息，请参见分配基于条件的值和规则。

WHENNOTCHANGED

指定当在工作项修订过程中另一个字段不变时要应用于当前字段的一个或多个规则。父元素用于定义当前字段。

<WHENNOTCHANGED field="fieldReferenceName">
    <ALLOWEDVALUES> . . . </ALLOWEDVALUES>
    <ALLOWEXISTINGVALUE> . . . <ALLOWEXISTINGVALUE>
    <CANNOTLOSEVALUE> . . . </CANNOTLOSEVALUE>
    <COPY> . . . </COPY>
    <DEFAULT> . . . </DEFAULT>
    <EMPTY> . . . </EMPTY>
    <FROZEN> . . . </FROZEN>
    <MATCH> . . . </MATCH>
    <NOTSAMEAS> . . . </NOTSAMEAS>
    <PROHIBITEDVALUES> . . . </PROHIBITEDVALUES>
    <READONLY> . . . </READONLY>
    <REQUIRED> . . . </REQUIRED>
    <SERVERDEFAULT> . . . </SERVERDEFAULT>        
    <SUGGESTEDVALUES> . . . </SUGGESTEDVALUES>
    <VALIDUSER> . . . </VALIDUSER>
</WHENNOTCHANGED>

有关更多信息，请参见分配基于条件的值和规则。

GLOBALLIST 和 LISTITEM 子元素

下表对 GLOBALLIST 和 LISTITEM 元素进行了说明。将这些元素指定为 ALLOWEDVALUES、SUGGESTEDVALUES 和 PROHIBITEDVALUES 元素的子元素。可以使用这些元素来枚举值的列表，该列表显示为用户可以指定的项的选取列表或下拉菜单。有关更多信息，请参见定义用户列表、选取列表和全局列表。

元素

语法

描述

GLOBALIST

 
<GLOBALLIST name="globalListName
">
    <LISTITEM> . . . </LISTITEM>
</GLOBALLIST>

定义一组为团队项目集合存储的并可由集合中的所有团队项目使用的 LISTITEM 元素。

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

GLOBALLIST 是 GLOBALLISTS 元素的必需子元素，并且是 ALLOWEDVALUES、SUGGESTEDVALUES 和 PROHIBITEDVALUES 元素的可选子元素。可以在工作项定义、全局列表定义或全局工作流中定义全局列表。

LISTITEM

 
<LISTITEM value="listName" />

定义一个有效列表值。

LISTITEM 是 GLOBALLIST 的必需子元素，并且是 ALLOWEDVALUES、SUGGESTEDVALUES 和 PROHIBITEDVALUES 元素的可选子元素。

返回页首

FIELD 子元素指定的特性

可以通过包含 for 或 not 特性，将大多数 FIELD 规则限定为是应用还是不应用于组或用户集。有关更多信息，请参见将字段规则的应用范围限定为某个组。

特性

语法

描述

expanditems

expanditems="true | false"

可选。指定 LISTITEM 元素标识的组是否应扩展在列表中包含从属组。此特性的默认值为 true。

filteritems

filteritems="excludegroups"

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

for

for="userGroupName"

可选。指定 Team Foundation 中应用规则的用户或组的名称。有效值是包含 1 至 255 个字符的文本字符串。

not

not="userGroupName"

可选。指定 Team Foundation 中不应用规则的用户或组的名称。有效值是包含 1 至 255 个字符的文本字符串。

from

from="value | field | clock | currentuser"

必需。指定要从中复制值或指定默认值的值的来源。以下为有效值：

  • clock:复制当前日期和时间从系统时钟到 datetime 字段。不需要其他特性。对于 COPY 和 DEFAULT 规则，此值来自本地计算机的时钟时间。对于 SERVERDEFAULT，该值来自用户保存工作项时的服务器时钟。

  • currentuser:复制当前登录用户的名称。使用当前用户的短用户名作为值。不需要其他特性。用于字符串字段。

  • field：复制所指定 field 特性的值。需要 field="abc" 特性。默认情况下，如果指定的“from”字段为空，则不执行任何操作。field 特性只用于 <COPY> 和 <DEFAULT> 规则。

  • value：复制所指定 value 特性的值。使用所指定字符串常量的值。需要一个 value="abc" 特性。value 仅用于 <COPY> 和 <DEFAULT> 规则。

如果指定“value”或“field”，还必须分别包括值或字段特性。

field

field="fieldReferenceName"

可选。为 from 特性指定 field 时，指定其值要复制到字段中的字段名称。

pattern

pattern= "patternValue”

必需。仅强制对字符串进行基本模式匹配。patternValue 是包含 1 至 255 个字符之间的字符串，包含。该字符串不能包含反斜杠字符 (\)。除非它是下列六个元字符之一，字符串的每个字符被解释为文本：

  • “A”或“a”表示单个字母字符。

  • “N”或“n”表示单个数字字符。

  • “X”或“x”表示单个字母数字字符。

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

例如，pattern="xxxxx.nn.nn" 匹配所有五个字母数字字符，然后期间，则两个数字字符，然后期间，则两个数字字符。

value

value="valueToCopy"

可选。为 from 特性指定 value 时，指定要复制到字段中的值。

返回页首

请参见

概念

定义用户列表、选取列表和全局列表

使用工作项字段

设计工作流