FlagsAttribute 類別

定義

指出可將列舉視為位元欄位,也就是一組旗標。Indicates that an enumeration can be treated as a bit field; that is, a set of flags.

public ref class FlagsAttribute : Attribute
[System.AttributeUsage(System.AttributeTargets.Enum, Inherited=false)]
public class FlagsAttribute : Attribute
[System.AttributeUsage(System.AttributeTargets.Enum, Inherited=false)]
[System.Serializable]
public class FlagsAttribute : Attribute
[System.AttributeUsage(System.AttributeTargets.Enum, Inherited=false)]
[System.Serializable]
[System.Runtime.InteropServices.ComVisible(true)]
public class FlagsAttribute : Attribute
[<System.AttributeUsage(System.AttributeTargets.Enum, Inherited=false)>]
type FlagsAttribute = class
    inherit Attribute
[<System.AttributeUsage(System.AttributeTargets.Enum, Inherited=false)>]
[<System.Serializable>]
type FlagsAttribute = class
    inherit Attribute
[<System.AttributeUsage(System.AttributeTargets.Enum, Inherited=false)>]
[<System.Serializable>]
[<System.Runtime.InteropServices.ComVisible(true)>]
type FlagsAttribute = class
    inherit Attribute
Public Class FlagsAttribute
Inherits Attribute
繼承
FlagsAttribute
屬性

範例

下列範例說明如何使用 FlagsAttribute 屬性,並顯示在宣告上使用之方法的效果 ToString FlagsAttribute EnumThe following example illustrates the use of the FlagsAttribute attribute and shows the effect on the ToString method of using FlagsAttribute on an Enum declaration.

using namespace System;

// Define an Enum without FlagsAttribute.
public enum class SingleHue : short
{
   None = 0,
   Black = 1,
   Red = 2,
   Green = 4,
   Blue = 8
};

// Define an Enum with FlagsAttribute.
[Flags]
enum class MultiHue : short
{
   None = 0,
   Black = 1,
   Red = 2,
   Green = 4,
   Blue = 8
};

int main()
{
   // Display all possible combinations of values.
   Console::WriteLine(
        "All possible combinations of values without FlagsAttribute:");
   for (int val = 0; val <= 16; val++)
      Console::WriteLine("{0,3} - {1:G}", val, (SingleHue)val);
      
   Console::WriteLine(
        "\nAll possible combinations of values with FlagsAttribute:");
   
   // Display all combinations of values, and invalid values.
   for (int val = 0; val <= 16; val++ )
      Console::WriteLine("{0,3} - {1:G}", val, (MultiHue)val);
}
// The example displays the following output:
//       All possible combinations of values without FlagsAttribute:
//         0 - None
//         1 - Black
//         2 - Red
//         3 - 3
//         4 - Green
//         5 - 5
//         6 - 6
//         7 - 7
//         8 - Blue
//         9 - 9
//        10 - 10
//        11 - 11
//        12 - 12
//        13 - 13
//        14 - 14
//        15 - 15
//        16 - 16
//       
//       All possible combinations of values with FlagsAttribute:
//         0 - None
//         1 - Black
//         2 - Red
//         3 - Black, Red
//         4 - Green
//         5 - Black, Green
//         6 - Red, Green
//         7 - Black, Red, Green
//         8 - Blue
//         9 - Black, Blue
//        10 - Red, Blue
//        11 - Black, Red, Blue
//        12 - Green, Blue
//        13 - Black, Green, Blue
//        14 - Red, Green, Blue
//        15 - Black, Red, Green, Blue
//        16 - 16
using System;

class Example
{
   // Define an Enum without FlagsAttribute.
   enum SingleHue : short
   {
      None = 0,
      Black = 1,
      Red = 2,
      Green = 4,
      Blue = 8
   };

   // Define an Enum with FlagsAttribute.
   [Flags]
   enum MultiHue : short
   {
      None = 0,
      Black = 1,
      Red = 2,
      Green = 4,
      Blue = 8
   };

   static void Main( )
   {
      // Display all possible combinations of values.
      Console.WriteLine(
           "All possible combinations of values without FlagsAttribute:");
      for(int val = 0; val <= 16; val++ )
         Console.WriteLine( "{0,3} - {1:G}", val, (SingleHue)val);

      // Display all combinations of values, and invalid values.
      Console.WriteLine(
           "\nAll possible combinations of values with FlagsAttribute:");
      for( int val = 0; val <= 16; val++ )
         Console.WriteLine( "{0,3} - {1:G}", val, (MultiHue)val);
   }
}
// The example displays the following output:
//       All possible combinations of values without FlagsAttribute:
//         0 - None
//         1 - Black
//         2 - Red
//         3 - 3
//         4 - Green
//         5 - 5
//         6 - 6
//         7 - 7
//         8 - Blue
//         9 - 9
//        10 - 10
//        11 - 11
//        12 - 12
//        13 - 13
//        14 - 14
//        15 - 15
//        16 - 16
//
//       All possible combinations of values with FlagsAttribute:
//         0 - None
//         1 - Black
//         2 - Red
//         3 - Black, Red
//         4 - Green
//         5 - Black, Green
//         6 - Red, Green
//         7 - Black, Red, Green
//         8 - Blue
//         9 - Black, Blue
//        10 - Red, Blue
//        11 - Black, Red, Blue
//        12 - Green, Blue
//        13 - Black, Green, Blue
//        14 - Red, Green, Blue
//        15 - Black, Red, Green, Blue
//        16 - 16
Module Example
   ' Define an Enum without FlagsAttribute.
   Enum SingleHue As Short
      None = 0
      Black = 1
      Red = 2
      Green = 4
      Blue = 8
   End Enum

   ' Define an Enum with FlagsAttribute.
   <Flags()> 
   Enum MultiHue As Short
      None = 0
      Black = 1
      Red = 2
      Green = 4
      Blue = 8
   End Enum

   Sub Main()
      ' Display all possible combinations of values.
      Console.WriteLine(
           "All possible combinations of values without FlagsAttribute:")
      For val As Integer = 0 To 16
         Console.WriteLine("{0,3} - {1:G}", val, CType(val, SingleHue))
     Next 
     Console.WriteLine()
     
     ' Display all combinations of values, and invalid values.
     Console.WriteLine( 
          "All possible combinations of values with FlagsAttribute:")
     For val As Integer = 0 To 16
        Console.WriteLine( "{0,3} - {1:G}", val, CType(val, MultiHue))
     Next 
   End Sub 
End Module 
' The example displays the following output:
'       All possible combinations of values without FlagsAttribute:
'         0 - None
'         1 - Black
'         2 - Red
'         3 - 3
'         4 - Green
'         5 - 5
'         6 - 6
'         7 - 7
'         8 - Blue
'         9 - 9
'        10 - 10
'        11 - 11
'        12 - 12
'        13 - 13
'        14 - 14
'        15 - 15
'        16 - 16
'       
'       All possible combinations of values with FlagsAttribute:
'         0 - None
'         1 - Black
'         2 - Red
'         3 - Black, Red
'         4 - Green
'         5 - Black, Green
'         6 - Red, Green
'         7 - Black, Red, Green
'         8 - Blue
'         9 - Black, Blue
'        10 - Red, Blue
'        11 - Black, Red, Blue
'        12 - Green, Blue
'        13 - Black, Green, Blue
'        14 - Red, Green, Blue
'        15 - Black, Red, Green, Blue
'        16 - 16

上述範例會定義兩個色彩相關列舉 SingleHueMultiHueThe preceding example defines two color-related enumerations, SingleHue and MultiHue. 後者具有屬性, FlagsAttribute 前者則否。The latter has the FlagsAttribute attribute; the former does not. 此範例顯示當整數範圍(包括不代表列舉型別之基礎值的整數)轉換成列舉型別及其顯示其字串標記法時的行為差異。The example shows the difference in behavior when a range of integers, including integers that do not represent underlying values of the enumeration type, are cast to the enumeration type and their string representations displayed. 例如,請注意,3不能表示為 SingleHue 值,因為3不是任何成員的基礎值 SingleHue ,而屬性則可以將 FlagsAttribute 3 表示為的 MultiHueBlack, RedFor example, note that 3 cannot be represented as a SingleHue value because 3 is not the underlying value of any SingleHue member, whereas the FlagsAttribute attribute makes it possible to represent 3 as a MultiHue value of Black, Red.

下列範例會定義另一個具有屬性的列舉 FlagsAttribute ,並示範如何使用位邏輯和等號比較運算子來判斷是否在列舉值中設定一個或多個位欄位。The following example defines another enumeration with the FlagsAttribute attribute and shows how to use bitwise logical and equality operators to determine whether one or more bit fields are set in an enumeration value. 您也可以使用 Enum.HasFlag 方法來執行這項作業,但這不會顯示在此範例中。You can also use the Enum.HasFlag method to do that, but that is not shown in this example.

using namespace System;

[Flags]
enum class PhoneService
{
   None = 0,
   LandLine = 1,
   Cell = 2,
   Fax = 4,
   Internet = 8,
   Other = 16
};

void main()
{
   // Define three variables representing the types of phone service
   // in three households.
   PhoneService household1 = PhoneService::LandLine | PhoneService::Cell |
                             PhoneService::Internet;
   PhoneService household2 = PhoneService::None;
   PhoneService household3 = PhoneService::Cell | PhoneService::Internet;

   // Store the variables in an array for ease of access.
   array<PhoneService>^ households = { household1, household2, household3 };

   // Which households have no service?
   for (int ctr = 0; ctr < households->Length; ctr++)
      Console::WriteLine("Household {0} has phone service: {1}",
                         ctr + 1,
                         households[ctr] == PhoneService::None ?
                             "No" : "Yes");
   Console::WriteLine();

   // Which households have cell phone service?
   for (int ctr = 0; ctr < households->Length; ctr++)
      Console::WriteLine("Household {0} has cell phone service: {1}",
                         ctr + 1,
                         (households[ctr] & PhoneService::Cell) == PhoneService::Cell ?
                            "Yes" : "No");
   Console::WriteLine();

   // Which households have cell phones and land lines?
   PhoneService cellAndLand = PhoneService::Cell | PhoneService::LandLine;
   for (int ctr = 0; ctr < households->Length; ctr++)
      Console::WriteLine("Household {0} has cell and land line service: {1}",
                         ctr + 1,
                         (households[ctr] & cellAndLand) == cellAndLand ?
                            "Yes" : "No");
   Console::WriteLine();

   // List all types of service of each household?//
   for (int ctr = 0; ctr < households->Length; ctr++)
      Console::WriteLine("Household {0} has: {1:G}",
                         ctr + 1, households[ctr]);
   Console::WriteLine();
}
// The example displays the following output:
//    Household 1 has phone service: Yes
//    Household 2 has phone service: No
//    Household 3 has phone service: Yes
//
//    Household 1 has cell phone service: Yes
//    Household 2 has cell phone service: No
//    Household 3 has cell phone service: Yes
//
//    Household 1 has cell and land line service: Yes
//    Household 2 has cell and land line service: No
//    Household 3 has cell and land line service: No
//
//    Household 1 has: LandLine, Cell, Internet
//    Household 2 has: None
//    Household 3 has: Cell, Internet
using System;

[Flags]
public enum PhoneService
{
   None = 0,
   LandLine = 1,
   Cell = 2,
   Fax = 4,
   Internet = 8,
   Other = 16
}

public class Example
{
   public static void Main()
   {
      // Define three variables representing the types of phone service
      // in three households.
      var household1 = PhoneService.LandLine | PhoneService.Cell |
                       PhoneService.Internet;
      var household2 = PhoneService.None;
      var household3 = PhoneService.Cell | PhoneService.Internet;

      // Store the variables in an array for ease of access.
      PhoneService[] households = { household1, household2, household3 };

      // Which households have no service?
      for (int ctr = 0; ctr < households.Length; ctr++)
         Console.WriteLine("Household {0} has phone service: {1}",
                           ctr + 1,
                           households[ctr] == PhoneService.None ?
                               "No" : "Yes");
      Console.WriteLine();

      // Which households have cell phone service?
      for (int ctr = 0; ctr < households.Length; ctr++)
         Console.WriteLine("Household {0} has cell phone service: {1}",
                           ctr + 1,
                           (households[ctr] & PhoneService.Cell) == PhoneService.Cell ?
                              "Yes" : "No");
      Console.WriteLine();

      // Which households have cell phones and land lines?
      var cellAndLand = PhoneService.Cell | PhoneService.LandLine;
      for (int ctr = 0; ctr < households.Length; ctr++)
         Console.WriteLine("Household {0} has cell and land line service: {1}",
                           ctr + 1,
                           (households[ctr] & cellAndLand) == cellAndLand ?
                              "Yes" : "No");
      Console.WriteLine();

      // List all types of service of each household?//
      for (int ctr = 0; ctr < households.Length; ctr++)
         Console.WriteLine("Household {0} has: {1:G}",
                           ctr + 1, households[ctr]);
      Console.WriteLine();
   }
}
// The example displays the following output:
//    Household 1 has phone service: Yes
//    Household 2 has phone service: No
//    Household 3 has phone service: Yes
//
//    Household 1 has cell phone service: Yes
//    Household 2 has cell phone service: No
//    Household 3 has cell phone service: Yes
//
//    Household 1 has cell and land line service: Yes
//    Household 2 has cell and land line service: No
//    Household 3 has cell and land line service: No
//
//    Household 1 has: LandLine, Cell, Internet
//    Household 2 has: None
//    Household 3 has: Cell, Internet
<Flags()>
Public Enum PhoneService As Integer
   None = 0
   LandLine = 1
   Cell = 2
   Fax = 4
   Internet = 8
   Other = 16
End Enum

Module Example
   Public Sub Main()
      ' Define three variables representing the types of phone service
      ' in three households.
      Dim household1 As PhoneService = PhoneService.LandLine Or
                                       PhoneService.Cell Or
                                       PhoneService.Internet
      Dim household2 As PhoneService = PhoneService.None
      Dim household3 As PhoneService = PhoneService.Cell Or
                                       PhoneService.Internet

      ' Store the variables in an array for ease of access.
      Dim households() As PhoneService = { household1, household2,
                                           household3 }

      ' Which households have no service?
      For ctr As Integer = 0 To households.Length - 1
         Console.WriteLine("Household {0} has phone service: {1}",
                           ctr + 1,
                           If(households(ctr) = PhoneService.None,
                              "No", "Yes"))
      Next
      Console.WriteLine()
      
      ' Which households have cell phone service?
      For ctr As Integer = 0 To households.Length - 1
         Console.WriteLine("Household {0} has cell phone service: {1}",
                           ctr + 1,
                           If((households(ctr) And PhoneService.Cell) = PhoneService.Cell,
                              "Yes", "No"))
      Next
      Console.WriteLine()
      
      ' Which households have cell phones and land lines?
      Dim cellAndLand As PhoneService = PhoneService.Cell Or PhoneService.LandLine
      For ctr As Integer = 0 To households.Length - 1
         Console.WriteLine("Household {0} has cell and land line service: {1}",
                           ctr + 1,
                           If((households(ctr) And cellAndLand) = cellAndLand,
                              "Yes", "No"))
      Next
      Console.WriteLine()
      
      ' List all types of service of each household?'
      For ctr As Integer = 0 To households.Length - 1
         Console.WriteLine("Household {0} has: {1:G}",
                           ctr + 1, households(ctr))
      Next
      Console.WriteLine()
   End Sub
End Module
' The example displays the following output:
'    Household 1 has phone service: Yes
'    Household 2 has phone service: No
'    Household 3 has phone service: Yes
'
'    Household 1 has cell phone service: Yes
'    Household 2 has cell phone service: No
'    Household 3 has cell phone service: Yes
'
'    Household 1 has cell and land line service: Yes
'    Household 2 has cell and land line service: No
'    Household 3 has cell and land line service: No
'
'    Household 1 has: LandLine, Cell, Internet
'    Household 2 has: None
'    Household 3 has: Cell, Internet

備註

位欄位通常用於可能會合並的元素清單,而列舉常數通常用於互斥專案的清單。Bit fields are generally used for lists of elements that might occur in combination, whereas enumeration constants are generally used for lists of mutually exclusive elements. 因此,位欄位是設計成要與位 OR 運算結合以產生未命名的值,而列舉的常數則不是。Therefore, bit fields are designed to be combined with a bitwise OR operation to generate unnamed values, whereas enumerated constants are not. 相較于列舉常數,語言與位欄位的使用方式不同。Languages vary in their use of bit fields compared to enumeration constants.

FlagsAttribute 的屬性Attributes of the FlagsAttribute

AttributeUsageAttribute 會套用至這個類別,而其 Inherited 屬性會指定 falseAttributeUsageAttribute is applied to this class, and its Inherited property specifies false. 這個屬性只能套用至列舉。This attribute can only be applied to enumerations.

FlagsAttribute 和 Enum 的指導方針Guidelines for FlagsAttribute and Enum

  • FlagsAttribute只有當位運算 (and、or、EXCLUSIVE 或) 是在數值上執行時,才使用自訂屬性做為列舉。Use the FlagsAttribute custom attribute for an enumeration only if a bitwise operation (AND, OR, EXCLUSIVE OR) is to be performed on a numeric value.

  • 將列舉常數定義為2的乘冪,也就是1、2、4、8等等。Define enumeration constants in powers of two, that is, 1, 2, 4, 8, and so on. 這表示結合的列舉常數中的個別旗標不會重迭。This means the individual flags in combined enumeration constants do not overlap.

  • 請考慮建立常用旗標組合的列舉常數。Consider creating an enumerated constant for commonly used flag combinations. 例如,如果您有一個用於包含列舉常數和之檔案 i/o 作業的列舉 Read = 1 Write = 2 ,請考慮建立列舉常數 ReadWrite = Read OR Write ,其中結合了 ReadWrite 旗標。For example, if you have an enumeration used for file I/O operations that contains the enumerated constants Read = 1 and Write = 2, consider creating the enumerated constant ReadWrite = Read OR Write, which combines the Read and Write flags. 此外,在某些情況下,用來結合旗標的位 OR 運算可能會被視為一種簡單的概念。In addition, the bitwise OR operation used to combine the flags might be considered an advanced concept in some circumstances that should not be required for simple tasks.

  • 如果您定義負數作為旗標列舉常數,因為有許多旗標位置可能設定為1,這可能會讓您的程式碼變得令人困惑,並鼓勵程式碼錯誤,請務必謹慎使用。Use caution if you define a negative number as a flag enumerated constant because many flag positions might be set to 1, which might make your code confusing and encourage coding errors.

  • 測試旗標是否設定在數值中的方便方式,是在數值和旗標列舉常數之間執行位 AND 運算,將數值中的所有位設定為零,而不會對應至旗標,然後測試該運算的結果是否等於旗標列舉常數。A convenient way to test whether a flag is set in a numeric value is to perform a bitwise AND operation between the numeric value and the flag enumerated constant, which sets all bits in the numeric value to zero that do not correspond to the flag, then test whether the result of that operation is equal to the flag enumerated constant.

  • 用作 None 值為零之旗標列舉常數的名稱。Use None as the name of the flag enumerated constant whose value is zero. 您無法使用 None 位 and 運算中的列舉常數來測試旗標,因為結果一律為零。You cannot use the None enumerated constant in a bitwise AND operation to test for a flag because the result is always zero. 不過,您可以在數值和列舉常數之間執行邏輯(而非位比較), None 以判斷是否已設定數值中的任何位。However, you can perform a logical, not a bitwise, comparison between the numeric value and the None enumerated constant to determine whether any bits in the numeric value are set.

    如果您建立一個值列舉,而不是旗標列舉,則建立列舉常數仍然是值得的 NoneIf you create a value enumeration instead of a flags enumeration, it is still worthwhile to create a None enumerated constant. 原因是,通用語言執行時間預設會將用於列舉的記憶體初始化為零。The reason is that by default the memory used for the enumeration is initialized to zero by the common language runtime. 因此,如果您未定義其值為零的常數,則在建立時,列舉會包含不合法的值。Consequently, if you do not define a constant whose value is zero, the enumeration will contain an illegal value when it is created.

    如果您的應用程式有明顯的預設情況,您的應用程式需要表示,請考慮使用其值為零的列舉常數來表示預設值。If there is an obvious default case your application needs to represent, consider using an enumerated constant whose value is zero to represent the default. 如果沒有預設案例,請考慮使用值為零的列舉常數,表示不是任何其他列舉常數所表示的大小寫。If there is no default case, consider using an enumerated constant whose value is zero that means the case that is not represented by any of the other enumerated constants.

  • 請勿只定義列舉值來鏡像列舉本身的狀態。Do not define an enumeration value solely to mirror the state of the enumeration itself. 例如,請勿定義只標示列舉結尾的列舉常數。For example, do not define an enumerated constant that merely marks the end of the enumeration. 如果您需要判斷列舉的最後一個值,請明確檢查該值。If you need to determine the last value of the enumeration, check for that value explicitly. 此外,如果範圍內的所有值都有效,您可以針對第一個和最後一個列舉的常數執行範圍檢查。In addition, you can perform a range check for the first and last enumerated constant if all values within the range are valid.

  • 請勿指定保留給未來使用的列舉常數。Do not specify enumerated constants that are reserved for future use.

  • 當您定義採用列舉常數作為值的方法或屬性時,請考慮驗證值。When you define a method or property that takes an enumerated constant as a value, consider validating the value. 原因是,您可以將數值轉換成列舉型別,即使該數值未在列舉中定義。The reason is that you can cast a numeric value to the enumeration type even if that numeric value is not defined in the enumeration.

建構函式

FlagsAttribute()

初始化 FlagsAttribute 類別的新執行個體。Initializes a new instance of the FlagsAttribute class.

屬性

TypeId

在衍生類別中實作時,取得這個 Attribute 的唯一識別碼。When implemented in a derived class, gets a unique identifier for this Attribute.

(繼承來源 Attribute)

方法

Equals(Object)

傳回值,這個值指出此執行個體是否與指定的物件相等。Returns a value that indicates whether this instance is equal to a specified object.

(繼承來源 Attribute)
GetHashCode()

傳回這個執行個體的雜湊碼。Returns the hash code for this instance.

(繼承來源 Attribute)
GetType()

取得目前執行個體的 TypeGets the Type of the current instance.

(繼承來源 Object)
IsDefaultAttribute()

在衍生類別中覆寫時,表示這個執行個體的值是衍生類別的預設值。When overridden in a derived class, indicates whether the value of this instance is the default value for the derived class.

(繼承來源 Attribute)
Match(Object)

在衍生類別中覆寫時,會傳回值,表示這個執行個體是否等於指定物件。When overridden in a derived class, returns a value that indicates whether this instance equals a specified object.

(繼承來源 Attribute)
MemberwiseClone()

建立目前 Object 的淺層複製。Creates a shallow copy of the current Object.

(繼承來源 Object)
ToString()

傳回代表目前物件的字串。Returns a string that represents the current object.

(繼承來源 Object)

明確介面實作

_Attribute.GetIDsOfNames(Guid, IntPtr, UInt32, UInt32, IntPtr)

將一組名稱對應至一組對應的分派識別項 (Dispatch Identifier)。Maps a set of names to a corresponding set of dispatch identifiers.

(繼承來源 Attribute)
_Attribute.GetTypeInfo(UInt32, UInt32, IntPtr)

擷取物件的類型資訊,可以用來取得介面的類型資訊。Retrieves the type information for an object, which can be used to get the type information for an interface.

(繼承來源 Attribute)
_Attribute.GetTypeInfoCount(UInt32)

擷取物件提供的類型資訊介面數目 (0 或 1)。Retrieves the number of type information interfaces that an object provides (either 0 or 1).

(繼承來源 Attribute)
_Attribute.Invoke(UInt32, Guid, UInt32, Int16, IntPtr, IntPtr, IntPtr, IntPtr)

提供物件所公開的屬性和方法的存取權。Provides access to properties and methods exposed by an object.

(繼承來源 Attribute)

適用於