Enum 陳述式 (Visual Basic)

發行項
05/22/2023

宣告列舉，並定義其成員的值。

語法

[ <attributelist> ] [ accessmodifier ]  [ Shadows ]
Enum enumerationname [ As datatype ]
   memberlist
End Enum

組件

attributelist

選擇性。套用至此列舉的屬性清單。您必須將屬性清單放在角括弧中 ("<" 和 ">")。

FlagsAttribute 屬性代表列舉執行個體的值可已包含多個列舉成員，且每個成員都代表列舉值中的位元欄位。
accessmodifier

選擇性。指定哪些程式碼可以存取此列舉。可以是下列其中一項：
Shadows

選擇性。指定這個列舉會在基底類別中重新宣告並隱藏相同名稱的程式設計元素，或一組多載元素。您只能在列舉本身上指定 Shadows，而不是在其任何成員上。
enumerationname

必要。列舉的名稱。如需有效名稱的詳細資訊，請參閱宣告的元素名稱。
datatype

選擇性。列舉的資料類型和其所有成員。
memberlist

必要。在此陳述式中宣告的成員常數清單。多個成員會出現在個別的原始程式碼上。

每個 member 都具有下列語法和組件：[<attribute list>] member name [ = initializer ]

部分描述

membername 必要。這個成員的名稱。

initializer 選擇性。在編譯時評估並指派給此成員的運算式。
End Enum

終止 Enum 區塊。

部分	描述
`membername`	必要。這個成員的名稱。
`initializer`	選擇性。在編譯時評估並指派給此成員的運算式。

備註

如果您有一組邏輯上彼此相關的未變更值，您可以在列舉中一起定義它們。這會為列舉及其成員提供有意義的名稱，比其值更容易記住。然後，您可以在程式碼的許多位置使用列舉成員。

使用列舉的優點包括以下幾點：

減少因轉置或錯誤輸入數字而造成的錯誤。
可讓您在日後輕鬆變更值。
使程式碼更容易閱讀，這表示不太可能會出現錯誤。
確保向前相容性。當您使用列舉時，如果未來有人變更對應到成員名稱的值，您的程式碼比較不可能失敗。

列舉具有名稱、基礎資料類型和一組成員。每個成員都代表常數。

在類別、結構、模組或介面層級宣告的列舉，在任何程序之外，都是成員列舉。其為宣告其本身之類別、結構、模組或介面的成員。

您可以從其類別、結構、模組或介面中的任何位置存取成員列舉。類別、結構或模組外的程式碼，必須以該類別、結構或模組的名稱來限定成員列舉的名稱。您只要新增 Imports 陳述式到來源檔案，就能避免需要使用完整名稱的情況。

在命名空間層級宣告的列舉，在任何類別、結構、模組或介面之外，都是其所顯示之命名空間的成員。

列舉的宣告內容必須是來源檔案、命名空間、類別、結構、模組或介面，而且不得為程序。如需詳細資訊，請參閱宣告內容和預設存取層級。

您可以將屬性套用至整體列舉，但不能個別套用至其成員。屬性會將資訊提供給組件中繼資料。

資料類型

Enum 陳述式可以宣告列舉的資料類型。每個成員都會採用列舉的資料類型。您可以指定 Byte、Integer、Long、SByte、Short、UInteger、ULong 或 UShort。

如果您未為列舉指定 datatype，則每個成員都會採用其 initializer 的資料類型。如果您同時指定 datatype 和 initializer，則 initializer 的資料類型必須可轉換為 datatype。如果沒有 datatype 和 initializer，資料類型會預設為 Integer。

初始化成員

Enum 陳述式可以初始化 memberlist 中所選成員的內容。您需使用 initializer 提供要指派給成員的運算式。

如果您未為成員指定 initializer，Visual Basic 會將其初始化為零 (如果其在 memberlist 中是第一個 member)，或是比前面緊接著的 member 還大一個的值。

在每個 initializer 中提供的運算式都可以是任何常值的組合、已定義的其他常數，以及已定義的列舉成員，包括此列舉先前的成員。您可以使用算術和邏輯運算子來合併這類元素。

您無法在 initializer 中使用變數或函式。不過，您可以使用轉換關鍵字，例如 CByte 和 CShort。如果您以常數 String 或 Char 引數呼叫，也可以使用 AscW，因為可在編譯時加以評估。

列舉不能有浮點數值。如果成員獲指派浮點數值，且 Option Strict 設定為開啟，則會發生編譯器錯誤。如果 Option Strict 設定為關閉，則值會自動轉換為 Enum 類型。

如果成員的值超過基礎資料類型允許的範圍，或者如果您將任何成員初始化為基礎資料類型所允許的最大值，編譯器會報告錯誤。

修飾詞

類別、結構、模組和介面成員列舉預設為公用存取。您可以使用存取修飾詞調整其存取層級。命名空間成員列舉預設為 friend 存取。您可以將其存取層級調整為 public，但不能為 private 或 protected。如需詳細資訊，請參閱 Visual Basic 的存取層級。

所有列舉成員都有 public 存取權，但您無法在其上使用任何存取修飾詞。不過，如果列舉本身具有較受限的存取層級，則指定的列舉存取層級優先。

根據預設，所有列舉都是類型，而且其欄位是常數。因此，當宣告列舉或其成員時，無法使用 Shared、Static 和 ReadOnly 關鍵字。

指派多個值

列舉通常代表互斥的值。透過在 Enum 宣告中包含 FlagsAttribute 屬性，您可以改為將多個值指派至列舉的執行個體。 FlagsAttribute 屬性會指定列舉應被視為位元欄位，也就是一組旗標。這些項目稱為「位元」列舉。

當您使用 FlagsAttribute 屬性宣告列舉時，建議使用 2 的乘冪作為值，也就是 1、2、4、8、16 等數字。我們也建議將值為 0 之成員的名稱設為 "None"。如需其他指導，請參閱 FlagsAttribute 和 Enum。

範例 1

下列範例顯示如何使用 Enum 陳述式。請注意，成員稱為 EggSizeEnum.Medium，而不是 Medium。

Public Class Egg
    Enum EggSizeEnum
        Jumbo
        ExtraLarge
        Large
        Medium
        Small
    End Enum

    Public Sub Poach()
        Dim size As EggSizeEnum

        size = EggSizeEnum.Medium
        ' Continue processing...
    End Sub
End Class

範例 2

下列範例中的方法不在 Egg 類別內。因此，EggSizeEnum 的完整名稱為 Egg.EggSizeEnum。

Public Sub Scramble(ByVal size As Egg.EggSizeEnum)
    ' Process for the three largest sizes.
    ' Throw an exception for any other size.
    Select Case size
        Case Egg.EggSizeEnum.Jumbo
            ' Process.
        Case Egg.EggSizeEnum.ExtraLarge
            ' Process.
        Case Egg.EggSizeEnum.Large
            ' Process.
        Case Else
            Throw New ApplicationException("size is invalid: " & size.ToString)
    End Select
End Sub

範例 3

下列範例會使用 Enum 陳述式來定義具名常數類型的相關集合。在此情況下，這些值是您可以選擇為資料庫設計資料輸入表單的色彩。

Public Enum InterfaceColors
    MistyRose = &HE1E4FF&
    SlateGray = &H908070&
    DodgerBlue = &HFF901E&
    DeepSkyBlue = &HFFBF00&
    SpringGreen = &H7FFF00&
    ForestGreen = &H228B22&
    Goldenrod = &H20A5DA&
    Firebrick = &H2222B2&
End Enum

範例 4

下列範例顯示同時包含正數和負數的值。

Enum SecurityLevel
    IllegalEntry = -1
    MinimumSecurity = 0
    MaximumSecurity = 1
End Enum

範例 5

下列範例中，As 子句會用來指定列舉的 datatype。

Public Enum MyEnum As Byte
    Zero
    One
    Two
End Enum

範例 6

下列範例顯示如何使用位元列舉。位元列舉的執行個體可以獲指派多個值。 Enum 宣告包含 FlagsAttribute 屬性，其指出列舉可被視作一組旗標。

' Apply the Flags attribute, which allows an instance
' of the enumeration to have multiple values.
<Flags()> Public Enum FilePermissions As Integer
    None = 0
    Create = 1
    Read = 2
    Update = 4
    Delete = 8
End Enum

Public Sub ShowBitwiseEnum()

    ' Declare the non-exclusive enumeration object and
    ' set it to multiple values.
    Dim perm As FilePermissions
    perm = FilePermissions.Read Or FilePermissions.Update

    ' Show the values in the enumeration object.
    Console.WriteLine(perm.ToString)
    ' Output: Read, Update

    ' Show the total integer value of all values
    ' in the enumeration object.
    Console.WriteLine(CInt(perm))
    ' Output: 6

    ' Show whether the enumeration object contains
    ' the specified flag.
    Console.WriteLine(perm.HasFlag(FilePermissions.Update))
    ' Output: True
End Sub

範例 7

下列範例會逐一查看列舉。其會使用 GetNames 方法從列舉取得一系列的成員名稱，以及使用 GetValues 取得一系列的成員值。

Enum EggSizeEnum
    Jumbo
    ExtraLarge
    Large
    Medium
    Small
End Enum

Public Sub Iterate()
    Dim names = [Enum].GetNames(GetType(EggSizeEnum))
    For Each name In names
        Console.Write(name & " ")
    Next
    Console.WriteLine()
    ' Output: Jumbo ExtraLarge Large Medium Small 

    Dim values = [Enum].GetValues(GetType(EggSizeEnum))
    For Each value In values
        Console.Write(value & " ")
    Next
    Console.WriteLine()
    ' Output: 0 1 2 3 4 
End Sub