資料與資料物件

發行項
09/27/2024

在拖放作業中傳輸的資料會儲存在資料物件中。就概念上而言，資料物件是由下列一或多個配對所組成：

包含實際資料的 Object。
對應的資料格式識別碼。

資料本身可以包含任何可表示為基底 Object的東西。對應的資料格式是字串或 Type ，可提示資料所使用的格式。資料物件支援裝載多個資料/資料格式組；這可讓單一資料物件以多種格式提供資料。

資料物件

所有資料物件都必須實作 IDataObject 介面，該介面提供下列標準方法集，以開啟及輔助資料傳輸。

方法	摘要
GetData	擷取指定資料格式的資料物件。
GetDataPresent	檢查資料是否可用，或可以轉換成指定的格式。
GetFormats	傳回格式清單，為此資料物件中資料的儲存格式，或可以轉成的格式。
SetData	將指定的資料儲存在此資料物件中。

WPF 提供 DataObject 類別中 IDataObject 的基本實作。庫存 DataObject 類別就足以用於許多常見的資料傳輸案例。

有數種預先定義的格式，例如點陣圖、CSV、檔案、HTML、RTF、字串、文字和音訊。如需 WPF 所提供的預先定義資料格式資訊，請參閱 DataFormats 類別參考主題。

資料物件通常包含一項功能，可讓您在擷取資料時，自動將儲存在一種格式的資料轉換成不同的格式，此功能稱為自動轉換。查詢資料物件中可用的資料格式時，可以藉由呼叫 GetFormats(Boolean) 或 GetDataPresent(String, Boolean) 方法來篩選自動轉換資料格式，並將 autoConvert 參數指定為 false。使用 SetData(String, Object, Boolean) 方法將資料新增至資料物件時，可以將 autoConvert 參數設定為 false，禁止自動轉換資料。

使用資料物件

本節說明建立和使用資料物件的常見技術。

建立新的資料物件

DataObject 類別提供數個多載建構函式，可協助使用單一資料/資料格式組填入新的 DataObject 實例。

下列範例程式碼會建立新的資料物件，並使用其中一個多載建構函式 DataObject（DataObject(String, Object)），以字串和指定的資料格式初始化資料物件。在此情況下，資料格式是由字串指定；DataFormats 類別提供一組預先定義的型別字串。默認允許自動轉換預存資料。

string stringData = "Some string data to store...";
string dataFormat = DataFormats.UnicodeText;
DataObject dataObject = new DataObject(dataFormat, stringData);

Dim stringData As String = "Some string data to store..."
Dim dataFormat As String = DataFormats.UnicodeText
Dim dataObject As New DataObject(dataFormat, stringData)

如需更多建立資料物件的程式碼範例，請參閱建立資料物件。

以多種格式儲存資料

單一資料物件能夠以多種格式儲存資料。策略性使用單一資料物件內多個資料格式，比起僅使用單一資料格式，可以使資料物件被更多樣的置放目標取用。請注意，一般而言，拖曳來源與潛在置放目標所能讀取的資料格式無關。

下列範例示範如何使用 SetData(String, Object) 方法，以多種格式將資料新增至資料物件。

DataObject dataObject = new DataObject();
string sourceData = "Some string data to store...";

// Encode the source string into Unicode byte arrays.
byte[] unicodeText = Encoding.Unicode.GetBytes(sourceData); // UTF-16
byte[] utf8Text = Encoding.UTF8.GetBytes(sourceData);
byte[] utf32Text = Encoding.UTF32.GetBytes(sourceData);

// The DataFormats class does not provide data format fields for denoting
// UTF-32 and UTF-8, which are seldom used in practice; the following strings
// will be used to identify these "custom" data formats.
string utf32DataFormat = "UTF-32";
string utf8DataFormat  = "UTF-8";

// Store the text in the data object, letting the data object choose
// the data format (which will be DataFormats.Text in this case).
dataObject.SetData(sourceData);
// Store the Unicode text in the data object.  Text data can be automatically
// converted to Unicode (UTF-16 / UCS-2) format on extraction from the data object;
// Therefore, explicitly converting the source text to Unicode is generally unnecessary, and
// is done here as an exercise only.
dataObject.SetData(DataFormats.UnicodeText, unicodeText);
// Store the UTF-8 text in the data object...
dataObject.SetData(utf8DataFormat, utf8Text);
// Store the UTF-32 text in the data object...
dataObject.SetData(utf32DataFormat, utf32Text);

Dim dataObject As New DataObject()
Dim sourceData As String = "Some string data to store..."

' Encode the source string into Unicode byte arrays.
Dim unicodeText() As Byte = Encoding.Unicode.GetBytes(sourceData) ' UTF-16
Dim utf8Text() As Byte = Encoding.UTF8.GetBytes(sourceData)
Dim utf32Text() As Byte = Encoding.UTF32.GetBytes(sourceData)

' The DataFormats class does not provide data format fields for denoting
' UTF-32 and UTF-8, which are seldom used in practice; the following strings 
' will be used to identify these "custom" data formats.
Dim utf32DataFormat As String = "UTF-32"
Dim utf8DataFormat As String = "UTF-8"

' Store the text in the data object, letting the data object choose
' the data format (which will be DataFormats.Text in this case).
dataObject.SetData(sourceData)
' Store the Unicode text in the data object.  Text data can be automatically
' converted to Unicode (UTF-16 / UCS-2) format on extraction from the data object; 
' Therefore, explicitly converting the source text to Unicode is generally unnecessary, and
' is done here as an exercise only.
dataObject.SetData(DataFormats.UnicodeText, unicodeText)
' Store the UTF-8 text in the data object...
dataObject.SetData(utf8DataFormat, utf8Text)
' Store the UTF-32 text in the data object...
dataObject.SetData(utf32DataFormat, utf32Text)

查詢資料物件是否有可用的格式

由於單一資料物件可以包含任意數目的資料格式，因此資料物件包含用來擷取可用資料格式清單的功能。

下列範例程式碼會使用 GetFormats 多載來取得字串陣列，表示資料物件中可用的所有資料格式（原生和自動轉換）。

DataObject dataObject = new DataObject("Some string data to store...");

// Get an array of strings, each string denoting a data format
// that is available in the data object.  This overload of GetDataFormats
// returns all available data formats, native and auto-convertible.
string[] dataFormats = dataObject.GetFormats();

// Get the number of data formats present in the data object, including both
// auto-convertible and native data formats.
int numberOfDataFormats = dataFormats.Length;

// To enumerate the resulting array of data formats, and take some action when
// a particular data format is found, use a code structure similar to the following.
foreach (string dataFormat in dataFormats)
{
    if (dataFormat == DataFormats.Text)
    {
        // Take some action if/when data in the Text data format is found.
        break;
    }
    else if(dataFormat == DataFormats.StringFormat)
    {
        // Take some action if/when data in the string data format is found.
        break;
    }
}

Dim dataObject As New DataObject("Some string data to store...")

' Get an array of strings, each string denoting a data format
' that is available in the data object.  This overload of GetDataFormats
' returns all available data formats, native and auto-convertible.
Dim dataFormats() As String = dataObject.GetFormats()

' Get the number of data formats present in the data object, including both
' auto-convertible and native data formats.
Dim numberOfDataFormats As Integer = dataFormats.Length

' To enumerate the resulting array of data formats, and take some action when
' a particular data format is found, use a code structure similar to the following.
For Each dataFormat As String In dataFormats
    If dataFormat = System.Windows.DataFormats.Text Then
        ' Take some action if/when data in the Text data format is found.
        Exit For
    ElseIf dataFormat = System.Windows.DataFormats.StringFormat Then
        ' Take some action if/when data in the string data format is found.
        Exit For
    End If
Next dataFormat

如需查詢資料物件以取得可用資料格式的程式碼範例，請參閱列出資料物件中的資料格式。如需查詢資料物件是否有特定資料格式的範例，請參閱判斷資料物件中是否有某資料格式。

從 Dialog 物件擷取資料

從特定格式的資料物件擷取資料只牽涉到呼叫其中一個 GetData 方法，並指定所需的資料格式。其中一個 GetDataPresent 方法可用來檢查特定資料格式是否存在。 GetData 傳回 Object中的資料；視資料格式而定，此物件可以轉換成類型特定的容器。

下列範例程式碼會使用 GetDataPresent(String) 多載來檢查指定的資料格式是否可用（原生或自動轉換）。如果指定的格式可用，此範例會使用 GetData(String) 方法來擷取資料。

DataObject dataObject = new DataObject("Some string data to store...");

string desiredFormat = DataFormats.UnicodeText;
byte[] data = null;

// Use the GetDataPresent method to check for the presence of a desired data format.
// This particular overload of GetDataPresent looks for both native and auto-convertible
// data formats.
if (dataObject.GetDataPresent(desiredFormat))
{
    // If the desired data format is present, use one of the GetData methods to retrieve the
    // data from the data object.
    data = dataObject.GetData(desiredFormat) as byte[];
}

Dim dataObject As New DataObject("Some string data to store...")

Dim desiredFormat As String = DataFormats.UnicodeText
Dim data() As Byte = Nothing

' Use the GetDataPresent method to check for the presence of a desired data format.
' This particular overload of GetDataPresent looks for both native and auto-convertible 
' data formats.
If dataObject.GetDataPresent(desiredFormat) Then
    ' If the desired data format is present, use one of the GetData methods to retrieve the
    ' data from the data object.
    data = TryCast(dataObject.GetData(desiredFormat), Byte())
End If

如需更多從資料物件擷取資料之程式碼範例，請參閱擷取特定資料格式的資料。

從資料物件移除資料

無法從資料物件直接移除資料。若要有效地從資料物件移除資料，請遵循下列步驟：

建立只包含您想要保留之資料的新資料物件。
將所需的資料從舊資料物件「複製」到新的資料物件。若要複製資料，請使用其中一個 GetData 方法來擷取包含原始資料的 Object ，然後使用其中一個 SetData 方法將資料新增至新的資料物件。
以新的資料物件取代舊的資料物件。

注意

SetData 方法只會將資料新增至資料物件；即使資料和資料格式與先前的呼叫完全相同，方法也不會取代資料。呼叫 SetData 兩次相同的資料和資料格式時，會導致資料/資料格式在資料物件中出現兩次。

共用方式為