window.runtime 属性window.runtime.flash.desktop.Clipboard
继承Clipboard Inheritance Object

Clipboard 类提供用于通过剪贴板和拖放操作传输数据和对象的容器。通过静态 generalClipboard 属性可以访问操作系统剪贴板。

Clipboard 对象可以包含多种格式的相同信息。通过以多种格式提供信息,可以增加另一个应用程序能够使用该信息的机会。使用 setData()setDataHandler() 方法向 Clipboard 对象添加数据。

标准格式是:

用作这些格式的常量在 ClipboardFormats 类中定义。

在 AIR 应用程序和操作系统之间进行传输时,将在 JavaScript ActionScript 数据类型和本机剪贴板之间自动转换标准格式。

可以使用应用程序定义的格式将 JavaScript ActionScript 对象添加到 Clipboard 对象中。如果对象可序列化,则可以使用对该对象的引用和该对象的克隆。对象引用只在原始应用程序中有效。

如果将待传输的信息转换成特殊格式时运算成本很高,则可以提供执行该转换的函数名称。当且仅当接收组件或应用程序能够读取该格式时,才能调用此函数。使用 setDataHandler() 方法向 Clipboard 对象中添加延迟呈现函数。

注意:为 HTML 拖放事件和复制并粘贴事件调度的事件对象所引用的剪贴板对象与 AIR Clipboard 对象的类型不同。JavaScript 剪贴板对象在 AIR 开发人员指南中进行了说明。

另请参见

ClipboardFormats
ClipboardTransferMode


属性
 属性定义方
 Inheritedconstructor : Object
对类对象或给定对象实例的构造函数的引用。
Object
  formats : Array
[只读 (read-only)] 一个字符串数组,其中包含此 Clipboard 对象中的可用数据格式的名称。
Clipboard
  generalClipboard : Clipboard
[静态] [只读 (read-only)] 操作系统剪贴板。
Clipboard
 Inheritedprototype : Object
[静态] 对类或函数对象的原型对象的引用。
Object
公共方法
 方法定义方
  
创建空 Clipboard 对象。
Clipboard
  
从此 Clipboard 对象中删除所有数据表示形式。
Clipboard
  
clearData(format:String):void
删除指定格式的数据表示形式。
Clipboard
  
getData(format:String, transferMode:String):Object
如果指定格式的数据存在,则获取剪贴板数据。
Clipboard
  
hasFormat(format:String):Boolean
检查指定格式的数据在此 Clipboard 对象中是否存在。
Clipboard
 Inherited
hasOwnProperty(name:String):Boolean
指示对象是否已经定义了指定的属性。
Object
 Inherited
isPrototypeOf(theClass:Object):Boolean
指示 Object 类的实例是否在指定为参数的对象的原型链中。
Object
 Inherited
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
 Inherited
setPropertyIsEnumerable(name:String, isEnum:Boolean = true):void
设置循环操作动态属性的可用性。
Object
 Inherited
toString():String
返回指定对象的字符串表示形式。
Object
 Inherited
valueOf():Object
返回指定对象的原始值。
Object
属性详细信息
formats属性
formats:Array  [只读 (read-only)]

一个字符串数组,其中包含此 Clipboard 对象中的可用数据格式的名称。

用作标准格式名称的字符串常量在 ClipboardFormats 类中定义。应用程序定义的其他字符串也可以用作要作为对象传输的数据的格式名称。

另请参见


示例
下面的示例读取系统剪贴板的 formats 数组:
 var availableFormats = air.Clipboard.generalClipboard.formats;
generalClipboard属性 
generalClipboard:Clipboard  [只读 (read-only)]

操作系统剪贴板。

粘贴到系统剪贴板中的任何数据均对其他应用程序可用。这可能包括网络浏览器中运行的不安全的远程代码。

generalClipboard 对象是自动创建的。不能为此属性分配 Clipboard 的另一个实例。改用 getData()setData() 方法可以读取现有对象中的数据和将数据写入现有对象。

在向剪贴板中写入新数据之前,应始终清理剪贴板,以确保擦除所有格式的旧数据。


示例
如何使用示例
构造函数详细信息
Clipboard()构造函数
function Clipboard()

创建空 Clipboard 对象。

另请参见


示例

下例创建一个用于 air.NativeDragManager 类的新剪贴板。

注意:对于涉及操作系统剪贴板的复制并粘贴操作,请使用 air.Clipboard.generalClipboard 对象,而不要创建新剪贴板。

 
 var clipboard = new air.Clipboard();
方法详细信息
clear()方法
function clear():void

从此 Clipboard 对象中删除所有数据表示形式。


示例

下面的示例清除系统剪贴板:
 air.Clipboard.generalClipboard.clear();
clearData()方法 
function clearData(format:String):void

删除指定格式的数据表示形式。

参数

format:String — 要删除的数据格式。


示例

下例将清除系统剪贴板中任何 air.ClipboardFormats.TEXT_FORMAT 格式的数据:
 air.Clipboard.generalClipboard.clearData(air.ClipboardFormats.TEXT_FORMAT);
getData()方法 
function getData(format:String, transferMode:String):Object

如果指定格式的数据存在,则获取剪贴板数据。

在访问标准数据格式时,将会以相应 AIR 类型的新对象的形式返回数据。

在访问应用程序定义的格式时,transferMode 参数的值确定是返回对原始对象的引用,还是返回包含原始对象的序列化副本的匿名对象。如果指定了 originalPreferredclonePreferred 模式,则当首选的版本不可用时,AIR 将返回替代版本。如果指定了 originalOnlycloneOnly 模式,则当请求的版本不可用时,AIR 将返回 undefined

参数

format:String — 要返回的数据格式。格式字符串可以包含 ClipboardFormats 类中定义的标准名称之一,也可以包含一个应用程序定义的名称。
 
transferMode:String (default = NaN) — 指定在访问应用程序定义的数据格式时是返回一个引用还是返回序列化副本。该值必须是 ClipboardTransferMode 类中定义的名称之一。对于标准数据格式,将忽略此值。

返回
Object — 一个类型与该数据格式相对应的对象。

另请参见


示例

下面的示例将读取系统剪贴板中的文本(如果可用):

 var pasteData = air.Clipboard.generalClipboard.getData(air.ClipboardFormats.TEXT_FORMAT);
hasFormat()方法 
function hasFormat(format:String):Boolean

检查指定格式的数据在此 Clipboard 对象中是否存在。

使用 ClipboardFormats 类中的常量以检查是否存在标准格式的数据。

参数

format:String — 要检查的格式类型.

返回
Boolean — 如果存在指定格式的数据,则为 true

另请参见


示例

下面的示例测试系统剪贴板以确定文本格式的数据是否可用:
if(air.Clipboard.generalClipboard.hasFormat(air.ClipboardFormats.TEXT_FORMAT)){
    //do something 
}
setData()方法 
function setData(format:String, data:Object, serializable:Boolean = true):Boolean

使用指定的数据格式添加要传输的信息的表示形式。

可以将相同信息的不同表示形式以不同格式添加到剪贴板,这可提高其他组件或应用程序利用可用数据的能力。例如,图像可以添加为位图数据以供图像编辑应用程序使用、添加为 Bitmap 对象供其他 AIR 应用程序使用以及添加为编码的 PNG 文件以便传输到本机文件系统。

data 参数必须是适用于指定格式的相应数据类型:

格式类型说明
ClipboardFormats.TEXT_FORMATString字符串数据。
ClipboardFormats.URL_FORMATStringURL 字符串
ClipboardFormats.HTML_FORMATStringHTML 字符串数据
ClipboardFormats.RICH_TEXT_FORMATByteArrayRTF 数据
ClipboardFormats.BITMAP_FORMATBitmapData位图数据
ClipboardFormats.FILE_LIST_FORMATFile 的数组文件数组
自定义格式名称任意对象引用和序列化克隆

自定义格式名称不能以“air:”或“flash:”开头。为了避免在使用自定义格式时发生命名冲突,您可能希望使用应用程序 ID 或包名称作为格式的前缀,如“com.example.applicationName.dataPacket”。

当在 AIR 应用程序内或 AIR 应用程序之间传输时,serializable 参数确定引用和副本是否都可用,或是否只有对象的引用才可用。将 serializable 设置为 true 可使该数据对象的引用和副本都可用。将 serializable 设置为 false 则只使对象引用可用。对象引用仅在当前应用程序中有效,因此,将 serializable 设置为 false 还意味着使用该格式的数据将对其他 AIR 应用程序不可用。组件可以通过在访问该格式的数据时设置适当的剪贴板传输模式来选择获取该对象的引用或获取该对象的副本。

注意:当在 AIR 应用程序外部粘贴或拖动数据时,标准格式始终转换成本机格式,因此,serializable 参数的值不影响采用标准格式的数据对于非 AIR 应用程序的可用性。

若要延迟呈现某一格式的数据,请改用 setDataHandler() 方法。如果同时使用 setData()setDataHandler() 方法添加具有相同格式名称的数据表示方式,则永远也不会调用该处理函数。

参数

format:String — 要添加的信息。
 
data:Object — 数据的格式。
 
serializable:Boolean (default = true) — 为可以序列化(和反序列化)的对象指定 true

返回
Boolean — 如果成功设置了数据,则为 true;否则为 false

引发
Error — 如果 dataundefined 值。

另请参见


示例

下面的示例以文本格式和 URL 格式向系统剪贴板中添加一个 URL:
 
 var urlString = "http://www.adobe.com";
 air.Clipboard.generalClipboard.setData(air.ClipboardFormats.TEXT_FORMAT, urlString);
 air.Clipboard.generalClipboard.setData(air.ClipboardFormats.URL_FORMAT, urlString);
setDataHandler()方法 
function setDataHandler(format:String, handler:Function, serializable:Boolean = true):Boolean

添加对某个处理函数的引用,该函数根据需要生成指定格式的数据。使用此方法可将数据的创建或呈现延迟到实际访问数据时。

处理函数必须返回适合指定格式的相应数据类型:

格式返回类型
ClipboardFormats.TEXT_FORMATString
ClipboardFormats.URL_FORMATString
ClipboardFormats.HTML_FORMATString
ClipboardFormats.RICH_TEXT_FORMATByteArray
ClipboardFormats.BITMAP_FORMATBitmapData
ClipboardFormats.FILE_LIST_FORMATFile 的数组
自定义格式名称非 void

当且仅当读取指定格式的数据时才会调用该处理函数。请注意,在添加处理函数时和读取数据时之间,基础数据可能会发生更改,除非应用程序采取保护数据的措施。多次读取剪贴板中由处理函数表示的数据时发生的行为没有保证。AIR 可能会返回由第一个函数调用生成的数据,也可能会再次调用该函数。不要依赖任一行为。

若要直接向此 Clipboard 对象添加数据,请改用 setData() 方法。如果使用相同的格式名称调用 setData()setDataHandler() 方法,则永远也不会调用该处理函数。

参数

format:String — 调用时可返回要传输的数据的函数。
 
handler:Function — 数据的格式。
 
serializable:Boolean (default = true) — 如果由 handler 返回的对象可以序列化(和反序列化),则指定 true

返回
Boolean — 如果成功设置了处理函数,则为 true;否则为 false

引发
Error — 如果 dataundefined 值。

另请参见


示例

下面的示例通过延迟数据函数向系统剪贴板添加一个随机数。
 
 air.Clipboard.generalClipboard.setDataHandler(air.ClipboardFormats.TEXT_FORMAT, randomNumberGenerator);

 function randomNumberGenerator(){
     return Math.random();
 }