大名鼎鼎SWFUpload是一款结合了Flash和JavaScript的文件上传工具

简介：
请介绍一下SWFUpload是什么。它最初是由Denys Vinterweeb在2016年开发的，旨在整合Flash与JavaScript技术以实现WEB开发者的一个强大文件上传功能。 这个工具相比传统标签提供了更高效的文件上传方式，并且支持多种高级功能如无刷新显示上传进度、良好的浏览器兼容性以及与其他JavaScript库（如jQuery和Prototype）的无缝集成。它特别适用于需要处理Flash 8和Flash 9文件的场景，允许开发者通过自定义样式表XHTML、CSS和JavaScript来设计界面并实现动态效果。 SWFUpload在使用前要求开发人员具备一定的JavaScript和DOM知识，并强调在实际开发中，由于错误设置或不恰当的事件处理可能导致上传失败。为了避免这种情况，在初次使用时建议先进行测试以确保配置无误。 请介绍一下SWFUpload是什么。它最初是由Denys Vinterweeb在2016年开发的，旨在整合Flash与JavaScript技术以实现WEB开发者的一个强大文件上传功能。 这个工具相比传统标签提供了更高效的文件上传方式，并且支持多种高级功能如无刷新显示上传进度、良好的浏览器兼容性以及与其他JavaScript库（如jQuery和Prototype）的无缝集成。它特别适用于需要处理Flash 8和Flash 9文件的场景，允许开发者通过自定义样式表XHTML、CSS和JavaScript来设计界面并实现动态效果。 SWFUpload在使用前要求开发人员具备一定的JavaScript和DOM知识，并强调在实际开发中，由于错误设置或不恰当的事件处理可能导致上传失败。为了避免这种情况，在初次使用时建议先进行测试以确保配置无误。 在发行包（SWFUpload v2）中含有两个版本的Flash控件（swfupload_f8.swf 与wfupload_f9.swf），其中第一个版本拥有最佳的兼容性，但是为此损失了部分功能；而第二个版本提供了一些附加的功能但是损失了兼容性。请提供具体的文档内容： http://www.v-sky.com/docs/swf/upload-v2.1.0/Documentation.html 特别提醒： 受Flash Player 10升级影响，SWFUpload V2.2.0之前的程序出现不兼容问题。具体说明请参考《Flash Player 10升级导致SWFUpload程序异常》一文。本版本及以后的更新将提供更详细的安装和使用指导，并且V2.1.0帮助文档不再支持，请用户及时查阅最新版本文档并停止使用V2.1.0。 TOC SWFUpload 版本二 概述 入门指南 SWFUpload JavaScript 对象构造器 全局变量和常量列表（instances） 实例信息（instances） movieCount 记录（电影数量） 队列错误信息（QUEUE_ERROR） 上传错误集合（UPLOAD_ERROR） 文件状态码集合（FILE_STATUS） 默认事件处理机制 设置配置对象： - customSettings：自定义设置管理器 - movieName：视频名称获取方法 操作方法： - addSetting、getSetting和retrieveSetting不再推荐使用，建议采用destroy或displayDebugInfo等新方法 用户交互功能扩展： 文件选择（selectFile） 多文件选择（selectFiles） 上传启动（startUpload）、取消上传（cancelUpload）及完成状态管理（stopUpload） 数据统计与报告： 获取上传统计数据（getStats）、设置统计数据（setStats）、获取文件信息（getFile）及处理后缀参数 网络传输控制： 添加和移除上传相关参数 文件限制配置： 设定文件大小上限、上传流量阈值、队列大小限制、文件名称前缀等参数 事件监听功能扩展： 触发Flash完成时（flashReady）、上传成功/失败事件（swfUploadLoaded、UPLOAD_ERROR）、文件选择阶段结束（fileDialogStart）及后续状态变化 开发文档辅助： 获取调试信息（debug） SWFUpload 功能对象集合 设置对象描述符：提供详细配置参数说明和示例使用方法 文件对象管理：支持不同文件类型和大小限制的设置 统计分析模块：收集并展示上传数据报告 插件扩展接口：为第三方工具集成提供接口 问题排查指南： 常见错误记录（QUEUE_ERROR、UPLOAD_ERROR等）及处理建议 开发环境配置说明： 安装步骤与依赖项要求 SWFUpload 是由Vinterwebb.se开发的客户端文件上传工具，整合了Flash和JavaScript的功能，超越传统浏览器中的标签提供的文件上传能力。 SWFUpload提供的主要功能涵盖了文件上传、转换与存储的核心组件。 在文件选择对话框中支持从多个位置批量选择文件上传。 通过事件回调函数实时追踪文件上传进度，并动态更新用户关于上传进程的最新信息。 该组件适用于主流浏览器环境，确保在不同设备上都能获得良好的用户体验。 (例如 jQuery、Prototype等)该组件采用命名空间机制以确保与其他JavaScript库的兼容性。 支持FlashPlayer版本为8.0及以上的版本。 SWFUpload的设计理念与基于Flash的传统上传工具存在显著差异。该软件将用户界面的控制权授予开发团队，让他们能够根据自身网站的风格需求进行个性化设计或构建相关功能模块。基于此，开发团队能够通过一组简单的JavaScript事件来实时更新上传进度信息，从而实现对上传过程的有效监控和管理。该软件版本增加了若干先进功能，显著提升了稳定性能，并成功修复了FlashPlayer中的若干技术缺陷。此外，新增的一组实用工具包也应运而生。这些新增的功能大体可分为以下几个类别： 在文件上传的同时，系统支持向后端发送额外的POST数据（仅适用于Flash 9版本）。每当单个文件被上传时，系统会向后端提交相应的POSTGET请求。提供更为直观的事件反馈机制，允许用户通过配置实现实例属性的动态更改。支持通过配置实现实例属性的动态更改。 在IE浏览器中，当页面刷新时无法加载FLASH内容（详细过程可见之前调试记录）。在Firefox中，若窗口滚动条未归位至顶部，则会导致Flash无法加载。防止文件缓存过程中出现的竞态条件错误，并确保其兼容性与现有解决方案保持一致。 SWFUpload v2 继续贯彻其设计理念，并将用户界面从开发团队手中剥离以便进行后续扩展。传统的HTML 上传界面通常包含一个文本字段和一个按纽设计元素。用户在提交表单时可选择任意文件并将其传递给服务器处理。完整的文件传输过程完成后，相关的内容才会被正确加载和展示。值得注意的是，在这一过程中，用户几乎无法获得实时反馈或确认信息。此外，传统的HTML 上传机制并未对所选文件进行预设限制，例如大小、类型等标准要求在上传前无需做特别检验。资源采用传统HTML上传模式较为简便，其过程直接且适用于所有主流浏览器。SWFUpload通过一个隐藏的Flash视频片段来控制文件的选择和上传过程。由JavaScript触发的事件实现了文件选择对话框的功能。该对话框设计允许用户选择单一文件或者多个文件进行上传操作。在设置参数时可以限定文件类型，从而确保仅接受指定格式的数据文件，例如*.jgp、*.gif等格式的图片。一旦选择文件后，所有文件将依次进行校验与处理。每当Flash接收待上传文件时，系统会自动启动预先配置好的JavaScript事件以更新页面用户界面，并同时反馈上传进度以及可能出现的任何问题提示。 文件的上传过程与所在页面、表单操作相互分离。所有文件均采用独立上传的方式处理，从而确保服务端脚本能够在同一个时间段内更高效地处理每个文件。尽管Flash提供了一定的上传功能，但页面内容不会被重传或刷新。相较于传统的HTML表单结构，采用SWFUpload进行文件上传的操作流程更接近于一种 AJAX式的请求处理机制。 入门 SWFUpload并非采用传统的拖放式文件上传方式，而是在实现功能的过程中需要用到JavaScript语言以及与之相关的DOM技术基础。通过一系列实际操作案例可以看出该控件具备哪些具体功能，并且能清晰地解释其在处理常见操作时的操作逻辑。 SWFUpload包含四部分：初始化时需进行参数配置 JavaScript库: SWFUpload.js 该类的名称为SWFUpload.js 其对应的图形文件分别为SWFUpload_f8.swf和SWFUpload_f9.swf 在实际应用中，利用该类可能会遇到的问题通常与错误地设定或误操作导致的异常处理有关。初始化和设置部分进行改写： SWFpload应在页面上执行初始化操作，通常可以在所有网页元素加载完毕时通过window.onload事件来完成。它的构造函数需要接受一个配置参数。 这个配置参数一般是由开发者预先定义好的Object类型变量，然后直接传递给SWFUpload的构造函数以获取实例。初始化的SWFUpload对象的引用必须保持不变，因为在用户进行文件选择和上传操作时，必须保持该对象引用不变。用直接定义的Object类型变量设置初始化SWFUpload对象。var swfu;在窗口加载事件中，将存储在变量中的设置对象初始化为SWFUpload实例。var swfu; 当窗口加载时调用函数window.onload。创建一个对象settings_object并将其赋值为以下字段：将upload_url字段指定为$...http:www.swfupload.orgupload.php$；设置flash_url属性为$...http:www.swfupload.orgswfupload_f9.swf$，并将file_size_limit设为20480。 swfu = new SWFUpload(settings_object); }; JavaScript 工具包 该SWFUpload组件库应部署于需要上传功能的网页中。它适用于Flash Player 8及Flash Player 9的SWFUpload版本。 当 SWFUpload 准备好并能够访问其一系列功能后，开发人员就能够有效地管理该实例。如：在网页上加入SWFUpload.js文件。基于用户的设置要求启动SWFUpload，并将seleteFiles方法注册为按钮点击事件响应函数var swfu = swfupload.create(); 设置相关Url字段值 上传文件的URL字段值设为http://www.swfupload.orgUpload.php， 展示文件的URL字段值设为http://www.swfupload.orgSWFUpload_F9.SWF。当双击此按钮时，会自动加载相关的Flash控件。$...$SWFUpload是一个能够动态地将Flash控制元素插入到网页中的JavaScript库。该版本支持Player8及以上，并且在保证兼容性的同时保留了更多功能。另一个版本则更适合需要支持更高Player9.0.28及以上用户的需求。必须预先在其SWFUpload设置对象中设定好Flash控件的文件路径。Flash控制元素是隐藏起来的一个Flash文件，它允许执行文件操作，包括查看、验证以及上传内容。这个控制元素本身不含任何用户交互界面，但当需要时，会通过与JavaScript进行通信以通知相关操作已完成。 开发团队应创建一组JavaScript函数以响应与SWFUpload相关的事件调用，在某些关键事件被触发时，这些函数将执行相应的操作。通过响应SWFUpload事件，开发人员能够向开发者传递包括上传进度报告、具体出错信息和完整的文件传输确认书在内的详细状态更新报告。swfupload响应处理其下载事件，并开始加载过程处理上传启动事件。此函数变量被指定用于将$uploadStartEventHandler指派给$upload_start_handler属性。 函数或方法结束时返回继续上传操作。var uploadSuccessEventHandler = function (file, server_data) { 该事件的处理由函数变量完成。 在配置中将此变量指定为upload_success_handler属性。 } alert(file.name already delivered to server); alert(server returned server_data); 创建一个SWFUpload实例并配置事件处理函数： var swfu = new SWFUpload({ upload_url: http://www.swfupload.org/upload.php, flash_url: http://www.swfupload.org/swfupload_f9.swf, file_size_limit: 20480 }); SWFUpload 对象的构造函数用于初始化上传相关功能。该对象包含两个绑定在特定事件处理程序中的属性：uploadStartHandler 和 uploadSuccessHandler，分别对应初始化上传和完成上传操作的回调函数。返回: 该实例的 SWFUpload 实例var swfupload_instance = new SWFUpload(settings_object); 全局变量与常量 SWFUpload定义了一系列全局变量与常量，这些对于提升其高级应用程序性能及有效处理异常情况具有重要意义。这些均为只读状态。SWFUpload.instances是一个专门收集了页面中的所有Flash文件上传实例的数组。该数组被用来确保播放器正确触发相关的事件处理。其中每个条目都基于movieName属性进行链接，从而实现了对不同Flash文件引用的准确管理。这个数组中的第一条目与第一个Flash文件上传实例相关联。注意: SWFUpload.instances并不是一个真正的JavaScript数组，实际上它是一个对象（关联数组）。这是一个对象类型，并且属于关联数组类别。SWFUpload.movieCount 被定义为全局变量，用于统计页面内的所有 SWFUpload 实例的数量，同时确保每个 Flash 文件被赋予一个独一无二的 movieName。SWFUpload.QUEUE_ERROR是一个专门包含Queue Error相关错误代码的JavaScript对象。这个对象通常用于获取在fileQueueError事件中传递过来的错误信息，并通过这些信息来判断fileQueueError事件的具体类别。 SWFUpload.ERROR_QUEUE = { QUEUE_LIMIT_EXCEEDED: -100, FILE_EXCEEDS_SIZE_LIMIT: -110, ZERO_BYTE_FILE: -120, INVALID_FILETYPE: -130 }; SWFUpload.UPLOAD_ERROR 该JavaScript对象包含Upload Error相关的错误编码信息，通常用于获取与 uploadError 事件相关联的 错误 码。进而确定 uploadError 的具体 类型。 SWFUpload.UPLOAD_ERROR = { HTTP错误码：-200， 缺少上传URL：-210， I/O错误：-220， 安全性错误：-230， 上传限制超出：-240， 上传失败：-250， 指定文件ID不存在：-260， 文件验证失败：-270， 文件取消 uploads：-280， 上传停止：-290 }; SWFUpload.FILE_STATUS是一个包含File Status状态码的JS对象。它能够用来检测File对象中的file status属性，以确定文件的状态。 默认处理事件 SWFUpload库包含一系列预设处理事件。当开发人员未定义自定义处理事件时，默认情况下SWFUpload会调用这些预设处理事件。因此，在设置自定义处理事件时，请避免覆盖这些默认的预设处理事件。自定义的处理事件必须在settings对象中单独进行配置以确保正确执行。以下列出的是与SWFUpload相关的各个属性的详细说明：如果尝试修改其他属性或对不可写属性进行编辑操作，则可能导致SWFUpload功能异常。 这是一个空置的JavaScript对象变量，用于存储与SWFUpload实例相关联的数据信息。该属性可以根据需要对其字段进行配置和初始化操作。请特别注意，在使用一些插件时，它们会借助 customSettings 对象来实现自身对内部控制的管理。当需要对 entire customSettings 进行重写或修改时，请务必谨慎小心。该资源旨在为用户提供高效的计算解决方案。 数学公式$...$保持不变以确保准确性。var swfu = new SWFUpload({ configuration : { custom_setting_1 : value_1, custom_setting_2 : value_2, custom_setting_n : value_n } });swfu.customSettings.第一个自定义参数被设定为target_custom_parameter_value; 更改一个现有的自定义设置。swfu.customSettings.新的自定义参数被设定为newly defined default parameter value; 添加一个新的自定义设置。 用一个全新的对象重写了customSettings. swfu.customSettings = { custom_setting_A : custom_setting_value_A, custom_setting_B : custom_setting_value_B }; movieName（不可编辑属性） 是唯一对应于当前实例在SWFUpload.instances数组中的具体位置信息。该值被传递给Flash，用于完成与JavaScript之间的通信过程。通过这个值可以确定该视频文件在整个列表中所处的精确位置。 这些方法用于操作SWFUpload功能。其中一些方法能够与元素（如按钮）的点击事件绑定，而其他的方法则用来处理内部事件中的调用。object addSetting(setting_name, value, default_value)函数getSetting接收一个参数setting_name。注释表明，addSetting和getSetting已弃用，但为了支持V2.0版本的兼容性，仍保留在库中。object retrieveSetting(setting_value, default_value)在v2.1.0版本内已被移除在版本号v2.1.0中新增了destroy boolean类型的函数 旨在删除位于页面上的所有SWFUpload实例。不仅会移除DOM中的Flash元素，还会清除该文件的所有引用。若操作成功，则返回布尔值true；否则返回布尔值false。这个方法尚未对插件进行兼容性测试，可能导致插件不兼容的问题。（尤其是SWFObject类插件）该软件在版本号v2.1.0时对Flash文件的导入代码进行了优化。在该版本中采用SWFObject格式导入Flash可能引发IE浏览器的一次刷新异常。该函数通过执行 debug 方法实现功能，在文本框中以文本形式展示 SWFUpload 实例的相关配置参数。当该实例的 debug 设置为 true 时，默认会在实例化完成后自动执行此函数。selectFile()函数用于打开Flash文件选择对话框，并仅允许用户一次选择一个文件。在selectFiles()函数中，调用Flash的文件选择对话框并允许一次性选择多个文件。这个函数声明定义了一个名为startUpload的成员函数，它接受一个参数file_id。该函数的作用是根据提供的file_id来启动相应的文件上传操作。如果没有提供有效的file_id或该参数被忽略，则默认开始上传第一个可用的文件。void cancelUpload(int file_id)通过传入参数file_id实现上传操作的取消，并将该文件从上传队列中移除。当不考虑file_id的值时，在默认情况下，第一个文件会被从队列中删除上传。当试图撤销一个被实时上传中的文件时，该系统将导致uploadError事件的发生。 void stopUpload() 如果当前存在文件上传操作，则阻止该操作并恢复文件至暂存队列中进行处理。 阻止了当前文件上传操作后，uploadError事件会被触发。当不再存在上传任务时，将不进行任何操作也不会引发相关事件。 class getStats() void setStats(stats_object) 注释： Stats统计对象具有可变性。若希望在数据上传完成后修改成功或失败的统计数据数量，则可以调用该方法。 提醒：可调整的属性仅包括successful_uploads、upload_errors、upload_cancelled及queue_errors四个字段，并且这些字段的数据类型必须为Number。 获取指定的文件队列中的文件对象。通过指定的参数file_id或index可以实现对文件对象中id属性和index属性的获取。 传递Number类型的参数会被视为index，它会返回位于该数组指定位置（由index确定）的所有文件对象集合中下标为index的那个文件对象。如果index超出了队列数组的有效索引范围，则函数将返回null值。 当接收的参数不是数值类型时，将被视为file_id。返回其在通过文件检测准备上传至服务器的队列中、具有该file_id标识符的文件实体。若参数为空或未找到对应于该file_id的文件实体，则将从候存队列中取出最先处理的第一个待上传的文件实体；若该实体为空，则返回null。在配置文件中为post_params字段赋值，在处理文件上传时，这些赋值将作为POST数据一同发送出去。在配置过程中，如果post_params中的该值同时存在，则会使得其数值被替代。该函数通过指定参数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数据。当POST设置中缺少该属性时，将不再返回true。The function void setUploadURL(url) is designed to dynamically modify the upload URL attribute within the settings. void setPostParams(param_object) 动态更新post_params，之前的设置全部丢失。param_object必须是一个JavaScript的原生数据类型，只能接受字符串类型的属性。 此函数名为SetFileTypes，用于接受两个必填的参数：类型和描述。 void setFileSizeLimit(size_t &fileSizeLimit) { 动态更改文件大小限制参数fileSizeLimit。该改动将影响后续的文件大小过滤逻辑。其中size_t类型的参数fileSizeLimit接收不同的存储单位，包括字节（B）、千字节（KB）、兆字节（MB）和吉字节（GB），默认采用千字节作为单位。}如以下数据：2147483648字节, 2097152, 2097152MByte, 2048 MB, 2 Gigabit根据需求进行配置中fileUploadLimit的设置，其中其数值为0时，表示不限制上传次数。函数名称：setFileUploadLimit；参数名：fileUploadLimit具体说明：SWFUpload实例的上传成功文件数量受到限制 该函数用于动态调整配置中的文件队列限制值。当该参数被指定为0时，则表示无限制。 须知此为系统规定，对文件上传队列的管理措施将被实施（仅当文件满足入队条件时才可加入待传队列）以确保资源的有效利用。经入队检测符合条件的文件会被纳入待传队列进行处理。该规定旨在限制因排队而无法及时处理的最大允许多余文件的数量。 实现实时更新$setFilePostName$函数，须特别留意，在Linux系统中，该设置会被忽略。 void setUseQueryString(use_query_string)动态地修改设置中的use_query_string字段值。当该字段被设置为true时，SWFUpload将通过GET方式发送数据；而当该字段被设置为false时，则采用POST的方式发送数据。 void set DebugOutputEnableddebug_enabled 该函数用于设置一个布尔型变量以决定是否禁止debug信息的显示。在运行过程中SWFUpload会触发多个事件，在这些事件中开发者可以响应和处理多个事件从而实现对用户界面、操作流程以及错误信息的管理每个事件都在SWFUpload实例的执行上下文中被触发，在这些回调的事件中使用this能够直接获取该触发该事件的具体对象实例。此事件函数为内部事件，因此无法进行修改。该事件会在 SWFupload 实例化并完成全部初始化步骤后触发。提示：在设置中对应的特定的事件swfupload_loaded_handler swfUploadLoaded函数在V2.1.0版本中已取消该事件fileDialogStart()函数会在selectFile或selectFiles被调用后触发，并且仅允许打开一个文件选择框。请注意，在配置选项中，请确认是否已设置了自定义的对话框启动事件$...$ file-dialog-start-handler。当文件选择框关闭消失时，如果某个文件被成功地添加到上传队列中，则对于每一个成功加入的文件，该事件会被触发一次。当有多个文件（共N个）被成功地添加到队列中时，此事件就会被触发N次。请注意：在配置设置时，请注意对应的是预定义事件中的file_queued_handler变量。 当选择文件对话框关闭取消时，如果所选文件无法成功加入到上传队列中，则该函数会针对每个出现错误的文件执行特定事件操作（此事件与fileQueued事件构成互斥触发关系，仅在文件添加到队列过程中存在两种可能结果：成功或失败） 文件添加队列出现错误可能原因之一是：文件大小超过指定上限（单位：KB），或者文件内容为零字节，也可能是由于文件数量超出队列容量限制。此外，还可能与不属于用户预先设定的有效文件类型有关。具体的错误信息可通过error code参数获取，可以通过查阅SWFUpload.QUEUE_ERROR的定义域来确定其类型。相关设置中的自定义事件file_queue_error_handler如果所选文件数量超过了配置设定期数，则导致该事件仅被触发一次。且未超过数目限制的情况下，将对每个文件进行类型及大小的检测，并在不通过的文件上触发此事件；而通过检测的文件则会成功入队。当选中文件对话框关闭并所有选中文件已处理完毕（包括成功入队和失败入队的情况）时，该事件会被触发。此函数用于获取两个关键信息：选中的文件数量（number of files selected）以及此次选择的文件中有多少已经成功地加入到上传队列中（number of files queued）。请注意，在配置管理中找到自定义功能块时，请注意该功能块为file_dialog_complete_handler设置相关参数 请记住，如果你希望文件在选择以后自动上传，在这个事件中调用this.startUpload() 是一个最佳实践。为了更严格地控制流程，在上传前确认队列中的文件数量大于零时，则可以执行上传操作。 请注意：如果希望文件在选定之后自动上传，请在此事件中触发$...$函数作为一个推荐方案。为了更加细致的管理流程，在执行上传操作之前，请检查队列中的文件数目是否超过零，若确实大于零，则可以开始上传过程。initiateUploadStart(文件对象)：在将文件发送至服务端之前执行此操作。您可以在其过程中进行最终验证，并对现有数据进行增删改运算等预处理任务。 在完成最终步骤之后，若该函数返回布尔值false，则此操作将导致该上传不再执行；进而引发uploadError事件（代码为ERROR_CODE_FILE_VALIDATION_FAILED）。与此相反的情况是，当函数返回true或无返回值时，该上传将执行相应的启动流程。 须知，在该设置中，存在一个自定义事件名为upload_start_handler。 此函数接收三个参数：首先为待上传的文件对象；其次为已完成的字节数；最后为总字节数。此事件经由Flash定时器触发，可据此事件定期更新页面中的UI元素，从而实时反映上传进度。通过该事件，可以在适当的时间间隔内更新页面的UI组件，进而提供动态展示文件上传进度的功能。注意：在Linux环境下，Flash Player仅当所有文件已上传完成后才会触发一次特定事件。据官方表示，这是一个Linux Flash Player的缺陷。目前该库尚未找到有效的解决方案，并且本人也未曾进行相关测试。特别提示：请留意在相关设置中查找并配置自定义事件 upload_progress_handler。 在任何情况下，如果上传操作因终止或未成功而中断，则该事件将触发。error code字段表示了当前错误类型，更具体的定义可在SWFUpload.UPLOAD_ERROR中查找。message字段存储了错误信息。file字段指定了上传失败的文件对象。例如，在服务端尝试访问一个未定义的文件处理页面时，服务器将返回错误代码-200并发送消息404。停止、退出或uploadStart操作失败（返回false）、HTTP错误、输入接口错误以及文件上传数量已超过限制等因素都可能引发该事件。对于官方解释，我仍有疑问：如果文件已被取消但仍在队列等待处理，为何不会触发 Upload 错误？提醒：在配置中指定的特定事件类型对应的是 upload_error_handler请记住：当前文件上传的周期尚未结束，必须避免在此处开始下一文件的上传操作。 uploadSuccess(file object, server data) 该事件会在以下两种情况发生时被触发：首先，文件上传任务已完成（即目标处理程序已成功发送Files信息），其次，服务端返回了HTTP 2xx响应。请注意设置中的自定义的事件对象upload_success_handler 注意：当使用SWFUpload的9.0版本时，server data由服务端处理程序返回。 在8.0版本中，server data缺失且保持为undefined状态。 当前文件上传流程尚未完成，在此阶段无法启动后续文件的上传任务。 当在Windows平台上采用9.0版时，服务端处理程序完成文件存儲后需返回非空结果；若未满足这一条件，则上传事件将无法触发。 一旦上传队列中的某个文件完成一轮传输——无论成功（通过uoloadSuccess引发）还是失败（通过u onloadError引发），uploadComplete事件就会触发。此时，我们已经完成了当前文件的上传，并准备好接收下一个。 当需要执行多个文件的自动上传操作时，此时调用this.startUpload()启动下一个文件的上传是一个合适的策略。提醒：请注意对应设置中的特定事件 upload_complete_handler在处理多文件上传操作时，若发现正在上传的文件被调用cancelUpload函数会中止当前上传操作。类似地，使用stopUpload方法也会暂时阻止当前文件上传。然而，在随后触发的uploadComplete事件中，必须特别注意调用this.startUpload()的方法。这是因为上述两种情况会导致 uploadError 与 uploadComplete事件按优先级顺序执行：即一旦中止了当前上传流程，就会立即开始处理下一个文件的上传。这种做法可能让人感到困惑，但实际上程序运行是正确的。如果希望完全停止自动上传过程，则需要进行额外的程序干预以实现目标。如果debug setting设为true，则在页面底部自动生成一个新的textarea元素，并触发两个库的调用：swfupload和flash。此事件会触发两个库的调用：swfupload和flash，从而将所有相关的调试信息写入到该 textarea 元素中以供调试使用。注意：在配置参数中指定的自定义事件debug_handler用于监控系统运行状态 The settings object is an Object-type variable. It serves as a configuration source for initializing the SWFUpload instance. Each configuration attribute can occur at most once. Many attributes are optional; if not specified, default values from the SWFUpload library will be used as defined in setting. 例如, 设置允许用户自定义所有属性 upload_url : http://www.swfupload.org/upload.php, file_post_name : 文件数据， post_params : 配置参数{ post_param_name_1 : 参数值1, post_param_name_2 : 参数值2, ..., post_param_name_n : 参数值n }, 不采用明文方式提交文件：false, 重传失败时不会自动重新上传：false, 文件大小限制为1024像素： false， 最大上传次数：10次， 文件队列处理时间限制：2秒， 支持的图片格式包括JPEG和GIF等， 图片格式描述为通用图像文件类型： Web Image Files, 上传文件大小限制为10MB: true, Flash播放链接： http://www.swfupload.org/swfupload_f9.swf, 插播Flash宽度设置为1像素： false， 插播Flash高度设置为1像素： false， 插播Flash颜色设置为纯白色： #FFFFFF， 开发调试功能：false swfUploadLoadedHandler: swfUploadLoadedFunction, fileDialogStartHandler: fileDialogStartFunction, fileQueueedHandler: filequeuedFunction, fileQueueErrorHandler: file_queue_error_function, fileDialogCompleteHandler: 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， debugHandler： debugFunction 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文件完整的全路径字符串，并建议采用完整绝对路径以防止浏览器和FlashPlayer因修改基准路径而导致的请求路径错误。须知此方面涉及的包括FlashPlayer的安全域模型。文件名称的默认值为Filedata。(仅在Flash 9版本中可用)该字段指定... uploadImg属性（类似于传统的表单形式）。需要注意的是，在Linux系统中，该参数不可用。它始终是Filedata。为此，建议将此参数设置为默认值。post_params的默认值是空的Object对象post_params表示为一个存储有成对键值信息的object类型数据。当某个文件被上传时，在传输过程中会被一并发送至服务端。建议在设置值对时，仅允许字符串或数字作为值使用。Flash8版本不支持额外的POST参数设置，因此post_params属性会被以GET方式传输。use_query_string属性-默认值：false。 (仅在Flash 9版本中可用) 该属性的取值范围为true或false，决定了post_params采用的是GET还是POST传输方式。当其设置为false时，则以POST形式发送。变量名：在异常时重试 requeue_on_error: 在错误时重试 该属性的可取值包括true和false。当该属性被设为true时，在遇到uploadError（不包括fileQueue错误和FILE_CANCELLED错误）的情况下，文件对象会被重新入队到上传队列的前端而非丢弃。若需将该文件从队列中移除，请确保调用cancelUpload方法。 所有与上传失败相关的事件都会被一一触发。因此，重新将失效文件入队可能会导致Queue Plugin引发冲突（可能是自定义代码自动上传整个文件队列）。如果代码中调用了startUpload方法以自动上传下一个文件，同时未能采取措施让失效的文件退出上传队列，那么这个重新入队的失效文件又会开始上传，并再次失败。这样不断重复会导致无止境地将失效文件重新入队并尝试上传。该参数自v2.1.0版本开始实施。file_types的默认值：*. *配置文件选择对话框的扩展名筛选规则中，用户可指定以空格或分号分割的文件类型标识符序列。例如，“*.jpg *.gif”将仅允许在该对话框内显示和支持图片类型的图片被选中。默认状态下，支持所有的文件类型。该功能仅限于客户端浏览器进行过滤操作，并不涉及服务端文件处理中的类型筛选。若需实施更为严格的文件过滤要求，则需要在服务层面上增加相应的程序验证机制以实现。 在文件类型描述中的默认值是All Files配置文件选择对话框以呈现用户选定的文件描述。The default value for file size limit is 0. 配置文件选择界面的大文件过滤标准如下：该参数接受带有单位的数值输入，支持的单位包括B、KB、MB及GB四种类型。若未指定具体单位，则采用KB作为默认值。特别地，当输入数值为0时，表示不设置大小限制。 请注意，此配置仅在客户端浏览器上生效。无需对服务器端的文件处理进行任何限制或干预。如果希望实施严格的文件过滤功能，则必须在服务器端配置相应的程序逻辑。Default value for file upload limit is 0. 配置SWFUpload实例可指定最大上传文件数量，同时其file_queue_limit属性设定了最大值。一旦用户已成功上传或文件队列达到上限时，不能再增加新文件。特别地，若设置为0，则表示没有数量限制。仅当文件上传成功时（如触发uploadSuccess事件），该文件才计入上传总量。通过调用setStats方法，可以更新已成功上传的文件数量状态。 注意：该数值不得跨越不同页面应用使用，并且在每次浏览器刷新后也将重新获取当前状态。对于文件上传量的严格限制必须由服务器层进行实时监控和处理。file_queue_limit，默认值为其默认设置为零在文件上传队列的设置中，定义等待上传的最大文件数量上限。每当一个文件成功上传、出现错误或退出上传流程时（前提是该状态下文件队列中的文件数目尚未达到上限），则可以继续将新文件加入队列，并取代原有队列中的相应位置。此外，在允许上传的文件总数限制（file_upload_limit）或剩余上传容量不足的情况下，实际采用的数值应基于上述较小的那个数值作为限制依据。flash_url default value: empty string指定绝对或者相对于当前页面的完整URL，一旦创建了SWFupload实例后，这个配置参数将无法进行更改。提示：经过测试显示，可以使用setUploadURL方法来实现此设置的更改。flash pixel size的固定值：1px在v2.1.0版本中对该值进行了删除操作。当该设置数值低于1像素时，部分浏览器会呈现异常行为。基于此原因，在本版本中去除了自定义配置参数，并将默认值设定为1像素。flash_height is set to be 1px, a fixed numerical value.在v2.1.0版本中已不再支持自定义参数设置，现将插入flash影片的HTML元素容器高度这一操作参数正式删除。具体而言，在此参数值小于1像素时可能会导致某些浏览器出现功能异常。相应地，该属性值已被固定为默认设置的1像素，无需用户自行调整。flash_color的默认值是#FFFFFF配置HTML页面的背景颜色，并将其预设为#FFFFFF提示：为一个尺寸仅为1×1像素的Flash元素调整其背景色几乎不会带来显著的变化。这可能是一个不太值得投入的时间和资源的尝试。调试默认设置为false此数值属于boolean类型的变量，是否被捕获？在该代码中，会比较一个变量与字符串true的值是否相等。因此当此变量等于true时才认为处于调试模式启动状态。然而即使将该变量设为1，在JavaScript中仍会被认为处于调试模式启动状态，并且在初始化完成后也会触发Debug Console的显示。但在随后的操作过程中，Flash并不会输出任何调试信息。custom_settings属性的默认值被设置为空的对象对象该属性接受一种基于对象的数据结构，能够以安全的方式存储与SWFUpload实例相关联的自定义数据（如属性、事件等），无需担心其内部方法和属性冲突以及版本升级不兼容的问题。 配置完成之后，可通过该实例的 customSettings 属性进而访问。 var swfu = new SWFUpload({ setting_options : { my_setting : This is my setting, other_settings : This is another setting, integer_value : 100, dynamicSetting : document.getElementById(some_element_id) } }); var mySetting = swfu.customSettings[mySetting]; This assignment represents a significant change to the systems configuration settings. The customSetting property has been updated with additional parameters. The integer_setting attribute is incremented by twenty-five units. The a_dom customized settings have had their visibility property set to hidden. Event Handlers Default Values: null 剩下的设置对应多个响应处理的回调函数，在SWFUpload的操作执行流程中，会触发这些事件。若需在这些回调中进行自定义操作，你应该在配置文件中指定对应的JavaScript函数。File Object包含了一个名为对象的集合，这些集合包含了与文件相关的各种可用属性。许多处理事件都会通过传递一个相应的参数来获取该文件的相关属性。通过指定该ID可启动此文件的上传操作、退出上传等业务流程；表示在选定文件队列中的位置信息（包括出错、退出、排队）；文件的基本名称，不带路径标识；表示该文件的整体大小数据；对应客户端操作系统定义的特定类型标识符；记录该文件从创建到生成的时间节点；标记该文件最后一次修改的具体时间点；描述当前的状态码，可参考SWFUpload中的FILE_STATUS字段进行理解。该对象为上传队列的状态信息提供了必要的数据支持，通过调用实例的getStats方法即可获取相关信息。该对象包含其具有的属性： 当前上传进程的状态指示器$number$取值范围限定在二进制状态（可取值为1或0），其中数值为1时表明当前存在文件正在进行上传操作，反之则表示无此类操作。 等待队列中的文件总数$number$直接反映了当前的资源占用情况，其数值变化有助于及时识别可能的性能瓶颈。 已成功完成的上传数量$number$（触发uploadSuccess事件时）可作为评估系统处理能力的重要指标。 因上传操作失败而记录的文件数量$number$（不包含退出上传过程导致的数据丢失情况）构成了衡量系统稳定性的关键参数。 因退出上传而导致丢弃的文件数量$number$则反映了系统的资源释放效率。 由于入队操作失败而产生的错误记录数$number$为后续故障排查提供了重要的线索来源。 所有这些属性的取值均可以通过调用setStats方法进行动态更新，其中in_progress和files_queued两个字段除外。