SWFUpload 中文版手册

523906455

贡献于2013-06-25

字数:0 关键词: 文件上传 手册

SWFUpload 中文文档地址是:http://www.v-sky.com/doc/swfupload/Documentation.html 网官上的 DEMO 为:http://demo.swfupload.org/v220/index.htm 下载地址:http://code.google.com/p/swfupload/ SWFUpload 最初是由 Vinterwebb.se 开发的一个客户端的上传工具. 它结合了 FLASH 和 JavaScript 的功能,以提供一种超越了传统的浏览器中标签提供的文件上传功能。 SWFUpload 提供的主要功能:  在文件选择对话框中能够进行文件多选  页面无刷新的上传  提供上传进度的事件回调,实时显示上传进度  良好的浏览器兼容性  采用了命名空间以兼容其它 JS 的库 (例如 jQuery, Prototype, 等等)   对 FLASH 9 和 FLASH 10 播放器的支持(V2.2.0 版本放弃了对 Flash 8 的 支持) SWFUpload 背后的设计思想和其它基于 Flash 的上传工具是不同的。它将浏览器 的中 UI 交给开发人员来控制。开发人员能够利用 XHTML,CSS,Javascript 来定制 符合他们网站风格的 UI 上传元素。然后使用它提供的一组简单的 JS 事件来更新 上传状态,开发人员能够利用这些事件来及时更新页面中的上传进度 UI。 不幸的是 Flash Player 10 更严格的安全机制迫使我们不得不将一个 Flash Button 放入 Flash 影片中。SWFUpload 提供 API 供开发者通过图片、文字、CSS 的方式来自定制更灵活的 UI 显示。 SWFUpload v2 SWFUpload v2 包含了新的高级功能,改善了稳定性,解决了 FlashPlayer 中的 一些 bug,并且提供一套有用的插件。新的功能包括:  兼容了 Flash Player 10 的安全限制问题  在文件上传的同时能够发送额外的 POST 数据  针对每一个文件上传发送 POST/GET 数据  更直观的事件回调  动态修改实例设置  接收服务端返回的数据  非取消形式的停止文件上传  自定义上传的顺序  支持单文件、多文件的文件的选择  文件入队数量,文件上传数量和文件大小的限制  更合理地处理 0 字节的文件  针对每个文件在上传前都提供一个最后确认的时间回调  解决了 v1.0.2 版本中未描述到的关于 Flash 的 bug  解决的 v1.0.2 中的 bug: o 在 IE 中,刷新的时候 FLASH 无法加载(详细可见我之前的 debug 过程) o 在 FireFox 中,如果窗口的滚动条没有回滚到顶部,那么 Flash 无法加载 o Race-conditions when files are cached  兼容 ASP.Net Forms SWFUpload v2 延续了 SWFUpload 的设计目标,将 UI 分离以交给开发人员控制和 后续扩展 概述 传统的 HTML 上传 标准的 HTML 上传表单为用户提供一个文本框和按钮来选择文件,选中的文件是 随着 form 表单提交的。整个文件上传完成之后,下一个页面才会显示,并且不 能对选择的文件做预设的文件检验,例如文件大小限制,文件类型限制。当文件 上传时,用户获得的可用的反馈信息很少。 传统的 HTML 上传模式十分简单,线性的,几乎所有浏览器都支持它。 SWFUpload SWFUpload 使用一个 Flash 影片来控制文件的选择和上传。此 FLASH 中包含一个 用户自定制UI 的按钮,点击该按钮能够激活 Flash 本身的高级文件上传对话框, 它能够根据用户的设置来进行单文件或者是多文件的上传。 选择的的文件类型 也是可以被限制的,因此用户只能选择指定的适当的文件,例如*.jgp;*.gif。 提醒:Flash Player 10 的安全机制更严格,类似打开文件上传的对话框的操作, 一定需要用户交互才触发,如果用脚本触发,会报#2176 的运行时错误。因此 V2.2.0 版本在 SWF 中添加了一个可定制的 Button 让用户交互来打开文件对话框。 当选定文件以后,每个文件都会被验证和处理。当 Flash 上传文件的时候,由开 发人员预定义的 Javascript 事件会被定时触发以便来更新页面中的 UI,同时还 提供上传状态和错误信息。 选定的文件的上传和它所在页面、表单是独立的。每个文件都是单独上传的,这 就保证了服务端脚本能够在一个时间点更容易地处理单个文件。虽然 Flash 提供 了上传服务,但是页面并不会提交或者重新载入。相比于标准的 HTML Form, SWFUpload 的使用方式更像是 AJAX 程序,页面中的 Form 会和 FLASH 控制的文件 上传单独处理。 入门 SWFUpload 并不是拖放式的上传控件,它需要 JavaScript 和 DOM 的知识。一些 可用的演示展示了它能够完成什么事情以及它是如何完成这些常见的任务。 SWFUpload 由 4 部分组成: 1. 初始化和设置(Javascript) 2. JavaScript 库: SWFUpload.js 3. SWFUpload.swf(V2.2.0 版本放弃了对 flash 8 的支持) 4. 事件处理(Javascript) 使用 SWFUpload 遇到的多数问题是由不正确地设置或者定义了糟糕的处理事件 引起的。 初始化和设置 SWFpload 必须在页面中初始化,一般可以在 window.onload 事件中完成此操作。 它的构造函数需要一个 Object 类型的设置对象。 这个设置对象一般是一个直接 定义的 Object 类型变量,直接传递给 SWFUpload 的构造函数。 初始化的 SWFUpload 对象的引用需要保留下来,因为当显示文件选择对话框和启 动文件上传的时候需要这个实例的引用。 例如:用直接定义的 Object 类型变量设置初始化 SWFUpload 对象 var swfu; window.onload = function () { swfu = new SWFUpload({ upload_url : "http://www.swfupload.org/upload.php", flash_url : "http://www.swfupload.org/swfupload.swf", button_placeholder_id : "spanSWFUploadButton", file_size_limit : "20480" }); }; 例如:用存储在变量中的设置对象初始化 SWFUpload 对象 var swfu; window.onload = function () { var settings_object = { upload_url : "http://www.swfupload.org/upload.php", flash_url : "http://www.swfupload.org/swfupload.swf", button_placeholder_id : "spanSWFUploadButton", file_size_limit : "20480" }; swfu = new SWFUpload(settings_object); }; JavaScript 库 该 JavaScript 库文件(swfupload.js)应该包含在需要上传功能的页面中。 当 SWFUpload 创建完成并能访问它的一系列功能时,开发人员可以来控制此实例。 例如: 添加 SWFUpload.js 到页面中 例如: 根据需要的设置来初始化 SWFUpload var swfu = new SWFUpload({ upload_url : "http://www.swfupload.org/upload.php", flash_url : "http://www.swfupload.org/swfupload.swf", button_placeholder_id : "spanSWFUploadButton" }); Flash 控制元素 SWFUpload JavaScript 库动态加载 Flash 控制元素(swfupload.swf)。 Flash 控制元素的文件地址在初始化的时候就应该在 SWFUpload 设置对象中定义。 Flash 控制元素是一个很小的的 Flash 影片,它提供了文件浏览、检验和上传功 能。它在页面中展现给用户的是一个 UI 可自定制的按钮,但该 Flash 会在需要 时候通过与 Javascript 通信来通知浏览器处理更新。 事件处理 开发人员必须定义一系列 JavaScript 函数来处理 SWFUpload 事件回调,当一些 不同的重要事件发生的时候,这些函数会被触发。 通过处理 SWFUpload 的事件,开发人员能够提供关于上传进度、出错信息以及上 传完成等的信息反馈。 例如: swfupload 的处理事件和初始化 // uploadStart 处理事件。该函数变量在设置对象中指定给了 upload_start_handler 属性。 var uploadStartEventHandler = function (file) { var continue_with_upload; if (file.name === "the sky is blue") { continue_with_upload = true; } else { continue_with_upload = false; } return continue_with_upload; }; //uploadSuccess 处理事件。 该函数变量 在设置对象中指定给了 upload_success_handler 属性。 var uploadSuccessEventHandler = function (file, server_data) { alert("The file " + file.name + " has been delivered to the server."); alert("The server responded with " + server_data); }; //创建 SWFUpload 实例,设置 事件回调函数 var swfu = new SWFUpload({ upload_url : "http://www.swfupload.org/upload.php", flash_url : "http://www.swfupload.org/swfupload.swf", file_size_limit : "20480", upload_start_handler : uploadStartEventHandler, upload_success_handler : uploadSuccessEventHandler }); SWFUpload JavaScript 对象 构造函数 SWFUpload(settings object) 返回:一个 SWFUpload 实例 var swfupload_instance = new SWFUpload(settings_object); 全局变量和常量 SWFUpload 定义了一些全局变量和常量,这对 SWFUpload 的高级应用程序和处理 错误都是很有用的,它们都是只读的。 SWFUpload.instances SWFUpload.instances 是一个存储了页面中所有 SWFUpload 实例引用的数组。 Flash 播放器依靠这个数组来调用正确的处理事件。该数组是由 movieName 属性 来索引的关联数组。例如:SWFUpload.instances.SWFUpload_0 访问的是第一个 实例引用。 注意: SWFUpload.instances 不是一个真正的 JavaScript 数组,实际上它是一 个对象(关联数组)。 SWFUpload.movieCount SWFUpoad.movieCount 是一个全局变量,用于记录页面中的 SWFUpload 实例个数, 同时确保给每一个 Flash 影片分配一个惟一的 movieName。 SWFUpload.QUEUE_ERROR SWFUpload.QUEUE_ERROR 是一个包含了 Queue Error 错误码的 JS 对象,一般用 它来查看 fileQueueError 事件的中发送的错误码,以确定 fileQueueError 的具 体类型。 SWFUpload.QUEUE_ERROR = { QUEUE_LIMIT_EXCEEDED : -100, FILE_EXCEEDS_SIZE_LIMIT : -110, ZERO_BYTE_FILE : -120, INVALID_FILETYPE : -130 }; SWFUpload.UPLOAD_ERROR SWFUpload.UPLOAD_ERROR 是一个包含了 Upload Error 错误码的 JS 对象,一般 用它来查看 uploadError 事件的中发送的错误码,以确定 uploadError 的具体类 型。 SWFUpload.UPLOAD_ERROR = { HTTP_ERROR : -200, MISSING_UPLOAD_URL : -210, IO_ERROR : -220, SECURITY_ERROR : -230, UPLOAD_LIMIT_EXCEEDED : -240, UPLOAD_FAILED : -250, SPECIFIED_FILE_ID_NOT_FOUND : -260, FILE_VALIDATION_FAILED : -270, FILE_CANCELLED : -280, UPLOAD_STOPPED : -290 }; SWFUpload.FILE_STATUS SWFUpload.FILE_STATUS 是一个包含 File Status 状态码的 JS 对象。它可以用 来检测 File 对象中的 file status 属性,以确定文件的状态。 SWFUpload.FILE_STATUS = { QUEUED : -1, IN_PROGRESS : -2, ERROR : -3, SUCCESS : -4, CANCELLED : -5 }; 默认处理事件 SWFUpload 库提供了一系列默认的处理事件。当开发人员没有自定义处理事件时, SWFUpload 库将调用这些默认的处理事件。因此当自定义事件时,不要把这些默 认的处理事件覆盖了。自定义事件是需要在 settings 对象中被单独定义的。 SWFUpload.BUTTON_ACTION SWFUpload.BUTTON_ACTION 是一个包含 button 的动作预设的 JS 对象。 SWFUpload.BUTTON_ACTION = { SELECT_FILE : -100, SELECT_FILES : -110, START_UPLOAD : -120 } 可以使用 button_action 属性来设置 Flash 本身的文件上传对话框的行为。默认 为 SWFUpload.BUTTON_ACTION.SELECT_FILES,点击按钮将会打开多文件上传的 对话框。如果设置为 SWFUpload.BUTTON_ACTION.SELECT_FILE,则为单文件上传。 如果设置为 SWFUpload.BUTTON_ACTION.START_UPLOAD,则启动文件上传 SWFUpload.CURSOR SWFUpload.CURSOR 是一个包含 button 的光标状态码的 JS 对象。 SWFUpload.CURSOR = { ARROW : -1, HAND : -2 } 可以使用 button_cursor 属性来设置鼠标划过 button 时的光标状态。默认为 SWFUpload.CURSOR.ARROW,如果设置为 SWFUpload.CURSOR.HAND,则为手形 SWFUpload.WINDOW_MODE SWFUpload.WINDOW_MODE 是一个包含了该 SWF 插入到页面中的 wmode 属性的 JS 对象.可以通过设置 button_window_mode 属性来告诉浏览器具体以哪种模式显 示此 SWF。 SWFUpload.WINDOW_MODE = { WINDOW : "window", TRANSPARENT : "transparent", OPAQUE : "opaque" }; SWFUpload.WINDOW_MODE.WINDOW 是默认的模式. 该 SWF 将位于页面元素的最高 层级。 SWFUpload.WINDOW_MODE.OPAQUE 该 SWF 可以被页面类的其他元素通过层级的 设置来覆盖它。 SWFUpload.WINDOW_MODE.TRANSPARENT 该 SWF 的背景是透明的,可以透过它看到 背后的页面元素。 属性 下面这个列表是相关属性的具体描述。使用其它属性或者对只读属性进行了写的 操作都会造成 SWFUpload 出现问题。 customSettings (可读/可写) customSettings 属性是一个空的 JavaScript 对象,它被用来存储跟 SWFUpload 实例相关联的数据。它的内容可以使用设置对象中的 custom_settings 属性来初 始化。 注意:一些插件使用 customSettings 对象来实现它们的内部控制。当重写整个 customSettings 对象的时候需要务必小心。 例如: // 初始化包含自定义设置的 SWFUpload 对象 var swfu = new SWFUpload({ custom_settings : { custom_setting_1 : "custom_setting_value_1", custom_setting_2 : "custom_setting_value_2", custom_setting_n : "custom_setting_value_n", } }); swfu.customSettings.custom_setting_1 = "custom_setting_value_1"; // 更 改一个存在的自定义设置 swfu.customSettings.myNewCustomSetting = "new custom setting value"; // 添加一个新的自定义设置 //用一个全新的对象重 写 customSettings swfu.customSettings = { custom_setting_A : "custom_setting_value_A", custom_setting_B : "custom_setting_value_B" }; movieName(只读) 包含了该 SWFUpload 实例的惟一影片名字。该值被传递给 Flash,用来完成 Flash 和 JavaScript 的通信。该值被用来索引实例在 SWFUpload.instances 数组中的 位置,你无法更改此值。 方法 下面的方法用来操作 SWFUpload。其中有些方法可以跟元素(例如,按钮)的点 击事件绑定,其它的方法供 SWFUpload 内部处理事件中调用。 object addSetting(setting_name, value, default_value) 不赞成使用 V2.1.0 源码中注释:addSetting 和 getSetting 已经不再被使用了, 只是考虑到兼容 V2 版本,才继续保留在库中。 object getSetting(setting_name) 不赞成使用 V2.1.0 源码中注释:addSetting 和 getSetting 已经不再被使用了, 只是考虑到兼容 V2 版本,才继续保留在库中。 object retrieveSetting(setting_value, default_value) v2.1.0 中已被删除 bool destroy() v2.1.0 中新增 用于将一个 SWFUpload 实例从页面中销毁。不但删除 DOM 中的 Flash 元素,同时 还删除 SWFUpload 实例的相关引用。成功返回 true,失败返回 false。 这个方法还没有针对插件做兼容测试,可能会有不兼容问题。(尤其是 SWFObject 插件) 提醒:SWFUpload 在 v2.1.0 中改写了 Flash 插入的代码,V2 版中使用 SWFObject 插入 Flash 会造成 IE 的一个刷新 BUG。 void displayDebugInfo() 调用 debug 方法,在 Debug 输出框中显示 SWFUpload 实例的设置信息,如果设置 中的 debug 属性是 true,那么默认是在实例化完成以后自动调用此方法。 void selectFile() 不赞成使用,不兼容 Flash Player 10 弹出 flash 的文件选择对话框,只能选择单个文件。 提醒:Flash Player 10 的安全机制更严格,类似打开文件上传的对话框的操作, 一定需要用户交互才触发,如果用脚本触发,会报#2176 的运行时错误。因此 V2.2.0 版本在 SWF 中添加了一个可定制的 Button 让用户交互来打开文件对话框。 void selectFiles() 不赞成使用,不兼容 Flash Player 10 弹出 flash 的文件选择对话框,可一次性选择多个文件。 提醒:Flash Player 10 的安全机制更严格,类似打开文件上传的对话框的操作, 一定需要用户交互才触发,如果用脚本触发,会报#2176 的运行时错误。因此 V2.2.0 版本在 SWF 中添加了一个可定制的 Button 让用户交互来打开文件对话框。 void startUpload(file_id) 指定 file_id 来启动该文件的上传,如果 file_id 被忽略了,那么默认开始上传 第一个文件。 void cancelUpload(file_id, trigger_error_event) 指定 file_id 来退出文件的上传,从上传队列中删除该文件。 如果忽略 file_id,那么默认文件上传队列中的第一个文件将被退出上传。 如果取消的文件是正在上传,那么会触发 uploadError 事件。 如果将可选参数 trigger_error_event 设置为 false,那么 uploadError 事件不 会触发。 void stopUpload() 如果当前有文件上传,那么停止上传,并且将文件还原到上传队列中。 停止了正在上传的文件,uploadError 事件会被触发。如果此时没有正在上传文 件,那么不会发生任何操作,不会触发任何事件。 object getStats() 获取当前状态的统计对象,具体见 Stats Object。 void setStats(stats_object) Stats 统计对象是可以被修改的。如果你希望在上传完毕之后修改上传成功或者 上传失败的统计数目时,那么可以使用该方法。 提醒:可供修改的属性只有 successful_uploads ,upload_errors, upload_cancelled,queue_errors,并且值必须是 Number 类型。 object getFile(file_id|index) 根据 file_id 或者 index 来获取文件队列中的文件对象。file_id 是文件对象中 的 id 属性,index 是文件对象中的 index 属性。 传递 Number 类型的参数会被认定为 index,那么返回的是文件队列(所有尝试 入队文件,包括因没有通过文件大小、类型检测等而触发 fileQueueError,没 有成功加入文件上传队列的文件对象)数组中下标为 index 的文件对象。如果 index 不在队列数组范围内,那么返回 null。 传递非 Number 类型的参数会被认定为 file_id,那么返回的是文件上传队列(通 过文件检测,准备好进行上传的文件)数组中 id 为 file_id 的文件对象。如果 参数为空,或者没有此 id 的文件对象,那么返回文件等待队列中的第一个文件 对象,如果第一个文件对象为空,那么返回 null。 void addPostParam(name, value) 给设置中的 post_params 对象添加值对,当文件上传的时候,这个值对会一同在 POST 中发送。 如果设置的时候,post_params 中以及存在该值,那么实际上会被覆盖。 提醒:SWFUload 存在 Cookie bug,你可以使用此方法避免。 void removePostParam(name) 从设置中的 post_params 对象中删除 name 指定的属性,当文件上传的时候,删 除的值对不会继续在 POST 中发送。 bool addFileParam(file_id, name, value) 为指定 file_id 的特定文件对象添加 POST 值对,如果添加的 name 属性已经存在, 那么原值会被覆盖。 如果需要给所有文件对象添加 POST 值,那么可以使用设置中的 post_params 属 性。 bool removeFileParam(file_id, name) 删除由 addFileParam 添加的 POST 值对. 如果 POST 设置中没有此属性,那么返回 false。 void setUploadURL(url) 动态修改设置中的 upload_url 属性。 void setPostParams(param_object) 动态修改 post_params,以前的属性全部被覆盖。param_object 必须是一个 JavaScript 的基本对象,所有属性和值都必须是字符串类型。 void setFileTypes(types, description) 动态修改设置中的 file_types 和 file_types_description,两个参数都是必 须的。 void setFileSizeLimit(file_size_limit) 动态修改设置中的 file_size_limit,此修改针对之后的文件大小过滤有效。 file_size_limit 参数接收一个单位,有效的单位有 B、KB、MB、GB,默认单位 是 KB。 例如: 2147483648 B, 2097152, 2097152KB, 2048 MB, 2 GB void setFileUploadLimit(file_upload_limit) 动态修改设置中的 file_upload_limit,特殊值 0 表示无限制。 提醒:这里限制的是一个 SWFUpload 实例控制上传成功的文件总数。 void setFileQueueLimit(file_queue_limit) 动态修改设置中的 file_queue_limit,特殊值 0 表示无限制。 提醒:这里限制的是文件上传队列中(入队检测通过的文件会添加到上传队列等 待上传)允许排队的文件总数。 void setFilePostName(file_post_name) 动态修改设置中的 file_post_name,注意在 Linux 环境下,FlashPlayer 是忽略 此设置的。 void setUseQueryString(use_query_string) 动态修改设置中的 use_query_string,设置为 true 的时候,SWFUpload 以 GET 形式发送数据,如果为 false,那么就以 POST 发送数据。 void setDebugEnabled(debug_enabled) 启动/禁止 debug 输出,debug_enabled 参数是一个布尔值。 void setButtonImageURL(url) 动态修改按钮的图片。url 参数是相对于该 swf 文件或者是绝对地址的图片(或 者是 SWF)。所有 FLASH 支持的图片类型都可以使用(gif,jpg,png,或者是一个 SWF)。 该按钮图片需要经过一定规则(CSS Sprite)的处理。按钮图片中需要包括按钮 的 4 个状态,从上到下依次是 normal, hover, down/click, disabled.(可以 参照官方 demo 中的图片) void setButtonDimensions(width, height) 动态修改 SWF 影片的尺寸以适应 Button 的图片大小。 void setButtonText(text) 动态设置 Flash Button 中显示的文字,支持 HTML。HTML 文本的样式可以通过 CSS 选择器并配合 setButtonTextStyle 方法来设置。关于 Flash 文本对 HTML 的 支持详细可见 Adobe's Flash documentation。 void setButtonTextStyle(css_style_text) 配合 setButtonText 方法,可以通过 CSS 样式来动态设置 Flash Button 中的文 字样式。关于 Flash 文本对 CSS 的支持详细可见 Adobe's Flash documentation void setButtonTextPadding(left, top) Sets the top and left padding of the Flash button text. The values may be negative. void setButtonDisabled(isDisabled) When 'true' changes the Flash Button state to disabled and ignores any clicks. void setButtonAction(buttonAction) Sets the action taken when the Flash button is clicked. Valid action values are taken from the BUTTON_ACTION constants. void setButtonCursor(buttonCursor) Sets the mouse cursor shown when hovering over the Flash button. Valid cursor values are taken from the BUTTON_CURSOR constants. 事件 SWFUpload 在操作过程中会触发一系列事件,开发者可以利用这些回调的处理事 件来控制 UI,控制操作或者报告错误。 所有的事件都是在 SWFUpload 实例的上下文中调用的,因此在这些回调的事件中 使用 this 能够直接访问到该触发该事件的实例对象。 所有事件应该在实例初始化时 setting 参数中预设完成。 flashReady() 该事件函数是内部事件,因此不能被重写。当 SWFupload 实例化,加载的 FLASH 完成所有初始化操作时触发此事件。 提醒:对应设置中的自定义事件 swfupload_loaded_handler swfUploadLoaded() V2.1.0 版本中已经删除了此事件 fileDialogStart() 此事件在selectFile 或者selectFiles 调用后,文件选择对话框显示之前触发。 只能同时存在一个文件对话框。 提醒:对应设置中的自定义事件 file_dialog_start_handler fileQueued(file object) 当文件选择对话框关闭消失时,如果选择的文件成功加入上传队列,那么针对每 个成功加入的文件都会触发一次该事件(N 个文件成功加入队列,就触发 N 次此 事件)。 提醒:对应设置中的自定义事件 file_queued_handler fileQueueError(file object, error code, message) 当选择文件对话框关闭消失时,如果选择的文件加入到上传队列中失败,那么针 对每个出错的文件都会触发一次该事件(此事件和 fileQueued 事件是二选一触 发,文件添加到队列只有两种可能,成功和失败)。 文件添加队列出错的原因可能有:超过了上传大小限制,文件为零字节,超过文 件队列数量限制,设置之外的无效文件类型。 具体的出错原因可由 error code 参数来获取,error code 的类型可以查看 SWFUpload.QUEUE_ERROR 中的定义。 提醒:对应设置中的自定义事件 file_queue_error_handler 注意:如果选择入队的文件数量超出了设置中的数量限制,那么所有文件都不入 队,此事件只触发一次。如果没有超出数目限制,那么会对每个文件进行文件类 型和大小的检测,对于不通过的文件触发此事件,通过的文件成功入队。 fileDialogComplete(number of files selected, number of files queued) 当选择文件对话框关闭,并且所有选择文件已经处理完成(加入上传队列成功或 者失败)时,此事件被触发,number of files selected 是选择的文件数目, number of files queued 是此次选择的文件中成功加入队列的文件数目。 提醒:对应设置中的自定义事件 file_dialog_complete_handler 注意:如果你希望文件在选择以后自动上传,那么在这个事件中调用 this.startUpload() 是一个不错的选择。如果需要更严格的判断,在调用上传 之前,可以对入队文件的个数做一个判断,如果大于 0,那么可以开始上传。 uploadStart(file object) 在文件往服务端上传之前触发此事件,可以在这里完成上传前的最后验证以及其 他你需要的操作,例如添加、修改、删除 post 数据等。 在完成最后的操作以后,如果函数返回 false,那么这个上传不会被启动,并且 触发 uploadError 事件(code 为 ERROR_CODE_FILE_VALIDATION_FAILED),如果 返回 true 或者无返回,那么将正式启动上传。 提醒:对应设置中的自定义事件 upload_start_handler uploadProgress(file object, bytes complete, total bytes) 该事件由 flash 定时触发,提供三个参数分别访问上传文件对象、已上传的字节 数,总共的字节数。因此可以在这个事件中来定时更新页面中的 UI 元素,以达 到及时显示上传进度的效果。 注意: 在 Linux 下,Flash Player 只在所有文件上传完毕以后才触发一次该事 件,官方指出这是 Linux Flash Player 的一个 bug,目前 SWFpload 库无法解决 (我没有测试过)。 提醒:对应设置中的自定义事件 upload_progress_handler uploadError(file object, error code, message) 无论什么时候,只要上传被终止或者没有成功完成,那么该事件都将被触发。 error code 参数表示了当前错误的类型,更具体的错误类型可以参见 SWFUpload.UPLOAD_ERROR 中的定义。Message 参数表示的是错误的描述。File 参数表示的是上传失败的文件对象。 例如,我们请求一个服务端的一个不存在的文件处理页面,那么 error code 会 是-200,message 会是 404。停止、退出、uploadStart 返回 false、HTTP 错误、 IO 错误、文件上传数目超过限制等,都将触发该事件,Upload error will not fire for files that are cancelled but still waiting in the queue。(对 于官方的这句话我还存在疑问,文件退出以后怎么还会保留在文件上传队列中保 留呢?) 提醒:对应设置中的自定义事件 upload_error_handler 注意:此时文件上传的周期还没有结束,不能在这里开始下一个文件的上传。 uploadSuccess(file object, server data) 当文件上传的处理已经完成(这里的完成只是指向目标处理程序发送了 Files 信息,只管发,不管是否成功接收),并且服务端返回了 200 的 HTTP 状态时, 触发此事件。 提醒:对应设置中的自定义事件 upload_success_handler 注意: 1. server data 是服务端处理程序返回的数据。 2. 此时文件上传的周期还没有结束,不能在这里开始下一个文件的上传。 3. 在 window 平台下,那么服务端的处理程序在处理完文件存储以后,必须 返回一个非空值,否则此事件不会被触发,随后的 uploadComplete 事件 也无法执行。 uploadComplete(file object) 当上传队列中的一个文件完成了一个上传周期,无论是成功(uoloadSuccess 触 发)还是失败(uploadError 触发),此事件都会被触发,这也标志着一个文件的 上传完成,可以进行下一个文件的上传了。 如果要进行多文件自动上传,那么在这个时候调用 this.startUpload()来启动 下一个文件的上传是不错的选择。 提醒:对应设置中的自定义事件 upload_complete_handler 注意:当在进行多文件上传的时候,中途用 cancelUpload 取消了正在上传的文 件,或者用 stopUpload 停止了正在上传的文件,那么在 uploadComplete 中就要 很小心的使用 this. startUpload(),因为在上述情况下,uploadError 和 uploadComplete 会顺序执行,因此虽然停止了当前文件的上传,但会立即进行 下一个文件的上传,你可能会觉得这很奇怪,但事实上程序并没有错。如果你希 望终止整个队列的自动上传,那么你需要做额外的程序处理了。 debug(message) 如果 debug setting 设置为 true,那么页面底部会自动添加一个 textArea, SWFUpload 库和 Flash 都会调用此事件来在页面底部的输出框中添加 debug 信息 供调试使用。 提醒:对应设置中的自定义事件 debug_handler SWFUpload 功能对象 Settings object 它是一个 Object 类型的变量,为 SWFUpload 的实例初始化提供配置。 其中的每 一个配置属性都只能出现一次。 很多属性都是可选的,如果可选属性没有被配 置,那么会使用 SWFUpload 库中默认指定的合适的值,具体可查看 setting 的详 细介绍。 例如:(setting 可以配置的所有属性) { upload_url : "http://www.swfupload.org/upload.php", flash_url : "http://www.swfupload.org/swfupload.swf", file_post_name : "Filedata", post_params : { "post_param_name_1" : "post_param_value_1", "post_param_name_2" : "post_param_value_2", "post_param_name_n" : "post_param_value_n" }, use_query_string : false, requeue_on_error : false, http_success : [201, 202], file_types : "*.jpg;*.gif", file_types_description: "Web Image Files", file_size_limit : "1024", file_upload_limit : 10, file_queue_limit : 2, debug : false, prevent_swf_caching : false, button_placeholder_id : "element_id", button_image_url : "http://www.swfupload.org/button_sprite.png", button_width : 61, button_height : 22, button_text : "Click here", button_text_style : ".redText { color: #FF0000; }", button_text_left_padding : 3, button_text_top_padding : 2, button_action : SWFUpload.BUTTON_ACTION.SELECT_FILES, button_disable : false, button_cursor : SWFUpload.BUTTON_CURSOR.HAND, button_window_mode : SWFUpload.WINDOW_MODE.TRANSPARENT, swfupload_loaded_handler : swfupload_loaded_function, file_dialog_start_handler : file_dialog_start_function, file_queued_handler : file_queued_function, file_queue_error_handler : file_queue_error_function, file_dialog_complete_handler : file_dialog_complete_function, upload_start_handler : upload_start_function, upload_progress_handler : upload_progress_function, upload_error_handler : upload_error_function, upload_success_handler : upload_success_function, upload_complete_handler : upload_complete_function, debug_handler : debug_function, custom_settings : { custom_setting_1 : "custom_setting_value_1", custom_setting_2 : "custom_setting_value_2", custom_setting_n : "custom_setting_value_n", } } Settings 描述 upload_url 默认值:空字符串 upload_url 设置接收的是一个绝对的或者相对于 SWF 文件的完整 URL。推荐使用 完整的绝对路径,以避免由浏览器和 FlashPlayer 修改了基准路径设置而造成的 请求路径错误。 注意:这里需要考虑 FlashPlayer 的安全域模型。 file_post_name 默认值:Filedata 该参数设置了 POST 信息中上传文件的 name 值(类似传统 Form 中设置了的 name 属性)。 注意:在 Linux 下面此参数设置无效,接收的 name 总为 Filedata,因此为了保 证最大的兼容性,建议此参数使用默认值。 post_params 默认值:空的 Object 对象 post_params 定义的是一个包含值对的 object 类型数据,每个文件上传的时候, 其中的值对都会被一同发送到服务端。 注意:设置值对的时候,值只能是字符串或者数字。 use_query_string 默认值:false 该属性可选值为 true 和 false,设置 post_params 是否以 GET 方式发送。如果 为 false,那么则以 POST 形式发送。 requeue_on_error 默认值:false 该属性可选值为 true 和 false。如果设置为 true,当文件对象发生 uploadError 时(除开 fileQueue 错误和 FILE_CANCELLED 错误),该文件对象会被重新插入 到文件上传队列的前端,而不是被丢弃。如果需要,重新入队的文件可以被再次 上传。如果要从上传队列中删除该文件对象,那么必须使用 cancelUpload 方法。 跟上传失败关联的所有事件同样会被一一触发,因此将上传失败的文件重新入队 可能会和 Queue Plugin 造成冲突(或者是自动上传整个文件队列的自定义代码)。 如果代码中调用了 startUpload 方法自动进行下一个文件的上传,同时也没有采 取任何措施让上传失败的文件退出上传队列,那么这个重新入队的上传失败的文 件又会开始上传,然后又会失败,重新入队,重新上传...,进入了无止境的循 环。 该设置是在 v2.1.0 中引入的。 http_success 默认值:[] 该数组可自定义触发 success 事件的 HTTP 状态值。200 的状态值始终会触发 success,并且只有 200 的状态会提供 serverData。 当接受一个 200 以外的 HTTP 状态值时,服务端不需要返回内容。 file_types 默认值:*.* 设置文件选择对话框的文件类型过滤规则,该属性接收的是以分号分隔的文件类 型扩展名,例如“ *.jpg;*.gif”,则只允许用户在文件选择对话框中可见并可 选 jpg 和 gif 类型的文件。默认接收所有类型的文件。 提醒:该设置只是针对客户端浏览器的过滤,对服务端的文件处理中的文件类型 过滤没有任何限制,如果你需要做严格的文件过滤,那么服务端同样需要程序检 测。 file_types_description 默认值:All Files 设置文件选择对话框中显示给用户的文件描述。 file_size_limit 默认值:0 设置文件选择对话框的文件大小过滤规则,该属性可接收一个带单位的数值,可 用的单位有 B,KB,MB,GB。如果忽略了单位,那么默认使用 KB。特殊值 0 表示文 件大小无限制。 提醒:该设置只对客户端的浏览器有效,对服务端的文件处理没有任何限制,如 果你需要做严格文件过滤,那么服务端同样需要程序处理。

下载文档,方便阅读与编辑

文档的实际排版效果,会与网站的显示效果略有不同!!

需要 6 金币 [ 分享文档获得金币 ] 1 人已下载

下载文档

相关文档