定義挑選清單

  • 發行項

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

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

本主題內容

  • 語法結構

  • 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 會定義兩組挑選清單。 執行階段期間會根據 MyCompany.MyTeam.Discipline 欄位有無獲指派 Requirements 而只顯示一個清單。

注意事項注意事項

這個範例中的 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 項目定義的索引

修改或加入欄位以支援查詢、報表和工作流程