System.FlagsAttribute 类

方法描述

指示可以将枚举作为位域(即一组标志)处理。

语法定义(C# System.FlagsAttribute 类 的用法)

[SerializableAttribute]
[AttributeUsageAttribute(AttributeTargets.Enum, Inherited = false)]
[ComVisibleAttribute(true)]
public class FlagsAttribute : Attribute

构造函数

构造函数名称 构造函数描述
FlagsAttribute 初始化 FlagsAttribute 类的新实例。

成员/方法

方法名称 方法描述
Equals 基础结构。返回一个值,该值指示此实例是否与指定的对象相等。 (继承自 Attribute。)
Finalize 允许对象在“垃圾回收”回收之前尝试释放资源并执行其他清理操作。 (继承自 Object。)
GetHashCode 返回此实例的哈希代码。 (继承自 Attribute。)
GetType 获取当前实例的 Type。 (继承自 Object。)
IsDefaultAttribute 当在派生类中重写时,指示此实例的值是否是派生类的默认值。 (继承自 Attribute。)
Match 当在派生类中重写时,返回一个指示此实例是否等于指定对象的值。 (继承自 Attribute。)
MemberwiseClone 创建当前 Object 的浅表副本。 (继承自 Object。)
ToString 返回表示当前对象的字符串。 (继承自 Object。)

提示和注释

位域通常用于由可组合出现的元素组成的列表,而枚举常数通常用于由互相排斥的元素组成的列表。 因此,位域设计为通过按位“或”运算组合来生成未命名的值,而枚举常数则不是。 语言在对位域的使用和对枚举常数的使用上不同。

FlagsAttribute 的特性

AttributeUsageAttribute 应用于此类,其 Inherited 属性指定 false。 此特性只能应用于枚举。

用于 FlagsAttribute 和 Enum 的准则

只有要对数值执行按位运算(AND、OR、XOR)时才对枚举使用 FlagsAttribute 自定义特性。

用 2 的幂(即 1、2、4、8 等)定义枚举常量。 这意味着组合的枚举常量中的各个标志都不重叠。

请考虑为常用标志组合创建一个枚举常量。 例如,如果用于文件 I/O 操作的枚举包含枚举常量 Read = 1 和 Write = 2,请考虑创建枚举常量 ReadWrite = Read OR Write,该常量组合了 Read 和 Write 标志。 此外,在某些情况下,可能会将用于组合标志的按位 OR 运算视为一种高级概念,在简单任务中不需要执行此操作。

将负数定义为标志枚举常量时应谨慎,因为很多标志位置都可能设置为 1,这可能使您的代码产生混淆并易于发生代码错误。

测试数值中是否已设置标志的一种简便方法为:在数值和标志枚举常量之间执行按位“与”操作,这种方法会将数值中与标志不对应的所有位都设置为零,然后测试该操作的结果是否等于该标志枚举常量。

将 None 用作值为零的标志枚举常量的名称。 在按位 AND 运算中,不能使用 None 枚举常量测试标志,因为所得的结果始终为零。 但是,您可以在数值与 None 枚举常量之间执行逻辑(不是按位)比较,以确定数值中是否已设置任何位。

如果创建的是值枚举而不是标志枚举,创建 None 枚举常量仍十分有用。 原因是在默认情况下,公共语言运行时会将用于枚举的内存初始化为零。 因此,如果不定义值为零的常量,则枚举在创建时将包含非法值。

如果明显存在应用程序需要表示的默认情况,请考虑使用值为零的枚举常量表示默认值。 如果不存在默认情况,请考虑使用值为零的枚举常量(这意味着该情况不由任何其他枚举常量表示)。

不要仅为了反映枚举自身的状态而定义枚举值。 例如,不要定义仅用于标记枚举末尾的枚举常量。 如果需要确定枚举的最后一个值,请显式检查该值。 此外,如果枚举常量范围中的所有值都有效,还可以对第一个和最后一个枚举常量执行范围检查。

不要指定保留供将来使用的枚举常量。

在定义采用枚举常量作为值的方法或属性时,应考虑对该值进行验证。 原因是即使没有在枚举中定义某个数值,也可以将该数值强制转换为枚举类型。

System.FlagsAttribute 类例子

下面的代码示例阐释了如何使用 FlagsAttribute 特性,并显示了使用 Enum 声明的 FlagsAttribute 在 ToString 方法上的效果。

// Example of the FlagsAttribute attribute.
using System;

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

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

    static void Main( )
    {
        Console.WriteLine( 
            "This example of the FlagsAttribute attribute \n" +
            "generates the following output." );
        Console.WriteLine( 
            "\nAll possible combinations of values of an \n" +
            "Enum without FlagsAttribute:\n" );

        // Display all possible combinations of values.
        for( int val = 0; val <= 8; val++ )
            Console.WriteLine( "{0,3} - {1}", 
                val, ( (SingleHue)val ).ToString( ) );

        Console.WriteLine( 
            "\nAll possible combinations of values of an \n" +
            "Enum with FlagsAttribute:\n" );

        // Display all possible combinations of values.
        // Also display an invalid value.
        for( int val = 0; val <= 8; val++ )
            Console.WriteLine( "{0,3} - {1}", 
                val, ( (MultiHue)val ).ToString( ) );
    } 
} 

/*
This example of the FlagsAttribute attribute
generates the following output.

All possible combinations of values of an
Enum without FlagsAttribute:

  0 - Black
  1 - Red
  2 - Green
  3 - 3
  4 - Blue
  5 - 5
  6 - 6
  7 - 7
  8 - 8

All possible combinations of values of an
Enum with FlagsAttribute:

  0 - Black
  1 - Red
  2 - Green
  3 - Red, Green
  4 - Blue
  5 - Red, Blue
  6 - Green, Blue
  7 - Red, Green, Blue
  8 - 8
*/

继承层次结构

System.Object

System.Attribute

System.FlagsAttribute

命名空间

namespace: System

程序集: mscorlib(在 mscorlib.dll 中)

线程安全

此类型的任何公共 static(在 Visual Basic 中为 Shared) 成员都是线程安全的。但不保证所有实例成员都是线程安全的。

版本信息

.NET Framework 受以下版本支持:4、3.5、3.0、2.0、1.1、1.0 .NET Framework Client Profile 受以下版本支持:4、3.5 SP1 受以下版本支持:

适用平台

Windows 7, Windows Vista SP1 或更高版本, Windows XP SP3, Windows XP SP2 x64 Edition, Windows Server 2008(不支持服务器核心), Windows Server 2008 R2(支持 SP1 或更高版本的服务器核心), Windows Server 2003 SP2 .NET Framework 并不是对每个平台的所有版本都提供支持。有关支持的版本的列表,请参见.NET Framework 系统要求。

相关资源

System 命名空间
MSDN