定義挑選清單

發行項
03/12/2013

您可以在欄位定義中或是在工作流程期間某個時間點定義挑選清單，藉此列舉欄位的一組值。您可以指定清單只包含允許值、不可包含禁用值，或可包含建議值。如果是建議值，使用者就可以指定不在挑選清單中的值。

您也可以定義相依挑選清單，為欄位定義兩個以上的清單，但在執行階段依據條件式規則的評估結果只顯示一個清單。

本主題內容

列舉挑選清單的語法結構
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 個字元之間的文字字串所組成。模式值：^[^\\]+\\[^\\]+$ 模式值範例：Domain\UserID
not	選擇項。指定不適用規則之 Team Foundation 使用者或群組的名稱。有效名稱由介於 1 到 255 個字元之間的文字字串所組成。模式值：^[^\\]+\\[^\\]+$ 模式值範例：Domain\UserID
expanditems	選擇項。指定是否應該將 LISTITEM 項目所識別的群組擴展成包括清單中的附屬群組。預設值是 true。
filteritems	選擇項。指定清單只會包含群組的成員，不會包含群組名稱。這個屬性的唯一有效值是 excludegroups。

如需詳細資訊，請參閱定義使用者清單、挑選清單和全域清單。

回到頁首

GLOBALLIST 和 LISTITEM 項目的語法結構

您可以使用 GLOBALLIST 和 LISTITEM 項目，列舉可全域更新或單一欄位專有的項目清單。

GLOBALLIST 用來定義一組為 Team 專案集合所儲存且可供該集合中所有 Team 專案使用的 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 之伺服器的語言，依字母順序顯示。

回到頁首

列舉一組允許值

在這個範例中，Customer Severity 欄位的值可以是下列三個值的任何一個：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>

回到頁首