資料與資料物件

發行項
10/18/2023

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

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

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

資料物件

所有資料物件都必須實 IDataObject 作介面，其提供下列一組標準方法，以啟用並加速資料傳輸。

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

WPF 提供類別中的基本實 IDataObject 作 DataObject 。庫存 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

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

從資料物件擷取資料

從特定格式的資料物件擷取資料只牽涉到呼叫其中 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 兩次，會導致資料/資料格式出現在資料物件中兩次。

共用方式為