使用方法
载入 JavaScript 文件
<script src="ZeroClipboard.js"></script>
如果 ZeroClipboard.swf 与页面不在同一个目录下,可以设置路径
// 全局设置 ZeroClipboard.setDefaults({ moviePath: '/path/ZeroClipboard.swf' }); // 参数中设置 var clip=new ZeroClipboard(document.getElementById("copy-button"), { moviePath: '/path/ZeroClipboard.swf' });
调用
可以传递一个元素或者一个元素数组。(这里使用 jQuery 获取元素的方式)
// 直接调用 var clip=new ZeroClipboard($('#my-button'));
AMD
如果你使用 RequireJS, curl.js, seajs 等 AMD 规范的模块加载器,那么需要设置模块的 ID 或者路径的值到 amdModuleId,才能正常使用 ZeroClipboard。例:
define(['path/to/zero-clipboard'], function(ZeroClipboard){ ZeroClipboard.setDefaults({ amdModuleId: 'path/to/zero-clipboard' }); });
requirejs.config({ paths:{ "ZeroClipboard":"path/to/zero-clipboard" } }); define(["ZeroClipboard"],function(ZeroClipboard) { ZeroClipboard.setDefaults({ amdModuleId: 'ZeroClipboard' }); });
参数说明
new ZeroClipboard(elements [, options])
options 参数说明
名称 | 默认值 | 说明 |
---|---|---|
swfPath | "ZeroClipboard.swf" | Flash 文件路径,默认的 swf 文件路径与 ZeroClipboard.js 相同 |
trustedDomains | window.location.host ? [window.location.host] : [] | 可信任的域(字符串或者字符串的数组) |
cacheBust | true | |
forceEnhancedClipboard | false | |
flashLoadTimeout | 30000 | 加载 Flash 的超时时间,如果不需要,可以设置为 0。单位(ms) |
autoActivate | true | |
bubbleEvents | true | |
containerId | "global-zeroclipboard-html-bridge" | |
containerClass | "global-zeroclipboard-container" | |
swfObjectId | "global-zeroclipboard-flash-bridge" | |
hoverClass | "zeroclipboard-is-hover" | 鼠标移上时给元素增加的 Class |
activeClass | "zeroclipboard-is-active" | 选定是给元素增加的 Class |
forceHandCursor | false | |
title | null | |
zIndex | 999999999 |
参数 allowScriptAccess 选项的注意事项
1.1.7 及以下的版本,allowScriptAccess 的默认值为 always。意味着允许 "ZeroClipboard.swf" 文件托管的其他的域。为了提高安全性,1.1.7 之后的版本,allowScriptAccess 的默认值为 sameDomain,只允许 "ZeroClipboard.swf" 在相同域之下。
如果你是从 1.1.7 或更低的版本升级到 1.1.7 以上版本时,需要将 "ZeroClipboard.swf" 保存一份到相同域之下,或者设置 allowScriptAccess 的值为 always。
关于 allowScriptAccess 的更多信息,可以参考官方文档。
Data 属性
名称 | 说明 |
---|---|
data-clipboard-target | 元素ID。查找该元素后,尝试复制元素的 .value 或 .textContent 或 .innerText 的值 |
data-clipboard-text | 默认复制的内容。 |
同时设置 data-clipboard-target 和 data-clipboard-text 两个属性时,只有在找不到 clipboard-target 的值时才会选用 clipboard-text
即使获取到 clipboard-target 的值为空,也不会选用 clipboard-text
此外,我们甚至无需通过元素节点的属性来设置用于复制的文本数据,我们可以直接使用 ZeroClipboard 对象的setText()
方法来设置文本数据。注意,该方法设置的数据是一次性的,使用该方法设置复制数据后,只在下一次复制操作时生效。之后即使你点击复制按钮也不再执行复制,除非你再次调用setText()
方法(你可以绑定复制("copy")事件来调用该方法,从而实现每次复制操作都设置数据,下面我们会讲到)。
clip.setText("设置用于复制的文本内容");
数据来源的优先级问题:如果我们同时为复制载体设置了data-clipboard-text
、 data-clipboard-target
属性,并调用了setText()
方法,那么 ZeroClipboard 复制数据的优先级是:setText() > data-clipboard-target > data-clipboard-text。
如果前者没有文本数据(没有调用、 没有属性或者数据为空字符串),则以下一个优先级为准,如果都没有文本数据,则不复制。
举例来说,如果同时设置上述三者。第一次复制:先取setText()
设置的数据,如果为空字符串,则取data-clipboard-target
对应元素的数据;如果它也为空字符串,则取data-clipboard-text
属性的文本数据;如果它也为空字符串,则不复制。注意,由于setText()
设置的数据是一次性的,下一次复制将以data-clipboard-target
属性为准(除非再次调用setText()
方法)。
数据类型
众所周知,剪贴板中的数据是有类型的,每一种类型都可以有自己的数据。我们复制的数据可以有多种类型,当我们粘贴的时候,会粘贴当前程序可接受类型的数据。
ZeroClipboard也支持设置多种类型的剪贴板数据。它为我们提供了setText()、setHtml、setRichText()方法分别用于设置纯文本数据、HTML内容、富文本内容。
// 可同时设置,粘贴时根据接收程序的不同,而粘贴出不同的内容
clip.setText("CodePlayer");
clip.setHtml("<strong>CodePlayer</strong>");
clip.setRichText("{\\rtf1\\ansi\n{\\b CodePlayer}}");
此外,ZeroClipboard还提供了一个通用的设置方法setData()
,用于设置各种类型的数据。
// 可同时设置,粘贴时根据接收程序的不同,而粘贴出不同的内容
clip.setData("text/plain", "CodePlayer");
clip.seData("text/html", "<strong>CodePlayer</strong>");
clip.setData("application/rtf", "{\\rtf1\\ansi\n{\\b CodePlayer}}");
API 方法
名称 | 说明 |
---|---|
glue(dom) | 绑定到元素 |
reposition() | 调整位置 |
on("Event",my_load_handler) | 绑定事件 |
off("Event",my_load_handler) | 取消已绑定的事件 |
事件
通过 API 的方法 on() 来绑定
名称 | 示例 | 说明 |
---|---|---|
load | clip.on("load",function(client,args){...}); | Flash 加载完成时的事件。args 参数包含以下属性: flashVersion:当前 Flash 的版本号 |
mouseover | clip.on("mouseover",function(client,args){...}); | 鼠标移入时的事件。args 参数包含以下属性: flashVersion:当前 Flash 的版本号 altKey:是否按住 Alt 键 ctrlKey:是否按住 Ctrl 键 shiftKey:是否按住 Shift 键 |
mouseout | clip.on("mouseout",function(client,args){...}); | 鼠标移出时的事件。args 参数包含以下属性: flashVersion:当前 Flash 的版本号 altKey:是否按住 Alt 键 ctrlKey:是否按住 Ctrl 键 shiftKey:是否按住 Shift 键 |
mousedown | clip.on("mousedown",function(client,args){...}); | 鼠标按下时的事件。args 参数包含以下属性: flashVersion:当前 Flash 的版本号 altKey:是否按住 Alt 键 ctrlKey:是否按住 Ctrl 键 shiftKey:是否按住 Shift 键 |
mouseup | clip.on("mouseup",function(client,args){...}); | 鼠标弹起时的事件。args 参数包含以下属性: flashVersion:当前 Flash 的版本号 altKey:是否按住 Alt 键 ctrlKey:是否按住 Ctrl 键 shiftKey:是否按住 Shift 键 |
complete | clip.on("complete",function(client,args){...}); | 成功复制内容时的事件。args 参数包含以下属性: flashVersion:当前 Flash 的版本号 altKey:是否按住 Alt 键 ctrlKey:是否按住 Ctrl 键 shiftKey:是否按住 Shift 键 text:复制的内容 |
noflash | clip.on("noflash",function(client,args){...}); | 没有检测到 Flash 时的事件。 |
wrongflash | clip.on("wrongflash",function(client,args){...}); | Flash 版本低于要求版本时的事件。ZeroClipboard 要求 Flash 10.0.0 以上的版本。 |
dataRequested | clip.on("dataRequested",function(client,args){...}); | 复制开始时的事件 |