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 对象中。请注意，在某些情况下，操作系统在放置操作发生前调用此函数。例如，当使用处理函数为从 AIR 应用程序拖到文件系统的文件提供数据时，只要拖动手势一离开 AIR 应用程序，操作系统就立即调用数据处理函数 — 通常在下载或创建文件数据时导致意外暂停。

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

关于 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。为 AIR 应用程序中的本机拖放操作创建新的 Clipboard 对象。

实现
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`	`String`	字符串数据。
`ClipboardFormats.HTML_FORMAT`	`String`	HTML 字符串数据
`ClipboardFormats.URL_FORMAT`	`String`	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”。

当在应用程序内或 AIR 应用程序之间传输时，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 中，如果 format 是不受支持的 ClipboardFormats 成员，则返回 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`	`String`
`ClipboardFormats.HTML_FORMAT`	`String`
`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

当且仅当读取指定格式的数据时才会调用该处理函数。请注意，在某些情况下，操作系统在放置操作发生前调用此函数。例如，当使用处理函数为从 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