README

一个跨浏览器的Ajax文件上传JavaScript插件。支持拖放、CORS和带有进度条的多个文件上传。在IE7-9、移动设备和所有现代浏览器中工作。

var uploader = new ss.SimpleUpload({
      button: 'upload-btn', // HTML element used as upload button
      url: '/PathTo/UploadHandler', // URL of server-side upload handler
      name: 'uploadfile' // Parameter name of the uploaded file
});

功能

• 跨浏览器 - 在IE7+、Firefox、Chrome、Safari、Opera中工作
• 支持多个并发文件上传（即使在非HTML5浏览器中）
• 内置CORS支持
• 拖放文件上传（v2.0新增）
• 无Flash或外部CSS - 单个6Kb的JavaScript文件（已压缩和gzip压缩）
• 所有浏览器中的进度条，包括IE9和更早版本。内置对以下的支持
  • Nginx上传进度模块
  • PHP APC文件上传进度
  • PHP会话上传进度
• 使用任何HTML元素作为上传按钮
• 无依赖项 - 可与或无jQuery使用
• 为支持XHR的浏览器和不支持XHR上传的浏览器提供单独的回调函数
• 能够在请求中传递自定义头信息，例如认证头

常见问题解答

访问新的 常见问题解答 了解最常见问题的解决方案。

如何使用

实时演示
API参考
IE9（及更早版本）中的上传进度条
CORS - 使用Simple Ajax Uploader进行跨域文件上传

使用此插件主要有两种方式

1. 单个文件上传 - 每次只允许一个上传。进度条是每个上传重用的元素。
2. 多个文件上传 - 允许多个并发文件上传。在每次上传之前动态创建进度条。

方法1：单个文件上传（一次一个文件）

在每次上传之前，在 onSubmit() 回调函数中，使用这两个函数将页面上的 sizeBox 和 progress 元素分配给特定角色

setProgressBar(elem) - 将元素指定为上传的进度条。
setFileSizeBox(elem) - 将元素指定为插入上传文件大小的容器。

因此，当上传开始时，上传文件的大小将插入到 sizeBox 元素中，并将 progress 元素的CSS宽度设置为0%。随着上传的进行，progress 元素的CSS宽度百分比将相应更新。

这种将角色分配给元素的方法为开发者提供了很大的灵活性 - 进度指示器可以以任何方式样式化并放置在页面的任何位置。

var sizeBox = document.getElementById('sizeBox'), // container for file size info
    progress = document.getElementById('progress'); // the element we're using for a progress bar

var uploader = new ss.SimpleUpload({
      button: 'uploadButton', // file upload button
      url: 'uploadHandler.php', // server side handler
      name: 'uploadfile', // upload parameter name        
      progressUrl: 'uploadProgress.php', // enables cross-browser progress support (more info below)
      responseType: 'json',
      allowedExtensions: ['jpg', 'jpeg', 'png', 'gif'],
      maxSize: 1024, // kilobytes
      hoverClass: 'ui-state-hover',
      focusClass: 'ui-state-focus',
      disabledClass: 'ui-state-disabled',
      onSubmit: function(filename, extension) {
          this.setFileSizeBox(sizeBox); // designate this element as file size container
          this.setProgressBar(progress); // designate as progress bar
        },         
      onComplete: function(filename, response) {
          if (!response) {
              alert(filename + 'upload failed');
              return false;            
          }
          // do something with response...
        }
});        

方法2：多个文件上传

以下是如何实现带有进度条的多文件上传的示例。在 onSubmit() 回调函数中为每个文件上传创建一个新的进度条。

与方法1类似，使用 setProgressBar() 和 setFileSizeBox() 函数分配新创建的元素的角色。然而，与上一个示例不同的是，进度元素在上传完成后会自动删除。

var uploader = new ss.SimpleUpload({
      button: 'uploadButton',
      url: 'uploadHandler.php', // server side handler
      progressUrl: 'uploadProgress.php', // enables cross-browser progress support (more info below)
      responseType: 'json',
      name: 'uploadfile',
      multiple: true,
      allowedExtensions: ['jpg', 'jpeg', 'png', 'gif'], // for example, if we were uploading pics
      hoverClass: 'ui-state-hover',
      focusClass: 'ui-state-focus',
      disabledClass: 'ui-state-disabled',   
      onSubmit: function(filename, extension) {
          // Create the elements of our progress bar
          var progress = document.createElement('div'), // container for progress bar
              bar = document.createElement('div'), // actual progress bar
              fileSize = document.createElement('div'), // container for upload file size
              wrapper = document.createElement('div'), // container for this progress bar
              //declare somewhere: <div id="progressBox"></div> where you want to show the progress-bar(s)
              progressBox = document.getElementById('progressBox'); //on page container for progress bars
          
          // Assign each element its corresponding class
          progress.className = 'progress progress-striped';
          bar.className = 'progress-bar progress-bar-success';
          fileSize.className = 'size';
          wrapper.className = 'wrapper';
          
          // Assemble the progress bar and add it to the page
          progress.appendChild(bar); 
          wrapper.innerHTML = '<div class="name">'+filename+'</div>'; // filename is passed to onSubmit()
          wrapper.appendChild(fileSize);
          wrapper.appendChild(progress);                                       
          progressBox.appendChild(wrapper); // just an element on the page to hold the progress bars    
          
          // Assign roles to the elements of the progress bar
          this.setProgressBar(bar); // will serve as the actual progress bar
          this.setFileSizeBox(fileSize); // display file size beside progress bar
          this.setProgressContainer(wrapper); // designate the containing div to be removed after upload
        },
        
       // Do something after finishing the upload
       // Note that the progress bar will be automatically removed upon completion because everything 
       // is encased in the "wrapper", which was designated to be removed with setProgressContainer() 
      onComplete:   function(filename, response) {
          if (!response) {
            alert(filename + 'upload failed');
            return false;
          }
          // Stuff to do after finishing an upload...
        }
});

对于多个文件上传，我们使用一个额外的函数：setProgressContainer(elem)。此函数指定一个元素，在上传完成后将其从DOM中移除。

在示例中，使用setProgressContainer()设置的将被移除的元素是进度元素的父容器。因此，每次上传完成后，进度条将从DOM中移除。

表单集成

要将插件与现有表单集成，以便文件上传包括表单中包含的所有输入字段，只需将表单元素传递给form选项，或使用setForm( form )实例方法。

表单集成尊重任何HTML5验证属性。无效的输入值将阻止上传发生。

默认情况下，插件将覆盖表单的原生提交。提交尝试将被捕获，并使用表单数据一起上传文件。要禁用此行为，将overrideSubmit设置为false。将overrideSubmit设置为false将需要手动调用submit实例方法，以便一起上传文件和表单数据。

注意：仅在需要将文件上传与表单一起提交时使用表单集成。

跨浏览器辅助函数

为了简化对旧浏览器的支持，插件包含一组回调函数，允许根据用户的浏览器是否支持XHR上传/HTML5文件API定义特定的行为。

startXHR(filename, fileSize) - 在上传之前调用 -- 仅在支持XHR上传的浏览器中
endXHR(filename) - 在上传完成后调用 -- 仅在支持XHR上传的浏览器中
startNonXHR(filename) - 在上传之前调用 -- 仅在不支持XHR上传的浏览器中
endNonXHR(filename) - 在上传完成后调用 -- 仅在不支持XHR上传的浏览器中

一个常见的用例是在支持progress事件的浏览器中显示上传进度条，同时在旧浏览器中显示动画GIF。

var progress = document.getElementById('progress'), // progress bar
    loaderImg = document.getElementById('loaderImg');  // "loading" animated GIF
                
var uploader = new ss.SimpleUpload({
      button: 'uploadButton',
      url: 'uploadHandler.php', // server side handler
      responseType: 'json',
      name: 'uploadfile',
      hoverClass: 'ui-state-hover',
      focusClass: 'ui-state-focus',
      disabledClass: 'ui-state-disabled',
      startXHR: function(filename, size) {                   
          progress.style.display = 'inline-block'; // show progress bar            
          this.setProgressBar(progress); // designate as progress bar
      },
      endXHR: function(filename) {
          progress.style.display = 'none'; // hide progress bar
      },
      startNonXHR: function(filename) {
          loaderImg.style.display = 'inline-block'; // show animated GIF
      },
      endNonXHR: function(filename) {
          loaderImg.style.display = 'none'; // hide animated GIF
      }
});

从startXHR()和startNonXHR()返回false将阻止上传开始，就像它对onSubmit()和onChange()所做的那样。

服务器端文件处理

文件通过POST以原始表单数据或常规multipart/form-data的形式上传，具体取决于浏览器。

使用Uploader.php

注意：此PHP类仅为了方便而包含。使用Simple Ajax Uploader不需要PHP。插件对服务器配置无依赖性，因此可以使用您喜欢的任何语言。

<?php
require('Uploader.php');

$upload_dir = '/img_uploads/';
$valid_extensions = array('gif', 'png', 'jpeg', 'jpg');

$Upload = new FileUpload('uploadfile');
$result = $Upload->handleUpload($upload_dir, $valid_extensions);

if (!$result) {
    echo json_encode(array('success' => false, 'msg' => $Upload->getErrorMsg()));   
} else {
    echo json_encode(array('success' => true, 'file' => $Upload->getFileName()));
}

您还可以通过设置newFileName属性将上传的文件保存为不同的名称

$Upload = new FileUpload('uploadfile');
$ext = $Upload->getExtension(); // Get the extension of the uploaded file
$Upload->newFileName = 'customFileName.'.$ext;
$result = $Upload->handleUpload($upload_dir, $valid_extensions);

要访问新上传的文件，使用getSavedFile()方法获取上传完成后文件路径

$Upload = new FileUpload('uploadfile');
$result = $Upload->handleUpload($upload_dir, $valid_extensions);

if ($result) {
  $path = $Upload->getSavedFile();
  $imgsize = getimagesize($path);
  // image resizing stuff...
}

传递自定义头

var uploader = new ss.SimpleUpload({
    customHeaders: {'Authorization': 'my-access-token'},
    ...
});

拖放

通过将元素传递给dropzone选项以作为拖放区域，启用拖放上传

var uploader = new ss.SimpleUpload({
      dropzone: 'dragbox', // ID of element to be the drop zone
      url: 'uploadHandler.php',
      name: 'uploadfile',
      responseType: 'json',      
      onComplete: function(filename, response) {
          // do something with response...
      }
}); 

许可证

在MIT许可证下发布。