UTF8Encoding 類別
定義
重要
部分資訊涉及發行前產品,在發行之前可能會有大幅修改。 Microsoft 對此處提供的資訊,不做任何明確或隱含的瑕疵擔保。
代表 Unicode 字元的 UTF-8 編碼。
public ref class UTF8Encoding : System::Text::Encoding
public class UTF8Encoding : System.Text.Encoding
[System.Serializable]
public class UTF8Encoding : System.Text.Encoding
[System.Serializable]
[System.Runtime.InteropServices.ComVisible(true)]
public class UTF8Encoding : System.Text.Encoding
type UTF8Encoding = class
inherit Encoding
[<System.Serializable>]
type UTF8Encoding = class
inherit Encoding
[<System.Serializable>]
[<System.Runtime.InteropServices.ComVisible(true)>]
type UTF8Encoding = class
inherit Encoding
Public Class UTF8Encoding
Inherits Encoding
- 繼承
- 屬性
範例
以下範例使用物件 UTF8Encoding 編碼一串 Unicode 字元並將其儲存在位元組陣列中。 Unicode 字串包含兩個字元,Pi(U+03A0)和 Sigma(U+03A3),它們不在 ASCII 字元範圍內。 當編碼的位元組陣列解碼回字串時,Pi 和 Sigma 字元仍然存在。
using System;
using System.Text;
class Example
{
public static void Main()
{
// Create a UTF-8 encoding.
UTF8Encoding utf8 = new UTF8Encoding();
// A Unicode string with two characters outside an 8-bit code range.
String unicodeString =
"This Unicode string has 2 characters outside the " +
"ASCII range:\n" +
"Pi (\u03a0), and Sigma (\u03a3).";
Console.WriteLine("Original string:");
Console.WriteLine(unicodeString);
// Encode the string.
Byte[] encodedBytes = utf8.GetBytes(unicodeString);
Console.WriteLine();
Console.WriteLine("Encoded bytes:");
for (int ctr = 0; ctr < encodedBytes.Length; ctr++) {
Console.Write("{0:X2} ", encodedBytes[ctr]);
if ((ctr + 1) % 25 == 0)
Console.WriteLine();
}
Console.WriteLine();
// Decode bytes back to string.
String decodedString = utf8.GetString(encodedBytes);
Console.WriteLine();
Console.WriteLine("Decoded bytes:");
Console.WriteLine(decodedString);
}
}
// The example displays the following output:
// Original string:
// This Unicode string has 2 characters outside the ASCII range:
// Pi (π), and Sigma (Σ).
//
// Encoded bytes:
// 54 68 69 73 20 55 6E 69 63 6F 64 65 20 73 74 72 69 6E 67 20 68 61 73 20 32
// 20 63 68 61 72 61 63 74 65 72 73 20 6F 75 74 73 69 64 65 20 74 68 65 20 41
// 53 43 49 49 20 72 61 6E 67 65 3A 20 0D 0A 50 69 20 28 CE A0 29 2C 20 61 6E
// 64 20 53 69 67 6D 61 20 28 CE A3 29 2E
//
// Decoded bytes:
// This Unicode string has 2 characters outside the ASCII range:
// Pi (π), and Sigma (Σ).
Imports System.Text
Class Example
Public Shared Sub Main()
' Create a UTF-8 encoding.
Dim utf8 As New UTF8Encoding()
' A Unicode string with two characters outside an 8-bit code range.
Dim unicodeString As String = _
"This Unicode string has 2 characters outside the " &
"ASCII range: " & vbCrLf &
"Pi (" & ChrW(&h03A0) & "), and Sigma (" & ChrW(&h03A3) & ")."
Console.WriteLine("Original string:")
Console.WriteLine(unicodeString)
' Encode the string.
Dim encodedBytes As Byte() = utf8.GetBytes(unicodeString)
Console.WriteLine()
Console.WriteLine("Encoded bytes:")
For ctr As Integer = 0 To encodedBytes.Length - 1
Console.Write("{0:X2} ", encodedBytes(ctr))
If (ctr + 1) Mod 25 = 0 Then Console.WriteLine
Next
Console.WriteLine()
' Decode bytes back to string.
Dim decodedString As String = utf8.GetString(encodedBytes)
Console.WriteLine()
Console.WriteLine("Decoded bytes:")
Console.WriteLine(decodedString)
End Sub
End Class
' The example displays the following output:
' Original string:
' This Unicode string has 2 characters outside the ASCII range:
' Pi (π), and Sigma (Σ).
'
' Encoded bytes:
' 54 68 69 73 20 55 6E 69 63 6F 64 65 20 73 74 72 69 6E 67 20 68 61 73 20 32
' 20 63 68 61 72 61 63 74 65 72 73 20 6F 75 74 73 69 64 65 20 74 68 65 20 41
' 53 43 49 49 20 72 61 6E 67 65 3A 20 0D 0A 50 69 20 28 CE A0 29 2C 20 61 6E
' 64 20 53 69 67 6D 61 20 28 CE A3 29 2E
'
' Decoded bytes:
' This Unicode string has 2 characters outside the ASCII range:
' Pi (π), and Sigma (Σ).
以下範例使用與前例相同的字串,但將編碼的位元組寫入檔案,並在位元組串流前加上位元組順序標記(BOM)。 接著它以兩種不同方式讀取檔案:透過物件 StreamReader 作為文字檔讀取;以及以二進位檔讀取。 如你所料,這兩個新讀的字串都沒有包含BOM。
using System;
using System.IO;
using System.Text;
public class Example
{
public static void Main()
{
// Create a UTF-8 encoding that supports a BOM.
Encoding utf8 = new UTF8Encoding(true);
// A Unicode string with two characters outside an 8-bit code range.
String unicodeString =
"This Unicode string has 2 characters outside the " +
"ASCII range:\n" +
"Pi (\u03A0)), and Sigma (\u03A3).";
Console.WriteLine("Original string:");
Console.WriteLine(unicodeString);
Console.WriteLine();
// Encode the string.
Byte[] encodedBytes = utf8.GetBytes(unicodeString);
Console.WriteLine("The encoded string has {0} bytes.",
encodedBytes.Length);
Console.WriteLine();
// Write the bytes to a file with a BOM.
var fs = new FileStream(@".\UTF8Encoding.txt", FileMode.Create);
Byte[] bom = utf8.GetPreamble();
fs.Write(bom, 0, bom.Length);
fs.Write(encodedBytes, 0, encodedBytes.Length);
Console.WriteLine("Wrote {0} bytes to the file.", fs.Length);
fs.Close();
Console.WriteLine();
// Open the file using StreamReader.
var sr = new StreamReader(@".\UTF8Encoding.txt");
String newString = sr.ReadToEnd();
sr.Close();
Console.WriteLine("String read using StreamReader:");
Console.WriteLine(newString);
Console.WriteLine();
// Open the file as a binary file and decode the bytes back to a string.
fs = new FileStream(@".\UTF8Encoding.txt", FileMode.Open);
Byte[] bytes = new Byte[fs.Length];
fs.Read(bytes, 0, (int)fs.Length);
fs.Close();
String decodedString = utf8.GetString(bytes);
Console.WriteLine("Decoded bytes:");
Console.WriteLine(decodedString);
}
}
// The example displays the following output:
// Original string:
// This Unicode string has 2 characters outside the ASCII range:
// Pi (π), and Sigma (Σ).
//
// The encoded string has 88 bytes.
//
// Wrote 91 bytes to the file.
//
// String read using StreamReader:
// This Unicode string has 2 characters outside the ASCII range:
// Pi (π), and Sigma (Σ).
//
// Decoded bytes:
// This Unicode string has 2 characters outside the ASCII range:
// Pi (π), and Sigma (Σ).
Imports System.IO
Imports System.Text
Class Example
Public Shared Sub Main()
' Create a UTF-8 encoding that supports a BOM.
Dim utf8 As New UTF8Encoding(True)
' A Unicode string with two characters outside an 8-bit code range.
Dim unicodeString As String = _
"This Unicode string has 2 characters outside the " &
"ASCII range: " & vbCrLf &
"Pi (" & ChrW(&h03A0) & "), and Sigma (" & ChrW(&h03A3) & ")."
Console.WriteLine("Original string:")
Console.WriteLine(unicodeString)
Console.WriteLine()
' Encode the string.
Dim encodedBytes As Byte() = utf8.GetBytes(unicodeString)
Console.WriteLine("The encoded string has {0} bytes.",
encodedBytes.Length)
Console.WriteLine()
' Write the bytes to a file with a BOM.
Dim fs As New FileStream(".\UTF8Encoding.txt", FileMode.Create)
Dim bom() As Byte = utf8.GetPreamble()
fs.Write(bom, 0, bom.Length)
fs.Write(encodedBytes, 0, encodedBytes.Length)
Console.WriteLine("Wrote {0} bytes to the file.", fs.Length)
fs.Close()
Console.WriteLine()
' Open the file using StreamReader.
Dim sr As New StreamReader(".\UTF8Encoding.txt")
Dim newString As String = sr.ReadToEnd()
sr.Close()
Console.WriteLine("String read using StreamReader:")
Console.WriteLine(newString)
Console.WriteLine()
' Open the file as a binary file and decode the bytes back to a string.
fs = new FileStream(".\UTF8Encoding.txt", FileMode.Open)
Dim bytes(fs.Length - 1) As Byte
fs.Read(bytes, 0, fs.Length)
fs.Close()
Dim decodedString As String = utf8.GetString(bytes)
Console.WriteLine("Decoded bytes:")
Console.WriteLine(decodedString)
End Sub
End Class
' The example displays the following output:
' Original string:
' This Unicode string has 2 characters outside the ASCII range:
' Pi (π), and Sigma (Σ).
'
' The encoded string has 88 bytes.
'
' Wrote 91 bytes to the file.
'
' String read using StreamReader:
' This Unicode string has 2 characters outside the ASCII range:
' Pi (π), and Sigma (Σ).
'
' Decoded bytes:
' This Unicode string has 2 characters outside the ASCII range:
' Pi (π), and Sigma (Σ).
備註
編碼是將一組 Unicode 字元轉換成位元組序列的程式。 解碼是將一連串編碼好的位元組轉換成一組 Unicode 字元的過程。
UTF-8 是一種 Unicode 編碼,將每個碼點以一到四個位元組的序列表示。 與 UTF-16 和 UTF-32 編碼不同,UTF-8 編碼不需要「端序」;無論處理器是大端序還是小端序,編碼方案都是相同的。 UTF8Encoding 對應 Windows 代碼頁 65001。 欲了解更多關於 支援的 UTF 及其他 System.Text編碼的資訊,請參閱 .NET Framework 中的字元編碼。
你可以用多種方式實例化一個 UTF8Encoding 物件,取決於你是否希望它提供位元組順序標記(BOM),以及是否啟用錯誤偵測。 下表列出回傳UTF8Encoding物件的建構子與Encoding屬性。
| 會員 | BOM | 錯誤偵測 |
|---|---|---|
| Encoding.UTF8 | 是的 | 不行(替代備用) |
| UTF8Encoding.UTF8Encoding() | No | 不行(替代備用) |
| UTF8Encoding.UTF8Encoding(Boolean) | Configurable | 不行(替代備用) |
| UTF8Encoding.UTF8Encoding(Boolean, Boolean) | Configurable | Configurable |
該 GetByteCount 方法決定編碼一組 Unicode 字元的位元組數,並 GetBytes 執行實際編碼。
同樣地,方法 GetCharCount 決定解碼一串位元組的字元數,而 和 GetCharsGetString 方法則執行實際解碼。
對於能在編碼或解碼跨多個區塊的資料(例如以 100,000 字元區段編碼的 100 萬字元字串)時儲存狀態資訊的編碼器或解碼器,分別使用 GetEncoder 和 GetDecoder 屬性。
物件可 UTF8Encoding 選擇性地提供位元組順序標記(BOM),這是一個位元組陣列,可以置於編碼過程產生的位元組串流開頭。 如果 UTF-8 編碼的位元組串流前加上位元組順序標記(BOM),它有助於解碼器決定位元組順序及轉換格式(UTF)。 但請注意,Unicode 標準並不要求也不建議在 UTF-8 編碼串流中使用 BOM。 如需位元組順序和位元組順序標記的詳細資訊,請參閱 Unicode 首頁上的 Unicode 標準。
如果編碼器設定提供 BOM,你可以透過呼叫 GetPreamble 該方法取得;否則,方法會回傳一個空陣列。 請注意,即使 UTF8Encoding 物件已設定為 BOM 支援,也必須在編碼的位元組流開頭適當地包含 BOM;類別的 UTF8Encoding 編碼方法不會自動做到這點。
Caution
為了啟用錯誤偵測並讓類別實例更安全,你應該呼叫 UTF8Encoding(Boolean, Boolean) 建構子並將參數設 throwOnInvalidBytes 為 true。 啟用錯誤偵測時,偵測無效字元序列或位元組的方法會拋 ArgumentException 出例外。 若沒有錯誤偵測,則不會拋出例外,且無效序列通常會被忽略。
Note
若 UTF-8 編碼物件使用不同的 .NET Framework 版本序列化與反序列化,其狀態不會被保留。
建構函式
| 名稱 | Description |
|---|---|
| UTF8Encoding() |
初始化 UTF8Encoding 類別的新執行個體。 |
| UTF8Encoding(Boolean, Boolean) |
初始化 UTF8Encoding 類別的新執行個體。 參數會指定是否提供 Unicode 位元組順序標記,以及當偵測到無效編碼時是否拋出例外。 |
| UTF8Encoding(Boolean) |
初始化 UTF8Encoding 類別的新執行個體。 一個參數指定是否提供 Unicode 位元組序標記。 |
屬性
| 名稱 | Description |
|---|---|
| BodyName |
當在衍生類別中覆寫時,會獲得一個可用於郵件代理體標籤的當前編碼名稱。 (繼承來源 Encoding) |
| CodePage |
當在衍生類別中被覆寫時,會獲得目前 Encoding的代碼頁識別碼。 (繼承來源 Encoding) |
| DecoderFallback |
取得或設定 DecoderFallback 當前 Encoding 物件的物件。 (繼承來源 Encoding) |
| EncoderFallback |
取得或設定 EncoderFallback 當前 Encoding 物件的物件。 (繼承來源 Encoding) |
| EncodingName |
當在衍生類別中覆寫時,會得到目前編碼的人類可讀描述。 (繼承來源 Encoding) |
| HeaderName |
當 在衍生類別中被覆寫時,會獲得一個可用於郵件代理標頭標籤的當前編碼名稱。 (繼承來源 Encoding) |
| IsBrowserDisplay |
當 在衍生類別中覆寫時,會獲得一個值,表示瀏覽器客戶端是否可以使用目前的編碼來顯示內容。 (繼承來源 Encoding) |
| IsBrowserSave |
當在衍生類別中覆寫時,會獲得一個值,表示瀏覽器客戶端是否能使用目前的編碼來儲存內容。 (繼承來源 Encoding) |
| IsMailNewsDisplay |
當在派生類別中覆寫時,會獲得一個值,表示目前的編碼是否可用於郵件和新聞用戶端顯示內容。 (繼承來源 Encoding) |
| IsMailNewsSave |
當在衍生類別中覆寫時,會獲得一個值,表示目前的編碼是否能被郵件和新聞客戶端用來儲存內容。 (繼承來源 Encoding) |
| IsReadOnly |
當在衍生類別中覆寫時,會獲得一個值,表示目前編碼是否為唯讀。 (繼承來源 Encoding) |
| IsSingleByte |
當在派生類別中覆寫時,會得到一個值,表示目前編碼是否使用單位元組的碼點。 (繼承來源 Encoding) |
| Preamble |
若此物件設定提供 Unicode 位元組順序標記,則以 UTF-8 格式編碼。 |
| Preamble |
當在衍生類別中覆寫時,會回傳一個包含指定所用編碼序列的位元組的區間。 (繼承來源 Encoding) |
| WebName |
當在衍生類別中被覆寫時,會獲得目前編碼的名稱,註冊於網際網路號碼分配管理局(IANA)。 (繼承來源 Encoding) |
| WindowsCodePage |
當在衍生類別中覆寫時,會得到與目前編碼最接近的 Windows 作業系統代碼頁。 (繼承來源 Encoding) |
方法
| 名稱 | Description |
|---|---|
| Clone() |
當在衍生類別中覆寫時,會產生目前 Encoding 物件的淺層副本。 (繼承來源 Encoding) |
| Equals(Object) |
判斷指定的物件是否等於當前 UTF8Encoding 物件。 |
| GetByteCount(Char[], Int32, Int32) |
計算從指定字元陣列編碼一組字元所產生的位元組數。 |
| GetByteCount(Char[]) |
當在派生類別中覆寫時,會計算將指定字元陣列中所有字元編碼所產生的位元組數。 (繼承來源 Encoding) |
| GetByteCount(Char*, Int32) |
計算從指定字元指標開始編碼一組字元所產生的位元組數。 |
| GetByteCount(ReadOnlySpan<Char>) |
計算編碼指定字元區間所產生的位元組數。 |
| GetByteCount(ReadOnlySpan<Char>) |
當在派生類別中覆寫時,會計算在指定字元區間內編碼字元所產生的位元組數。 (繼承來源 Encoding) |
| GetByteCount(String, Int32, Int32) |
當在派生類別中覆寫時,會計算從指定字串編碼一組字元所產生的位元組數。 (繼承來源 Encoding) |
| GetByteCount(String) |
計算透過編碼指定 String字元所產生的位元組數。 |
| GetBytes(Char[], Int32, Int32, Byte[], Int32) |
將指定字元陣列中的一組字元編碼到指定的位元組陣列中。 |
| GetBytes(Char[], Int32, Int32) |
當在派生類別中覆寫時,會將指定字元陣列中的一組字元編碼成一串位元組。 (繼承來源 Encoding) |
| GetBytes(Char[]) |
當在派生類別中覆寫時,會將指定字元陣列中的所有字元編碼成一串位元組。 (繼承來源 Encoding) |
| GetBytes(Char*, Int32, Byte*, Int32) |
將一組從指定字元指標開始的字元編碼成一串位元組,並從指定位元組指標開始儲存。 |
| GetBytes(ReadOnlySpan<Char>, Span<Byte>) |
將指定的字元區間編碼為指定的位元組區間。 |
| GetBytes(ReadOnlySpan<Char>, Span<Byte>) |
當在派生類別中覆寫時,會將指定唯讀區間的一組字元編碼到位元組區間。 (繼承來源 Encoding) |
| GetBytes(String, Int32, Int32, Byte[], Int32) |
將指定的 String 一組字元編碼到指定的位元組陣列中。 |
| GetBytes(String, Int32, Int32) |
當在派生類別中覆寫時,會將指定字串中指定的 |
| GetBytes(String) |
將指定 String 物件中的字元編碼成一串位元組。 |
| GetBytes(String) |
當在派生類別中覆寫時,會將指定字串中的所有字元編碼成一串位元組。 (繼承來源 Encoding) |
| GetCharCount(Byte[], Int32, Int32) |
計算從指定位元組陣列解碼一串位元組所產生的字元數。 |
| GetCharCount(Byte[]) |
當在派生類別中覆寫時,會計算解碼指定位元組陣列中所有位元組所產生的字元數。 (繼承來源 Encoding) |
| GetCharCount(Byte*, Int32) |
透過解碼從指定位元組指標開始的一串位元組來計算字元數。 |
| GetCharCount(ReadOnlySpan<Byte>) |
透過解碼指定的位元組範圍來計算字元數。 |
| GetCharCount(ReadOnlySpan<Byte>) |
當在衍生類別中覆寫時,會計算出解碼所提供的唯讀位元組區間所產生的字元數。 (繼承來源 Encoding) |
| GetChars(Byte[], Int32, Int32, Char[], Int32) |
將指定位元組陣列的一串位元組解碼到指定的字元陣列。 |
| GetChars(Byte[], Int32, Int32) |
當在派生類別中覆寫時,會將指定位元組陣列中的一串位元組解碼成一組字元。 (繼承來源 Encoding) |
| GetChars(Byte[]) |
當在派生類別中覆寫時,會將指定位元組陣列中的所有位元組解碼成一組字元。 (繼承來源 Encoding) |
| GetChars(Byte*, Int32, Char*, Int32) |
將從指定位元組指標開始的一串位元組解碼成一組字元,這些字元從指定字元指標開始儲存。 |
| GetChars(ReadOnlySpan<Byte>, Span<Char>) |
將指定的位元組區間解碼為指定的字元區間。 |
| GetChars(ReadOnlySpan<Byte>, Span<Char>) |
當在派生類別中覆寫時,會將指定唯讀位元組區間中的所有位元組解碼為字元區間。 (繼承來源 Encoding) |
| GetDecoder() |
取得一個解碼器,能將 UTF-8 編碼的位元組序列轉換成 Unicode 字元序列。 |
| GetEncoder() |
取得一個編碼器,可將一串 Unicode 字元轉換成 UTF-8 編碼的位元組序列。 |
| GetHashCode() |
傳回目前實例的哈希碼。 |
| GetMaxByteCount(Int32) |
計算編碼指定字元數所產生的最大位元組數。 |
| GetMaxCharCount(Int32) |
計算解碼指定位元組數後產生的最大字元數。 |
| GetPreamble() |
若編碼物件設定提供 Unicode 位元組順序標記,則 UTF8Encoding 回傳 UTF-8 格式編碼的 Unicode 位元組序標記。 |
| GetString(Byte[], Int32, Int32) |
將位元組陣列中的位元組範圍解碼成字串。 |
| GetString(Byte[], Int32, Int32) |
當在派生類別中覆寫時,會將指定位元組陣列中的一串位元組解碼成字串。 (繼承來源 Encoding) |
| GetString(Byte[]) |
當在衍生類別中覆寫時,會將指定位元組陣列中的所有位元組解碼成一個字串。 (繼承來源 Encoding) |
| GetString(Byte*, Int32) |
當在派生類別中覆寫時,會將從指定位址開始的指定位元組解碼成字串。 (繼承來源 Encoding) |
| GetString(ReadOnlySpan<Byte>) |
當在派生類別中覆寫時,會將指定位元組區間中的所有位元組解碼成一個字串。 (繼承來源 Encoding) |
| GetType() |
取得目前實例的 Type。 (繼承來源 Object) |
| IsAlwaysNormalized() |
會得到一個值,表示目前編碼是否總是正規化,使用預設的正規化形式。 (繼承來源 Encoding) |
| IsAlwaysNormalized(NormalizationForm) |
當在派生類別中覆寫時,會得到一個值,表示目前編碼是否總是被正規化,並使用指定的正規化形式。 (繼承來源 Encoding) |
| MemberwiseClone() |
建立目前 Object的淺層複本。 (繼承來源 Object) |
| ToString() |
傳回表示目前 物件的字串。 (繼承來源 Object) |
| TryGetBytes(ReadOnlySpan<Char>, Span<Byte>, Int32) |
如果目的地夠大,則會將指定唯讀區段中的一組字元編碼成位元組區間。 |
| TryGetChars(ReadOnlySpan<Byte>, Span<Char>, Int32) |
如果目的地夠大,則會將指定唯讀區段中的一組位元組解碼成字元區間。 |
擴充方法
| 名稱 | Description |
|---|---|
| GetBytes(Encoding, ReadOnlySequence<Char>, IBufferWriter<Byte>) |
利用指定ReadOnlySequence<T>條件解碼 |
| GetBytes(Encoding, ReadOnlySequence<Char>, Span<Byte>) |
將指定 ReadOnlySequence<T> 內容編碼為 |
| GetBytes(Encoding, ReadOnlySequence<Char>) |
將指定 ReadOnlySequence<T> 編碼成 Byte 一個陣列,使用指定的 Encoding。 |
| GetBytes(Encoding, ReadOnlySpan<Char>, IBufferWriter<Byte>) |
將指定 ReadOnlySpan<T> 內容編碼為 |
| GetChars(Encoding, ReadOnlySequence<Byte>, IBufferWriter<Char>) |
利用指定ReadOnlySequence<T>條件解碼 |
| GetChars(Encoding, ReadOnlySequence<Byte>, Span<Char>) |
利用指定ReadOnlySequence<T>條件將指定 |
| GetChars(Encoding, ReadOnlySpan<Byte>, IBufferWriter<Char>) |
利用指定ReadOnlySpan<T>條件解碼 |
| GetString(Encoding, ReadOnlySequence<Byte>) |
利用指定的 ReadOnlySequence<T>將 解碼String為 。Encoding |