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

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的版本
  };
*/
});