swfupload参数详细说明.pdf

一、配置参数对象中的常用属性及说明一、配置参数对象中的常用属性及说明属性属性类型类型默认值默认值描述描述处理上传文件的服务器端页面的 url 地址，可以是绝对地址，upload_urlupload_urlString也可以是相对地址，当为相对地址时相对的是当前代码所在的文档地址如果为 false 则 SWFUpload 会preserve_relative_urlspreserve_relative_urlsBooleanfalse把 swfupload.swf 用到的相对地址转换为绝对地址，以达到更好的兼容性相当于用普通的文件域上传文file_post_namefile_post_nameStringFiledata件时的 name 属性，服务器端接收页面通过该名称来获取上传的文件一个对象直接量，里面的键/值post_paramspost_paramsObject(直接量)对会随着每一个文件一起上传，文件上传要附加一些信息时很有用为 false 时,post_params 属性定义的参数会以 post 方式上use_query_stringuse_query_stringBooleanfalse传；为true 时，则会以get 方式上传（即参数会以查询字符串的形式附加到 url 后面）该属性指定了允许上传的文件file_typesfile_typesString类型，当有多个类型时使用分号隔开，比如：*.jpg;*.png,允许所有类型时请使用*.*指定在文件选取窗口中显示的file_types_descriptionfile_types_descriptionString文件类型描述，起一个提示和说明的作用吧指定要上传的文件的最大体积，可以带单位，合法的单位有:B、file_size_limitfile_size_limitStringKB、MB、GB，如果省略了单位，则默认为 KB。该属性为 0 时，表示不限制文件的大小。file_upload_limitfile_upload_limitNumber指定最多能上传多少个文件，当上传成功的文件数量达到了这个最大值后，就不能再上传文件了，也不能往上传队列里添加文件了。把该属性设为 0 时表示不限制文件的上传数量。指定文件上传队列里最多能同时存放多少个文件。当超过了这个数目后只有当队列里有文件上传成功、上传出错或被取消上传后，等同数量的其他文件才可以被添加进来。当file_upload_limit 的数值或者剩余的能上传的文件数量小于 file_queue_limit 时，则取那个更小的值swfupload.swf 文件的绝对或相对地址，相对地址是指相对于file_queue_limitfile_queue_limitNumberflash_urlflash_urlString当前的页面地址。实例化swfupload 后，就不能再改变该属性的值了。为 true 时会加一个随机数在swfupload.swf 地址的后面，以阻止 flash 影片被缓存，这是为了防止某些版本的 IE 浏览器在读取缓存的 falsh 影片时出现的 bug指定一个dom元素的id,该domprevent_swf_cachingprevent_swf_cachingBooleanbutton_placeholder_idbutton_placeholder_idString元素在 swfupload 实例化后会被 Flash 按钮代替，这个 dom元素相当于一个占位符指定一个 dom元素,该dom 元素在 swfupload 实例化后会被Flash 按钮代替，这个 dom 元素相当于一个占位符。当button_placeholderbutton_placeholderDOMElementbutton_placeholder_id 与button_placeholder 都存在时，以button_placeholder_id 为优先button_image_urlbutton_image_urlString指定 Flash 按钮的背景图片，相对地址或绝对地址都可以。该地址会受到preserve_relative_urls 属性的影响，遵从与upload_url一样的规则。该背景图片必须是一个 sprite图片,从上到下包含了Flash按钮的正常、鼠标悬停、按下、禁用这四种状态。因此该图片的高度应该是 Flash 按钮高度的四倍button_widthbutton_widthNumber指定 Flash 按钮的宽度指定 Flash 按钮的高度，应该button_heightbutton_heightNumber为 button_image_url 所指定的按钮背景图片高度的 1/4button_textbutton_textString指定 Flash 按钮上的文字，也可以是 html 代码Flash 按钮上的文字的样式，使用方法见示例指定 Flash 按钮顶部的内边距，可使用负值指定 Flash 按钮左边的内边距，可使用负值为true时Flash按钮将变为禁button_text_stylebutton_text_styleStringbutton_text_top_paddingbutton_text_top_paddingNumberbutton_text_left_paddingbutton_text_left_paddingNumberbutton_disabledbutton_disabledBooleanfalse用状态，点击也不会触发任何行为指定鼠标悬停在 Flash 按钮上button_cursorbutton_cursor时的光标样式，可用值为SWFUpload.CURSOR 里定义的常量指定Flash按钮的WMODE属性，button_window_modebutton_window_mode可用值为SWFUpload.WINDOW_MODE 里定义的常量file_dialog_start_handlerfile_dialog_start_handlerFunctionfile_queued_handlerfile_queued_handlerfile_queue_error_handlerfile_queue_error_handlerFunctionFunctionfileDialogStart 事件侦听函数fileQueued 事件侦听函数fileQueueError 事件侦听函数file_dialog_complete_handlerfile_dialog_complete_handlerFunctionupload_start_handlerupload_start_handlerupload_progress_handlerupload_progress_handlerupload_error_handlerupload_error_handlerupload_success_handlerupload_success_handlerupload_complete_handlerupload_complete_handlerFunctionfileDialogComplete 事件侦听函数uploadStart 事件侦听函数uploadProgress 事件侦听函数uploadError 事件侦听函数uploadSuccess 事件侦听函数uploadComplete 事件侦听函数FunctionFunctionFunctionFunction二、各种事件说明二、各种事件说明要实现与用户的交互，靠的就是在这些事件上做文章了fileDialogStart()fileDialogStart()在文件选取窗口将要弹出时触发fileQueued(fileQueued(file object)当一个文件被添加到上传队列时会触发此事件，提供的唯一参数为包含该文件信息的 file object 对象fileQueueError(fileQueueError(file object,error code,message)当文件添加到上传队列失败时触发此事件，失败的原因可能是文件大小超过了你允许的数值、文件是空的或者文件队列已经满员了等。该事件提供了三个参数。第一个参数是当前出现问题的文件对象，第二个参数是具体的错误代码，可以参照 SWFUpload.QUEUE_ERROR 中定义的常量fileDialogComplete(fileDialogComplete(number of files selected,number of files queued,totalnumber of files in the queued)当文件选取完毕且选取的文件经过处理后（指添加到上传队列），会立即触发该事件。可以在该事件中调用 this.startUpload()方法来实现文件的自动上传参数 number of files selected 指本次在文件选取框里选取的文件数量参数 number of files queued 指本次被添加到上传队列的文件数量参数 total number of files in the queued 指当前上传队列里共有多少个文件（包括了本次添加进去的文件）uploadStart(uploadStart(file object)当文件即将上传时会触发该事件,该事件给了你在文件上传前的最后一次机会来验证文件信息、增加要随之上传的附加信息或做其他工作。可以通过返回 false 来取消本次文件的上传参数 file object 为当前要上传的文件的信息对象uploadProgress(uploadProgress(file object,bytes complete,total bytes)该事件会在文件的上传过程中反复触发，可以利用该事件来实现上传进度条参数 file object 为文件信息对象参数 bytes complete 为当前已上传的字节数参数 total bytes 为文件总的字节数uploadError(uploadError(file object,error code,message)文件上传被中断或是文件没有成功上传时会触发该事件。停止、取消文件上传或是在 uploadStart 事件中返回 false 都会引发这个事件，但是如果某个文件被取消了但仍然还在队列中则不会触发该事件参数 file object 为文件信息对象参数 error code 为错误代码，具体的可参照 SWFUpload.UPLOAD_ERROR 中定义的常量uploadSuccess(uploadSuccess(file object,server data,received response)当一个文件上传成功后会触发该事件参数 file object 为文件信息对象参数 server data 为服务器端输出的数据uploadComplete(uploadComplete(file object)当一次文件上传的流程完成时（不管是成功的还是不成功的）会触发该事件，该事件表明本次上传已经完成，上传队列里的下一个文件可以开始上传了。该事件发生后队列中下一个文件的上传将会开始三、三、swfuploadswfupload实例的方法实例的方法方法中大多数是动态改变参数配置对象的方法destroy()destroy()当不需要再使用 SWFUpload 了的时候,可以使用该方法来销毁它的实例和 dom 元素startUpload(startUpload(file_id)开始上传队列中指定的文件参数 file_id 代表要上传的文件的 id，如果未填写这个参数，则会上传队列中第一个文件cancelUpload(cancelUpload(file_id,trigger_error_event)取消文件的上传参数 file_id 为要取消的文件的 id,如果该参数为 undefined 或者未填写，则会取消队列里的第一个文件参数 trigger_error_event 接受一个布尔值，当为 false 时取消文件不会触发 uploadError 事件，默认为 truestopUpload()stopUpload()终止当前正在上传的文件，会触发 uploadError 事件。如果当前没有文件在上传，则该方法什么都不会做getStats()getStats()获取队列的 stats objectsetStats(setStats(stats_object)修改队列的 stats_object，传入修改过的 stats_object 作为参数getFile(getFile(file_id|index)根据文件 id 或文件索引来获取一个 File Object,当使用文件 id 时只能获得队列里的文件，当使用文件索引时所有文件（包括队列内和队列外）都可获得addPostParam(addPostParam(name,value)往配置对象中 post_params 指定的附加信息对象中增加键/值对removePostParam(removePostParam(name)移除置配置对象中的 post_params 包含的某一个键/值对，参数 name 为要移除的值的键名addFileParam(addFileParam(file_id,name,value)为某个特定文件增加随之一起上传的附加信息。注意，只有在该指定的文件上传时，附加的信息才会一起上传。而配置对象中 post_param 设置的附加信息在任一文件上传时都会与之一起发送。参数 file_id 为要指定的文件 id,参数 name 和 value 分别为附加信息的名称和值removeFileParam(removeFileParam(file_id,name)移除通过 addFileParam 方法增加的附加信息，两个参数相信就不用我多讲了吧setUploadURL(setUploadURL(url)动态设置配置对象中 upload_url 的值setPostParams(setPostParams(param_object)动态设置配置对象中 post_params 属性的值，新的值会覆盖旧的值。参数 param_object 必须为一个对象直接量，且里面的属性和值都只能为字符串setFileTypes(setFileTypes(types,description)动态设置配置对象中 file_types 和 file_types_description 属性的值。两个参数都不能省略setFileSizeLimit(setFileSizeLimit(file_size_limit)动态设置配置对象中 file_size_limit 属性的值setFileUploadLimit(setFileUploadLimit(file_upload_limit)动态设置配置对象中 file_upload_limit 属性的值setFileQueueLimit(setFileQueueLimit(file_queue_limit)动态设置配置对象中 file_queue_limit 属性的值setFilePostName(setFilePostName(file_post_name)动态设置配置对象中 file_post_name 属性的值setUseQueryString(setUseQueryString(use_query_string)动态设置配置对象中 use_query_string 属性的值setButtonImageURL(setButtonImageURL(url)动态设置配置对象中 button_image_url 属性的值setButtonDimensions(setButtonDimensions(width,height)动态设置 Flash 按钮的宽度和高度，两个参数分别为宽度和高度的值，类型为数字，且不能带单位setButtonText(setButtonText(text)动态设置配置对象中 button_text 属性的值setButtonTextStyle(setButtonTextStyle(css_style_text)动态设置配置对象中 button_text_style 属性的值setButtonTextPadding(setButtonTextPadding(left,top)动态设置 Flash 按钮的左边内边距和顶部内边距setButtonDisabled(setButtonDisabled(isDisabled)动态对 Flash 按钮进行禁用和不禁用的操作，参数为一个布尔值setButtonCursor(setButtonCursor(buttonCursor)动态设置配置对象中 button_cursor 的值四、文件信息对象四、文件信息对象 File ObjectFile Object在事件监听函数中，经常要用到文件信息对象来获取文件的信息以供下一步的操作属性属性ididindexindexnamenametypetypecreationdatecreationdatemodificationdatemodificationdatefilestatusfilestatus类型类型StringNumberStringStringDateDate描述描述SWFUpload 定义的文件 id,用来控制文件的上传文件的索引，用在 getFile(i)方法中文件的原始名称，不包括路径文件类型文件的创建日期文件的最后修改日期当前文件的状态，详细的请参照SWFUpload.FILE_STATUS 中定义的常量Number五、队列状态对象五、队列状态对象 Stats ObjectStats Object用来获取当前队列的状况属性属性类型类型描述描述in_progressin_progressfiles_queuedfiles_queuedNumber得到的值为 1 或 0，表明当前队列是否有文件正在上传中目前上传队列中的文件数量已成功上传(指触发了 uploadSuccess 事件)的文件数量上传失败的文件数量(包括被取消上传的文件)被取消上传的文件数量触发了 fileQueueError 事件的文件数量Numbersuccessful_uploadssuccessful_uploadsNumberupload_errorsupload_errorsupload_cancelledupload_cancelledqueue_errorsqueue_errorsNumberNumberNumber六、一些常量六、一些常量定义的一些常量，便于理解常量名常量名描述描述该常量是一个对象，代表一个页面上SWFUpload.instancesSWFUpload.instances所有的 SWFUpload 实例的引用的集合，用 SWFUpload 实例的 movieName属性进行索引SWFUpload.movieCountSWFUpload.movieCountSWFUpload.QUEUE_ERROR.QUEUE_LIMIT_EXCEEDEDSWFUpload.QUEUE_ERROR.QUEUE_LIMIT_EXCEEDEDSWFUpload.QUEUE_ERROR.FILE_EXCEEDS_SIZE_LIMITSWFUpload.QUEUE_ERROR.FILE_EXCEEDS_SIZE_LIMITSWFUpload.QUEUE_ERROR.ZERO_BYTE_FILESWFUpload.QUEUE_ERROR.ZERO_BYTE_FILESWFUpload.QUEUE_ERROR.INVALID_FILETYPESWFUpload.QUEUE_ERROR.INVALID_FILETYPESWFUpload.UPLOAD_ERROR.HTTP_ERRORSWFUpload.UPLOAD_ERROR.HTTP_ERRORSWFUpload.UPLOAD_ERROR.MISSING_UPLOAD_URLSWFUpload.UPLOAD_ERROR.MISSING_UPLOAD_URLSWFUpload.UPLOAD_ERROR.IO_ERRORSWFUpload.UPLOAD_ERROR.IO_ERRORSWFUpload.UPLOAD_ERROR.SECURITY_ERRORSWFUpload.UPLOAD_ERROR.SECURITY_ERRORSWFUpload.UPLOAD_ERROR.UPLOAD_LIMIT_EXCEEDEDSWFUpload.UPLOAD_ERROR.UPLOAD_LIMIT_EXCEEDEDSWFUpload.UPLOAD_ERROR.UPLOAD_FAILEDSWFUpload.UPLOAD_ERROR.UPLOAD_FAILEDSWFUpload.UPLOAD_ERROR.SPECIFIED_FILE_ID_NOT_FOUNDSWFUpload.UPLOAD_ERROR.SPECIFIED_FILE_ID_NOT_FOUND页面上存在的 SWFUpload 实例的数量用户选取的文件超过了允许的数量文件的体积超过了允许的大小文件是空的不允许的文件类型服务器返回的状态码不是 200没有设置 upload_url读取或传输文件时发生错误上传受到了安全方面的限制上传的文件数量超过了允许的最大值上传出现错误给 startUpload()方法传入的文件id 不存在SWFUpload.UPLOAD_ERROR.FILE_VALIDATION_FAILEDSWFUpload.UPLOAD_ERROR.FILE_VALIDATION_FAILEDSWFUpload.UPLOAD_ERROR.FILE_CANCELLEDSWFUpload.UPLOAD_ERROR.FILE_CANCELLEDSWFUpload.UPLOAD_ERROR.UPLOAD_STOPPEDSWFUpload.UPLOAD_ERROR.UPLOAD_STOPPEDSWFUpload.FILE_STATUS.QUEUEDSWFUpload.FILE_STATUS.QUEUEDSWFUpload.FILE_STATUS.IN_PROGRESSSWFUpload.FILE_STATUS.IN_PROGRESSSWFUpload.FILE_STATUS.ERRORSWFUpload.FILE_STATUS.ERRORSWFUpload.FILE_STATUS.COMPLETESWFUpload.FILE_STATUS.COMPLETESWFUpload.FILE_STATUS.SWFUpload.FILE_STATUS.SWFUpload.CURSOR.ARROWSWFUpload.CURSOR.ARROWSWFUpload.CURSOR.HANDSWFUpload.CURSOR.HANDSWFUpload.WINDOW_MODE.WINDOWSWFUpload.WINDOW_MODE.WINDOWSWFUpload.WINDOW_MODE.OPAQUESWFUpload.WINDOW_MODE.OPAQUESWFUpload.WINDOW_MODE.TRANSPARENTSWFUpload.WINDOW_MODE.TRANSPARENTuploadStart()方法中返回了 false上传被取消了上传被终止了文件正在队列中等待上传文件正在上传文件在添加到队列或是上传的时候出现了错误文件已上传成功文件被取消上传鼠标以箭头显示鼠标以手形显示Flash 按钮会显示在页面的所有 dom元素上面允许其他dom元素覆盖住Flash按钮