Clipboard 資料格式

Flash Player 10 以及更新的版本,Adobe AIR 1.0 以及更新的版本

Clipboard 格式描述了放置在 Clipboard 物件中的資料。Flash Player 或 AIR 會自動在 ActionScript 資料類型和系統剪貼簿格式之間轉譯標準資料格式。此外,您也可以利用應用程式定義的格式,在各個以 ActionScript 撰寫的應用程式之間轉換應用程式物件。

Clipboard 物件可以包含同一份資訊的各種不同格式表示形式。例如,表示 Sprite 的 Clipboard 物件可以包含參考格式 (可在相同應用程式中使用)、經過序列化的格式 (可供 Flash Player 或 AIR 中執行的其它應用程式使用)、點陣圖格式 (可供影像編輯程式使用) 以及可能具有延遲顯示功能以編碼 PNG 檔的檔案清單格式 (用於將此 Sprite 的表示形式複製或拖曳到檔案系統)。

標準資料格式

ClipboardFormats 類別提供了定義標準格式名稱的常數:

常數

說明

TEXT_FORMAT

文字格式資料會和 ActionScript String 類別進行雙向轉譯。

HTML_FORMAT

帶有 HTML 標記的文字。

RICH_TEXT_FORMAT

RTF 格式資料會和 ActionScript ByteArray 類別進行雙向轉譯,但不會解譯或轉譯 RTF 標記。

BITMAP_FORMAT

(僅限 AIR) 具有點陣圖格式的資料會轉譯至/自 ActionScript 的 BitmapData 類別。

FILE_LIST_FORMAT

(僅限 AIR) 具有檔案清單格式的資料會轉譯至/自 ActionScript 的 File 物件陣列。

URL_FORMAT

(僅限 AIR) 具有 URL 格式的資料會轉譯至/自 ActionScript 的 String 類別。

在 AIR 應用程式載入的 HTML 內容中,基於回應 copycutpaste 事件而複製和貼上資料時,必須改用 MIME 類型來取代 ClipboardFormat 字串。有效的資料 MIME 類型如下:

MIME 類型

說明

文字

"text/plain"

URL

"text/uri-list"

點陣圖

"image/x-vnd.adobe.air.bitmap"

檔案清單

"application/x-vnd.adobe.air.file-list"

備註: HTML 內容中的 RTF 格式資料,無法透過 paste 事件發生時傳送之 event 物件的 clipboardData 屬性取得。

自訂資料格式

您可以使用應用程式定義的自訂格式來傳輸物件的參考或是已序列化的副本。參考只有在相同應用程式中才有效。經過序列化的物件則可在各個應用程式之間傳輸,但只能與序列化或還原序列化期間仍有效的物件搭配使用。物件的屬性若為簡單類型或是可以序列化的物件,通常即表示該物件可以序列化。

如果要將經過序列化的物件加入至 Clipboard 物件,請呼叫 Clipboard.setData() 方法,並將 serializable 參數設定為 true。格式名稱可以是某種標準格式,或是由應用程式定義的任意字串。

傳輸模式

使用自訂資料格式將物件寫入至剪貼簿時,可以從剪貼簿將物件資料當做參考來讀取,或當做原始物件的序列化副本來讀取。有四種傳輸模式,供您判斷物件傳輸形式是一項參考或已序列化的副本:

傳輸模式

說明

ClipboardTransferModes.ORIGINAL_ONLY

只傳回參考。若無法取得參考,則傳回 null 值。

ClipboardTransferModes.ORIGINAL_PREFFERED

若能取得參考便將其傳回,反之則傳回已序列化的副本。

ClipboardTransferModes.CLONE_ONLY

只傳回已序列化的副本。若無法取得已序列化的副本,則傳回 null 值。

ClipboardTransferModes.CLONE_PREFFERED

若能取得已序列化的副本便將其傳回。反之則傳回參考。

讀取與寫入自訂資料格式

在剪貼簿中寫入物件時,除了在 format 參數開頭保留當做前置詞使用的 air:flash: 以外,您可以使用任何字串。使用代表該格式的相同字串即可讀取物件。下列範例說明如何在剪貼簿中讀取與寫入物件:

public function createClipboardObject(object:Object):Clipboard{ 
    var transfer:Clipboard = Clipboard.generalClipboard; 
    transfer.setData("object", object, true); 
} 

若要從剪貼簿物件中擷取已序列化的物件 (在執行放入或貼上作業後),請使用相同的格式名稱以及 CLONE_ONLYCLONE_PREFFERED 轉換模式。

var transfer:Object = clipboard.getData("object", ClipboardTransferMode.CLONE_ONLY); 

參考一律會加入至 Clipboard 物件。若要 (在拖放或貼上作業之後) 從剪貼簿物件擷取參考,請使用 ORIGINAL_ONLYORIGINAL_PREFFERED 轉換模式,而不要使用經過序列化的副本:

var transferredObject:Object =  
    clipboard.getData("object", ClipboardTransferMode.ORIGINAL_ONLY); 

物件參考只有在 Clipboard 物件源自目前的應用程式時才有效。使用 ORIGINAL_PREFFERED 轉換模式,即可在參考可用時存取參考;而無法使用參考時,則存取經過序列化的副本。

延遲顯示

如果資料格式的建立較耗費運算資源,您可以利用延遲顯示函數視需要提供資料。當放入或貼上作業的接收者要求取得延遲的格式資料時,才會呼叫該函數。

請使用 setDataHandler() 方法,將延遲顯示函數加入 Clipboard 物件。函數必須傳回正確格式的資料。例如,若您呼叫了 setDataHandler(ClipboardFormat.TEXT_FORMAT, writeText),則 writeText() 函數必須傳回字串。

如果是使用 setData() 方法將相同類型的資料格式加入至 Clipboard 物件,則該資料的優先順序會大於延遲版本 (如此將永遠不會呼叫顯示函數)。即使二度存取同一份剪貼簿資料,也未必會再次呼叫延遲顯示函數。

備註: 在 Mac OS X 中,延遲顯示功能僅適用於自訂資料格式。使用標準資料格式時,則會立即呼叫顯示函數。

使用延遲顯示函數貼上文字

下列範例會說明如何實作延遲顯示函數。

當使用者按下「複製」按鈕時,應用程式會清除系統剪貼簿中的資料,確保不會留下任何之前剪貼簿作業所產生的資料。接著,setDataHandler() 方法會將 renderData() 函數設定為剪貼簿輸出器。

當使用者從目的地文字欄位的快顯選單選取「貼上」命令時,應用程式會存取剪貼簿並設定目的地文字。由於已經使用函數 (而非字串) 設定了剪貼簿中的文字資料格式,因此剪貼簿會呼叫 renderData() 函數。renderData() 函數傳回來源文字的內容,然後再指定給目標文字。

請注意,如果您編輯了來源文字後按「貼上」按鈕,貼上的文字就會反映編輯結果,即使您是在按下「複製」按鈕後才進行編輯也一樣。這是因為延遲顯示函數會等到您按「貼上」按鈕才複製來源文字 (若在實用性質的應用程式中使用延遲顯示函數,您可能需要設法儲存或保護來源文字以免發生此問題)。

Flash 範例

 package {  
    import flash.desktop.Clipboard; 
    import flash.desktop.ClipboardFormats; 
    import flash.desktop.ClipboardTransferMode; 
    import flash.display.Sprite; 
    import flash.text.TextField; 
    import flash.text.TextFormat; 
    import flash.text.TextFieldType; 
    import flash.events.MouseEvent; 
    import flash.events.Event; 
    public class DeferredRenderingExample extends Sprite  
    {  
         private var sourceTextField:TextField; 
        private var destination:TextField; 
        private var copyText:TextField; 
        public function DeferredRenderingExample():void 
        { 
            sourceTextField = createTextField(10, 10, 380, 90); 
            sourceTextField.text = "Neque porro quisquam est qui dolorem " 
                + "ipsum quia dolor sit amet, consectetur, adipisci velit."; 
                 
            copyText = createTextField(10, 110, 35, 20); 
            copyText.htmlText = "<a href='#'>Copy</a>"; 
            copyText.addEventListener(MouseEvent.CLICK, onCopy); 
 
            destination = createTextField(10, 145, 380, 90); 
            destination.addEventListener(Event.PASTE, onPaste); 
        } 
        private function createTextField(x:Number, y:Number, width:Number, 
                        height:Number):TextField 
        { 
            var newTxt:TextField = new TextField(); 
            newTxt.x = x; 
            newTxt.y = y; 
            newTxt.height = height; 
            newTxt.width = width; 
            newTxt.border = true; 
            newTxt.multiline = true; 
            newTxt.wordWrap = true; 
            newTxt.type = TextFieldType.INPUT; 
            addChild(newTxt); 
            return newTxt; 
        } 
        public function onCopy(event:MouseEvent):void 
        { 
            Clipboard.generalClipboard.clear(); 
            Clipboard.generalClipboard.setDataHandler(ClipboardFormats.TEXT_FORMAT, 
                            renderData); 
        } 
        public function onPaste(event:Event):void 
        { 
            sourceTextField.text = 
            Clipboard.generalClipboard.getData(ClipboardFormats.TEXT_FORMAT).toString; 
        } 
        public function renderData():String 
        { 
            trace("Rendering data"); 
            var sourceStr:String = sourceTextField.text; 
            if (sourceTextField.selectionEndIndex > 
                     sourceTextField.selectionBeginIndex) 
            { 
                return sourceStr.substring(sourceTextField.selectionBeginIndex, 
                                    sourceTextField.selectionEndIndex); 
            } 
            else 
            { 
                return sourceStr; 
            } 
        } 
    } 
}

Flex 範例

<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" layout="absolute" width="326" height="330" applicationComplete="init()"> 
    <mx:Script> 
    <![CDATA[ 
    import flash.desktop.Clipboard; 
    import flash.desktop.ClipboardFormats; 
     
    public function init():void 
    { 
        destination.addEventListener("paste", doPaste); 
    } 
 
    public function doCopy():void 
    { 
        Clipboard.generalClipboard.clear(); 
        Clipboard.generalClipboard.setDataHandler(ClipboardFormats.TEXT_FORMAT, renderData); 
    } 
    public function doPaste(event:Event):void 
    { 
        destination.text = Clipboard.generalClipboard.getData(ClipboardFormats.TEXT_FORMAT).toString; 
    } 
     
    public function renderData():String{ 
        trace("Rendering data"); 
        return source.text; 
    } 
    ]]> 
    </mx:Script> 
    <mx:Label x="10" y="10" text="Source"/> 
    <mx:TextArea id="source" x="10" y="36" width="300" height="100"> 
        <mx:text>Neque porro quisquam est qui dolorem ipsum quia dolor sit amet, consectetur, adipisci velit.</mx:text> 
    </mx:TextArea> 
    <mx:Label x="10" y="181" text="Destination"/> 
    <mx:TextArea id="destination"  x="12" y="207" width="300" height="100"/> 
    <mx:Button click="doCopy();" x="91" y="156" label="Copy"/> 
</mx:Application>