ZeroClipboard 2.x API 全局对象的属性和方法 - CodePlayer

内容目录

以下是ZeroClipboard 2.x的API文档中关于全局对象ZeroClipboard的属性和方法(你可以理解为静态属性和静态方法)，以及全局事件类型及其属性的详细介绍。

ZeroClipboard 全局对象的属性和方法

以下没有标注返回值类型的方法，均表示该方法没有返回值(即 undefined)。

version

String类型返回当前使用的 ZeroClipboard 的版本号，例如 "2.1.6"。

config(...)

任意类型设置或返回 ZeroClipboard 的配置选项。具体的配置选项请参见这里。

// 用法一
var config = ZeroClipboard.config(); // 获取对象形式的所有配置选项(副本)
// 用法二
var swfPath = ZeroClipboard.config("swfPath"); // 获取某个具体的配置选项
// 用法三
var config = ZeroClipboard.config( {
	forceHandCursor: true ,
	title: "点击复制"
} ); // 以对象形式设置配置选项，并同时返回所有配置选项的新对象(副本)。

// 返回的包含所有配置选项的对象都是副本，对其进行操作不会影响ZeroClipboard中的配置选项

create()

创建 Flash bridge SWF 对象。注意：该方法应该被认为是私有的，不建议用户直接访问。

destroy()

触发destroy事件，删除所有事件处理器，并销毁Flash bridge。

setData(...)

设置用于复制的数据，可以设置多种格式(MIME类型)的数据，如果接收粘贴的程序支持对应的MIME类型，就会在粘贴时粘贴对应类型的数据。

// 其用法如下：其中type表示MIME类型，data表示用于复制的数据
ZeroClipboard.setData(type, data);

// 例如：
ZeroClipboard.setData("text/plain", "用于<复制>的文本数据");
ZeroClipboard.setData("text/html", "用于&lt;复制&gt;的文本数据");

getData(...)

String/Object类型获取用于复制的数据。

// 用法一
var text = ZeroClipboard.getData("text/html"); //获取用于复制的"text/html"类型的数据
// 用法二
var dataObj = ZeroClipboard.getData(); //获取用于复制的所有类型的数据，并以对象形式返回(副本)

clearData(...)

清空剪贴板中的数据。

// 用法一
ZeroClipboard.clearData(); // 清空剪贴板中所有类型的数据
// 用法二
ZeroClipboard.clearData("text/plain"); // 清空剪贴板中"text/plain"类型的数据

focus(...) & activate(...)

focus()和activate()方法是相同的。用于通过移动Flash SWF 对象到指定的元素上来暂时聚焦/"激活"该元素。激活后，点击该元素可以进行一次复制操作，但仅有一次，之后Flash SWF 对象将从该元素上移除。

activate()是focus()方法的别名，请优先使用focus()方法，activate()主要用于向后兼容。

// 激活该元素
ZeroClipboard.focus( document.getElementById("d_clip_button") );

blur() && deactivate()

与focus()和activate()方法相对，用于让当前"激活"的元素失去焦点(取消"激活")。deactivate()是blur()的别名。

activeElement()

Element类型返回当前被激活的元素，如果没有则返回null。

var btn = document.getElementById("d_clip_button");
ZeroClipboard.focus( btn );
var activeEl = ZeroClipboard.activeElement();  // activeEl === btn

state()

Object类型状态检测方法，用于检测浏览器、Flash 和 ZeroClipboard 的状态。其内容大致如下：

var state = ZeroClipboard.state();
/*
state = {
	browser : {
		appName: "Netscape"
		platform: "Win32"
		userAgent: "Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/32.0.1700.76 Safari/537.36"
	},
	flash : {
		deactivated: false
		disabled: false
		outdated: false
		overdue: false
		pluginType: "pepper"
		ready: true
		unavailable: false
		version: "12.0.0"
	},
	zeroclipboard : {
		config: Object // 包含所有配置选项的对象副本
		version: "2.1.6"
	}
}
*/

isFlashUnavailable()

Boolean类型检测Flash是否明确不可用(包括禁用、过时、不可用、无效等)。注意：该方法应该被看作私有的，一般无需用户去检测。

on(...)

为 ZeroClipboard 的全局事件绑定事件处理函数。支持的事件有"ready"、 "beforecopy"、 "copy"、 "aftercopy"、 "destroy"、 "error"，详情参见下面。

var listenerFn = function(e) { var ZeroClipboard = this; /* ... */ };
// 为ready事件绑定处理函数，函数内部的this指向全局对象ZeroClipboard
ZeroClipboard.on("ready", listenerFn);

var listenerObj = {
    handleEvent: function(e) { var listenerObj = this; /* ... */ }
};
// 为error事件绑定包含处理函数在内的对象，对象属性名称必须是handleEvent，否则无效。
// 处理函数内部的this指向该函数所在对象
ZeroClipboard.on("error", listenerObj);

// 同时为多个事件绑定相同的处理函数
ZeroClipboard.on("ready error", function(e) { /* ... */ });

// 以对象形式同时为多个事件绑定不同的处理函数
ZeroClipboard.on({
    "ready": function(e) { /* ... */ },
    "error": function(e) { /* ... */ }
});

// 同一个事件都可以多次调用，从而绑定多个处理函数

off(...)

解除之前为 ZeroClipboard 绑定的全局事件处理函数。

// 解除ready事件上绑定的listenerFn函数
ZeroClipboard.off("ready", listenerFn);
// 解除ready事件上绑定的listenerObj对象
ZeroClipboard.off("error", listenerObj);

// 解除多个事件上绑定的同一listenerFn函数
ZeroClipboard.off("ready error", listenerFn);

// 同时解除多个事件上绑定的不同函数
ZeroClipboard.off({
    "ready": readyListenerFn,
    "error": errorListenerFn
});

// 解除ready事件上绑定的所有事件处理函数或对象
ZeroClipboard.off("ready");

// 解除所有事件的所有绑定
ZeroClipboard.off();

emit(...)

手动触发 ZeroClipboard 的全局事件，会触发该事件上注册的所有事件处理函数。

// 触发ready事件
ZeroClipboard.emit("ready");

// 触发error事件
// 这里的name属性是 ZeroClipboard 内部定义的错误类型名称，表示Flash被禁用或未安装。此外还有flash-outdated(版本过低)、 flash-unavailable(无法与JS交互)、 flash-deactivated(未激活)、 flash-overdue(加载Flash SWF超时)。
ZeroClipboard.emit({
    type: "error",
    name: "flash-disabled"
});

// 只有触发copy事件时，会返回被复制的数据
// 由于Flash 10+的安全限制因素，将无法通过代码触发beforecopy、copy、aftercopy等事件
var copyData = ZeroClipboard.emit("copy");

handlers(...)

Array/Object类型返回 ZeroClipboard 中指定全局事件绑定的事件处理函数或对象的副本。

// 以数组形式返回ready事件的所有事件处理函数或对象
var listeners = ZeroClipboard.handlers("ready");

// 以对象形式返回所有事件的所有事件处理函数或对象
var listenersObj = ZeroClipboard.handlers();

事件处理及其属性细节

ready 事件

当Flash SWF文件加载完成并准备就绪时触发ready事件。请注意，你必须在 ZeroClipboard.create()方法被自动调用前设置大多数配置选项，否则你无法在之后更改这些选项。

ZeroClipboard.on("ready", function(e) {
/*
e = {
	type: "ready",
	message: "Flash communication is established",
	target: null,
	relatedTarget: null,
	currentTarget: flashSwfObjectRef,
	version: "11.2.202",
	timeStamp: Date.now()
};
*/

beforecopy 事件

在点击时，Flash对象会触发 beforecopy 事件。这是一个同步事件，只有你指定的处理操作完成后，才会触发copy事件。

ZeroClipboard.on("beforecopy", function(e) {
/*
e = {
	type: "beforecopy",
	target: currentlyActivatedElementOrNull,
	relatedTarget: dataClipboardElementTargetOfCurrentlyActivatedElementOrNull,
	currentTarget: flashSwfObjectRef,
	timeStamp: Date.now()
};
*/

copy 事件

当点击时，Flash 对象会触发copy事件(在beforecopy之后触发)。你可以通过事件对象e.clipboardData.setData()方法来设置用于复制的数据。

ZeroClipboard.on("copy", function(e) {
/*
e = {
	type: "copy",
	target: currentlyActivatedElementOrNull,
	relatedTarget: dataClipboardElementTargetOfCurrentlyActivatedElementOrNull,
	currentTarget: flashSwfObjectRef,
	timeStamp: Date.now(),
	clipboardData: {
	 setData: ZeroClipboard.setData,
	 clearData: ZeroClipboard.clearData
	}
};
*/
});

aftercopy 事件

当数据被复制到剪贴板后，触发该事件。

ZeroClipboard.on("aftercopy", function(e) {
/*
  e = {
    type: "aftercopy",
    target: currentlyActivatedElementOrNull,
    relatedTarget: dataClipboardElementTargetOfCurrentlyActivatedElementOrNull,
    currentTarget: flashSwfObjectRef,
    timeStamp: Date.now(),
    success: {
      "text/plain": true,
      "text/html": true,
      "application/rtf": false
    },
    data: {
      "text/plain": "Blah",
      "text/html": "<b>Blah</b>",
      "application/rtf": "{\\rtf1\\ansi\n{\\b Blah}}"
    }
  };
*/
});

destroy 事件

当ZeroClipboard.destroy()被调用时触发该事件。ZeroClipboard 会确保该事件的处理函数执行完后才完成销毁操作。

ZeroClipboard.on("destroy", function(e) {
/*
  e = {
    type: "destroy",
    target: null,
    relatedTarget: null,
    currentTarget: flashSwfObjectRef,
    timeStamp: Date.now(),
    success: {
      "text/plain": true,
      "text/html": true,
      "application/rtf": false
    },
    data: {
      "text/plain": "Blah",
      "text/html": "<b>Blah</b>",
      "application/rtf": "{\\rtf1\\ansi\n{\\b Blah}}"
    }
  };
*/
});

error 事件

当满足一系列条件时触发该事件，一般是出现错误时触发该事件。

// 由于错误有多种，因此事件对象的属性值和个数也不固定，其他错误类型多一个version属性
ZeroClipboard.on("error", function(e) {
/*
  e = {
    type: "error",
    name: "flash-disabled",
    messsage: "Flash is disabled or not installed",
    target: null,
    relatedTarget: null,
    currentTarget: flashSwfObjectRef,
    timeStamp: Date.now(),
    minimumVersion: "11.0.0"
//  ,version: "10.3.183" // 其他错误类型具有该属性，表示当前Flash的版本
  };
*/
});

CodePlayer

原创 ZeroClipboard 2.x API 全局对象的属性和方法

内容目录

ZeroClipboard 全局对象的属性和方法

version

config(...)

create()

destroy()

setData(...)

getData(...)

clearData(...)

focus(...) & activate(...)

blur() && deactivate()

activeElement()

state()

isFlashUnavailable()

on(...)

off(...)

emit(...)

handlers(...)

事件处理及其属性细节

ready 事件

beforecopy 事件

copy 事件

aftercopy 事件

destroy 事件

error 事件

0 条评论

原创 ZeroClipboard 2.x API 全局对象的属性和方法

内容目录

ZeroClipboard 全局对象的属性和方法

version

config(...)

create()

destroy()

setData(...)

getData(...)

clearData(...)

focus(...) & activate(...)

blur() && deactivate()

activeElement()

state()

isFlashUnavailable()

on(...)

off(...)

emit(...)

handlers(...)

事件处理及其属性细节

ready 事件

beforecopy 事件

copy 事件

aftercopy 事件

destroy 事件

error 事件

0 条评论

撰写评论