Clipboard

套件	flash.desktop
類別	public class Clipboard
繼承	Clipboard Object

語言版本:

ActionScript 3.0

執行階段版本:

Flash Player 10, AIR 1.0

Clipboard 類別會提供透過剪貼簿來傳輸資料與物件所需的容器。作業系統的剪貼簿可以透過靜態 generalClipboard 屬性存取。

Clipboard 物件可能會以一種以上的格式包含相同的資訊。以多種格式提供資訊，讓您給予其他應用程式更多機會來使用該資訊。請使用 setData() 或 setDataHandler() 方法，將資料加入 Clipboard 物件。

標準格式如下：

BITMAP_FORMAT：一種 BitmapData 物件 (僅限 AIR)
FILE_LIST_FORMAT：File 物件的陣列 (僅限 AIR)
HTML_FORMAT：格式為 HTML 的字串資料
TEXT_FORMAT：字串資料
RICH_TEXT_FORMAT：內含 RTF 格式資料的 ByteArray
URL_FORMAT：URL 字串 (僅限 AIR)

這些具有標準格式名稱的常數是在 ClipboardFormats 類別中定義。

傳送至作業系統或者從作業系統傳送時，會在 ActionScript 資料類型和原生作業系統剪貼簿類型之間自動轉譯標準格式。

您可以使用應用程式所定義的格式，將 ActionScript 物件加入 Clipboard 物件。若某個物件可以序列化，便可以製作此物件的參考和副本。物件參考只有在原始應用程式內才有效。

如果將資訊轉換成以特定格式傳輸的運算成本很昂貴，您可以提供執行轉換的函數名稱。只有當該格式由接收的組件或應用程式所讀取時，才會呼叫此函數。請使用 setDataHandler() 方法，將延遲的顯示函數加入 Clipboard 物件。注意：在某些情況下，作業系統會在放置之前，先呼叫此函數。例如，當您使用 handler 函數，為從 AIR 應用程式拖曳至檔案系統的檔案提供資料，作業系統會在拖曳手勢離開 AIR 應用程式時，立即呼叫資料處理常式 — 通常會在資料下載和建立時，造成意外的暫停。

AIR 應用程式注意事項：傳送給 HTML 拖放和複製及貼上事件的事件物件所參考的剪貼簿物件與 AIR Clipboard 物件的類型不同。AIR 開發人員手冊中有描述 JavaScript 剪貼簿物件。

Flash Player 應用程式中注意事項：在 Flash Player 10 中，必須先有使用者事件 (例如「貼上」命令的鍵盤快速鍵，或在快顯選單的「貼上」命令上按下滑鼠)，才能進行從剪貼簿貼上的作業。只有當 InteractiveObject 已經收到並開始處理貼上事件時，Clipboard.getData() 才會傳回剪貼簿內容。在任何其他情況下呼叫 Clipboard.getData() 都不會成功。在 AIR 中，相同的限制也適用於應用程式安全執行程序之外的內容。

在 Linux 上，當 AIR 應用程式關閉時，剪貼簿資料不會持續存在。

檢視範例

公用屬性

隱藏繼承公用屬性

顯示繼承公用屬性

	屬性		定義自
		constructor : Object 類別物件的參照或是特定物件實體的建構函數。	Object
		formats : Array [唯讀] 字串陣列，內含此 Clipboard 物件中可用的資料格式名稱。	Clipboard
		generalClipboard : Clipboard [靜態] [唯讀] 作業系統剪貼簿。	Clipboard
		supportsFilePromise : Boolean [唯讀] 指出用戶端系統是否支援檔案承諾剪貼簿格式。	Clipboard

公用方法

隱藏繼承公用方法

顯示繼承公用方法

	方法		定義自
		Clipboard() 建立空的 Clipboard 物件。	Clipboard
		clear():void 刪除此 Clipboard 物件中的所有資料形式。	Clipboard
		clearData(format:String):void 刪除指定格式的資料形式。	Clipboard
		getData(format:String, transferMode:String = "originalPreferred"):Object 如果存在指定格式的資料，則取回剪貼簿資料。	Clipboard
		hasFormat(format:String):Boolean 檢查此 Clipboard 物件中是否存在指定之格式的資料。	Clipboard
		hasOwnProperty(name:String):Boolean 指出物件是否有已定義的指定屬性。	Object
		isPrototypeOf(theClass:Object):Boolean 指出 Object 類別的實體是否位於指定為參數的物件原型鏈中。	Object
		propertyIsEnumerable(name:String):Boolean 指出指定的屬性是否存在，以及是否可列舉。	Object
		setData(format:String, data:Object, serializable:Boolean = true):Boolean 加入要以指定資料格式進行傳輸的資訊形式。	Clipboard
		setDataHandler(format:String, handler:Function, serializable:Boolean = true):Boolean 將參考加到處理常式函數 – 它負責產生傳送時所需的資料。	Clipboard
		setPropertyIsEnumerable(name:String, isEnum:Boolean = true):void 為迴圈作業設定動態屬性的可用性。	Object
		toLocaleString():String 傳回代表此物件的字串，根據地區特定慣例進行格式化。	Object
		toString():String 會傳回指定之物件的字串形式。	Object
		valueOf():Object 會傳回指定之物件的基本值。	Object

屬性詳細資訊

formats

屬性

formats:Array [唯讀]

語言版本:

ActionScript 3.0

執行階段版本:

Flash Player 10, AIR 1.0

字串陣列，內含此 Clipboard 物件中可用的資料格式名稱。

具有標準格式名稱的字串常數是在 ClipboardFormats 類別中定義。要傳輸的資料為物件時，應用程式定義的其他字串也可以當做格式名稱使用。

實作
public function get formats():Array

相關 API 元素

flash.desktop.ClipboardFormats

範例 ( 如何使用本範例 )

下列程式碼將讀取系統剪貼簿的 formats 陣列：

 var availableFormats:Array = Clipboard.generalClipboard.formats;

generalClipboard

屬性

generalClipboard:Clipboard [唯讀]

語言版本:

ActionScript 3.0

執行階段版本:

Flash Player 10, AIR 1.0

作業系統剪貼簿。

任何貼至系統剪貼簿中的資料都可以供其他應用程式使用，其中可能包含在網頁瀏覽器中執行的不安全遠端程式碼。

注意：在 Flash Player 10 應用程式中，必須先有使用者事件 (例如「貼上」命令的鍵盤快速鍵，或在快顯選單的「貼上」命令上按下滑鼠)，才能進行從剪貼簿貼上的作業。只有當 InteractiveObject 已經收到並開始處理貼上事件時，Clipboard.getData() 才會傳回剪貼簿內容。在任何其他情況下呼叫 Clipboard.getData() 都不會成功。在 AIR 中，相同的限制也適用於應用程式安全執行程序之外的內容。

generalClipboard 物件會自動建立，您無法將 Clipboard 的其他實體指派給此屬性。因此，請改用 getData() 和 setData() 方法，對現有的物件讀取和寫入資料。

您一定要先清除剪貼簿，再於其中寫入新的資料，如此可確保已消除所有格式的舊資料。

generalClipboard 物件不能傳遞給 AIR NativeDragManager。建立新的 Clipboard 物件供 AIR 應用程式的原生拖放作業使用。

實作
public static function get generalClipboard():Clipboard

範例 ( 如何使用本範例 )

若要寫入作業系統剪貼簿：

 import flash.desktop.ClipboardFormats;
 
 var copy:String = "A string to copy to the system clipboard.";
 Clipboard.generalClipboard.clear();
 Clipboard.generalClipboard.setData(ClipboardFormats.TEXT_FORMAT, copy);

若要讀取作業系統剪貼簿：

 import flash.desktop.ClipboardFormats;
 
 var pasteData:String  = Clipboard.generalClipboard.getData(ClipboardFormats.TEXT_FORMAT) as String;

supportsFilePromise

屬性

supportsFilePromise:Boolean [唯讀]

語言版本:

ActionScript 3.0

執行階段版本:

AIR 2

指出用戶端系統是否支援檔案承諾剪貼簿格式。

實作
public function get supportsFilePromise():Boolean

建構函式詳細資料

()

建構函式

public function Clipboard()

語言版本:

ActionScript 3.0

執行階段版本:

Flash Player 10, AIR 1.0

建立空的 Clipboard 物件。

建立 Clipboard 物件保存在 Adobe AIR 中原生拖放手勢的資料。Clipboard 物件只能用於一個拖放手勢，無法重複使用。

請勿建立 Clipboard 物件用於複製與貼上作業。請改為使用單一 Clipboard.generalClipboard 物件。

擲回值

IllegalOperationError — Flash Player 不支援 new Clipboard()，因為 Flash Player 只能使用作業系統的剪貼簿。針對作業系統剪貼簿中涉及的複製與貼上作業，請使用 Clipboard.generalClipboard 物件，而非建立新的 Clipboard 物件。不會在 AIR 應用程式中擲回錯誤。

相關 API 元素

generalClipboard

範例 ( 如何使用本範例 )

下列程式碼將建立新的剪貼簿以搭配 NativeDragManager 類別使用。

注意：針對作業系統剪貼簿中涉及的複製與貼上作業，請使用 Clipboard.generalClipboard 物件，而非建立新的剪貼簿。

 import flash.desktop.Clipboard;
 
 var clipboard:Clipboard = new Clipboard();

方法詳細資訊

clear

()

方法

public function clear():void

語言版本:

ActionScript 3.0

執行階段版本:

Flash Player 10, AIR 1.0

刪除此 Clipboard 物件中的所有資料形式。

擲回值

SecurityError — 本內容不允許呼叫 generalClipboard.clear()。在 Flash Player 中，只有在處理使用者事件 (例如，按下按鍵或按下滑鼠) 期間，才能成功呼叫這個方法。在 AIR 中，這項限制僅適用於應用程式安全執行程序外的內容。

範例 ( 如何使用本範例 )

下列程式碼將清除系統剪貼簿：

 Clipboard.generalClipboard.clear();

clearData

()

方法

public function clearData(format:String):void

語言版本:

ActionScript 3.0

執行階段版本:

Flash Player 10, AIR 1.0

刪除指定格式的資料形式。

參數

format:String — 要移除的資料格式。

擲回值

SecurityError — 本內容不允許呼叫 generalClipboard.clearData()。在 Flash Player 中，只有在處理使用者事件 (例如，按下按鍵或按下滑鼠) 期間，才能成功呼叫這個方法。在 AIR 中，這項限制僅適用於應用程式安全執行程序外的內容。

範例 ( 如何使用本範例 )

下列範例將清除系統剪貼簿中具有 ClipboardFormats.TEXT_FORMAT 格式的所有資料：

 import flash.desktop.ClipboardFormats;
 
 Clipboard.generalClipboard.clearData(ClipboardFormats.TEXT_FORMAT);

getData

()

方法

public function getData(format:String, transferMode:String = "originalPreferred"):Object

語言版本:

ActionScript 3.0

執行階段版本:

Flash Player 10, AIR 1.0

如果存在指定格式的資料，則取回剪貼簿資料。

Flash Player 需要在 paste 事件處理常式中呼叫 getData() 方法。在 AIR 中，這項限制僅適用於應用程式安全執行程序外的內容。

存取標準資料格式時，此資料會當作新的物件 (其類型為對應的 Flash 資料類型) 傳回。

存取應用程式定義的格式時，transferMode 參數會判斷傳回的是原始物件的參考，還是包含原始物件之已序列化副本的匿名物件。指定 originalPreferred 或 clonePreferred 模式時，如果沒有偏好使用的版本，Flash Player 或 AIR 將傳回替代版本。指定 originalOnly 或 cloneOnly 模式時，如果無法使用要求的版本，Flash Player 或 AIR 將傳回 null。

參數

	`format:String` — 要傳回的資料格式。此格式字串可包含 ClipboardFormats 類別內定義的其中一個標準名稱，或應用程式定義的名稱。

	`transferMode:String` (default = "`originalPreferred`") — 指定在存取應用程式定義的資料格式時，要傳回參考還是已序列化的副本。此值必須是在 ClipboardTransferMode 類別內定義的其中一個名稱：若為標準資料格式，此值會遭忽略。系統一律會傳回副本。

傳回值

Object — 其類型對應至該資料格式的物件。

擲回值

	`Error` — `transferMode` 不是 ClipboardTransferMode 類別中定義的名稱之一。

	`IllegalOperationError` — 要求的 Clipboard 物件已經不在範圍內 (僅限 AIR)。

	`SecurityError` — 在此情況下，不允許從剪貼簿讀取，或是寫入剪貼簿。在 Flash Player 中，您只能在處理 `paste` 事件時，成功呼叫此方法。在 AIR 中，這項限制僅適用於應用程式安全執行程序外的內容。

範例 ( 如何使用本範例 )

下列範例將從系統剪貼簿讀取文字 (如果有的話)：

 import flash.desktop.ClipboardFormats;

 var pasteData:String = Clipboard.generalClipboard.getData(ClipboardFormats.TEXT_FORMAT) as String;

hasFormat

()

方法

public function hasFormat(format:String):Boolean

語言版本:

ActionScript 3.0

執行階段版本:

Flash Player 10, AIR 1.5

檢查此 Clipboard 物件中是否存在指定之格式的資料。

您可以使用 ClipboardFormats 類別中的常數來參考標準格式名稱。

參數

format:String — 要檢查的格式類型.

傳回值

Boolean — true 表示存在指定之格式的資料。

擲回值

	`IllegalOperationError` — 要求的 Clipboard 物件已經不在範圍內。

	`SecurityError` — 在此情況下，不允許從剪貼簿讀取，或是寫入剪貼簿。

相關 API 元素

flash.desktop.ClipboardFormats

範例 ( 如何使用本範例 )

下列程式碼將測試系統剪貼簿，判斷是否有格式為文字的資料：

if(Clipboard.generalClipboard.hasFormat(ClipboardFormats.TEXT_FORMAT)){
    //do something 
}

setData

()

方法

public function setData(format:String, data:Object, serializable:Boolean = true):Boolean

語言版本:

ActionScript 3.0

執行階段版本:

Flash Player 10, AIR 1.0

加入要以指定資料格式進行傳輸的資訊形式。

在 Adobe AIR 的執行程序中，可以隨時呼叫 setData()。在其他情況中，只有在回應使用者事件 (例如，按下某個按鍵或滑鼠)，才可以呼叫 setData()。

同一個資訊的不同形式可以使用不同格式加入剪貼簿中，如此可提高其他組件或應用程式使用該可用資料的機會。例如，您可以加入影像做為點陣圖資料供影像編輯應用程式使用，或是做為 URL 使用，以及做為已編碼的 PNG 檔案供傳輸至原生檔案系統。

data 參數必須是指定之格式的適當資料類型：

格式	類型	說明
`ClipboardFormats.TEXT_FORMAT`	`字串`	字串資料
`ClipboardFormats.HTML_FORMAT`	`字串`	HTML 字串資料
`ClipboardFormats.URL_FORMAT`	`字串`	URL 字串 (僅限 AIR)
`ClipboardFormats.RICH_TEXT_FORMAT`	`ByteArray`	RTF 格式資料
`ClipboardFormats.BITMAP_FORMAT`	`BitmapData`	點陣圖資料 (僅限 AIR)
`ClipboardFormats.FILE_LIST_FORMAT`	`File` 的陣列	以及檔案陣列 (僅限 AIR)
自訂格式名稱	任何	物件參考和已序列化的副本

自訂格式的名稱不能以「air:」或「flash:」做為開頭。使用自訂格式時若要避免命名衝突，您可以使用自己的應用程式 ID 或套件名稱做為格式的前置詞，例如「com.example.applicationName.dataPacket」。

在應用程式內部或之間進行傳輸時，serializable 參數可以決定物件的參考和副本都可用，還是只有參考可用。將 serializable 設定為 true 表示資料物件的參考和副本都可用；將 serializable 設定為 false 表示只有物件參考可用。由於物件參考只有在目前的應用程式中才有效，因此將 serializable 設定為 false 也表示其他 Flash Player 或 AIR 應用程式將無法使用該格式的資料。存取該格式的資料時，藉由設定適當的剪貼簿傳輸模式，組件便可以選擇要取得該物件的參考還是副本。

注意：在支援的應用程式外面貼上或拖曳資料時，這些標準格式一定會轉換為原生格式，因此 serializable 參數的值不會讓非 Flash 應用程式無法使用標準格式的資料。

若要延遲顯示某種格式的資料，請改用 setDataHandler() 方法。如果使用 setData() 和 setDataHandler() 方法加入具有相同的格式名稱的資料形式，則永遠不會呼叫該處理常式函數。

注意：在 Mac OS 上，當您將 format 參數設定成 ClipboardFormats.URL_FORMAT 時，只有 URL 有效時才會予以傳送。否則，Clipboard 物件會被清空 (並呼叫 getData() 來傳回 null)。

參數

	`format:String` — 資料的格式。

	`data:Object` — 要加入的資訊。

	`serializable:Boolean` (default = `true`) — 對於可以序列化 (和還原序列化) 的物件，請指定 `true`。

傳回值

Boolean — true 表示資料已成功設定，否則為 false。在 Flash Player 中，當 ClipboardFormats 不支援 format 成員時，會傳回 false (Flash Player 不支援 ClipboardFormats.URL_FORMAT、ClipboardFormats.FILE_LIST_FORMAT、ClipboardFormats.FILE_PROMISE_LIST_FORMAT 或 ClipboardFormats.BITMAP_FORMAT)。

擲回值

	`IllegalOperationError` — 要求的 Clipboard 物件已不在範圍中 (為拖放作業建立剪貼簿時會發生此情況)。

	`SecurityError` — 在此情況下，不允許從剪貼簿讀取，或是寫入剪貼簿。在 Flash Player 中，只有在處理使用者事件 (例如，按下按鍵或按下滑鼠) 期間，才能成功呼叫這個方法。在 AIR 中，這項限制僅適用於應用程式安全執行程序外的內容。

	`TypeError` — `format` 或 `data` 為 `null`。

範例 ( 如何使用本範例 )

下列範例會以文字和 HTML 格式，將內容加入系統剪貼簿：

 import flash.desktop.ClipboardFormats;
 
 var htmlString:String = "<html><body>Body content</body></html>";
 Clipboard.generalClipboard.setData(ClipboardFormats.TEXT_FORMAT, urlString);
 Clipboard.generalClipboard.setData(ClipboardFormats.HTML_FORMAT, urlString);

setDataHandler

()

方法

public function setDataHandler(format:String, handler:Function, serializable:Boolean = true):Boolean

語言版本:

ActionScript 3.0

執行階段版本:

Flash Player 10, AIR 1.0

將參考加到處理常式函數 – 它負責產生傳送時所需的資料。

您可以使用此處理常式函數，延遲建立或顯示資料，直到實際存取該資料為止。

處理常式函數必須傳回指定之格式的適當資料類型：

格式	傳回類型
`ClipboardFormats.TEXT_FORMAT`	`字串`
`ClipboardFormats.HTML_FORMAT`	`字串`
`ClipboardFormats.URL_FORMAT`	`String` (僅限 AIR)
`ClipboardFormats.RICH_TEXT_FORMAT`	`ByteArray`
`ClipboardFormats.BITMAP_FORMAT`	`BitmapData` (僅限 AIR)
`ClipboardFormats.FILE_LIST_FORMAT`	`File` 的陣列 (僅限 AIR)
`ClipboardFormats.FILE_PROMISE_LIST_FORMAT`	`File` 的陣列 (僅限 AIR)
自訂格式名稱	非 void

只有在已讀取指定之格式的資料時，才會呼叫此處理常式函數。注意：在某些情況下，作業系統會在放置之前，先呼叫此函數。例如，當您使用 handler 函數，為從 AIR 應用程式拖曳至檔案系統的檔案提供資料，作業系統會在拖曳手勢離開 AIR 應用程式時，立即呼叫資料處理常式 — 通常會在資料下載和建立時，造成意外的暫停。您可以使用 URLFilePromise 得到相同的結果。

請注意，除非您的應用程式採取保護資料的步驟，否則在加入處理常式和讀取資料之間，基礎資料可能會變更。在處理常式函數所表示之剪貼簿上的資料讀取一次以上時所發生的行為指令，並不保證一定會發生。剪貼簿可能會傳回第一個函數呼叫所產生的資料，或者可能會再次呼叫此函數。請勿依賴任何一個行為指令。

在 Adobe AIR 的執行程序中，可以隨時呼叫 setDataHandler()。在其他情況中，只有在回應使用者事件 (例如，按下某個按鍵或滑鼠)，才可以呼叫 setDataHandler()。

若要直接將資料加入 Clipboard 物件，請改用 setData() 方法。如果使用相同的格式名稱呼叫 setData() 和 setDataHandler() 方法，則永遠都不會呼叫該處理常式函數。

注意：在 Mac OS 上，當您將 format 參數設定成 ClipboardFormats.URL_FORMAT，只有在處理常式函數傳回有效 URL 時，才會傳回 URL。否則，Clipboard 物件會被清空 (並呼叫 getData() 來傳回 null)。

參數

	`format:String` — 函數，可傳回要傳輸的資料。

	`handler:Function` — 資料的格式。

	`serializable:Boolean` (default = `true`) — 如果 `handler` 傳回的物件可以序列化 (和還原序列化)，請指定 `true`。

傳回值

Boolean — true 表示處理常式已成功設定，否則為 false。

擲回值

	`TypeError` — `format` 或 `handler` 為 `null`。

	`IllegalOperationError` — 要求的 Clipboard 物件已經不在範圍內 (僅限 AIR)。

	`SecurityError` — 在此情況下，不允許從剪貼簿讀取，或是寫入剪貼簿。在 Flash Player 中，只有在處理使用者事件 (例如，按下按鍵或按下滑鼠) 期間，才能成功呼叫這個方法。在 AIR 中，這項限制僅適用於應用程式安全執行程序外的內容。

相關 API 元素

setData()
flash.desktop.ClipboardFormats
flash.desktop.URLFilePromise

範例 ( 如何使用本範例 )

下列程式碼會透過延遲的資料函數，將隨機號碼加入系統剪貼簿：

 import flash.desktop.ClipboardFormats;
 
 Clipboard.generalClipboard.setDataHandler(ClipboardFormats.TEXT_FORMAT, randomNumberGenerator);

 public function randomNumberGenerator():String{
     return Math.random().toString();
 }

範例如何使用本範例

ClipboardExample.as

下列 Adobe AIR 範例，將使用 ClipboardExample 類別，透過系統剪貼簿從某個變數將一字串複製到其他變數。您可以執行下列步驟來完成這項工作：

將資料 (在此例中為字串) 寫入 Clipboard.generalClipboard。
從 Clipboard.generalClipboard 讀取剪貼簿內容。

注意：因為存取剪貼簿資料會有安全方面的限制，所以此範例在 Flash Player 中無效。在 Flash Player 中，您只可以在 paste 事件處理常式中，呼叫 Clipboard 物件的 getData() 方法。

package
{
    import flash.display.Sprite;
    import flash.desktop.Clipboard;
    import flash.desktop.ClipboardFormats;
    import flash.desktop.ClipboardTransferMode;

    public class ClipboardExample extends Sprite
    {
        public function ClipboardExample()
        {
            var sally:String = "Sally";
            var person:String;
            
            copy(sally);
            person = paste();
            trace(person); //traces: "Sally"
        }

        private function copy(text:String):void 
        {
            Clipboard.generalClipboard.clear();
            Clipboard.generalClipboard.setData(ClipboardFormats.TEXT_FORMAT, text);
        }
        
        private function paste():String
        {
            if(Clipboard.generalClipboard.hasFormat(ClipboardFormats.TEXT_FORMAT))
            {
                return String(Clipboard.generalClipboard.getData(ClipboardFormats.TEXT_FORMAT));
            } 
            else 
            {
                return null;
            }
        }
        
    }
}

法律聲明 | 線上隱私權政策

Clipboard - AS3

套件x

語言元素

附錄

套件 flash.desktop

formats

generalClipboard

supportsFilePromise

Clipboard

clear

clearData

getData

hasFormat

setData

setDataHandler