#Angular File Upload
English documentation
About
Angular File Upload is a module for the AngularJS framework. Supports drag-n-drop upload, upload progress, validation filters and a file upload queue. It supports native HTML5 uploads, but degrades to a legacy iframe upload method for older browsers. Works with any server side platform which supports standard HTML form uploads.
When files are selected or dropped into the component, one or more filters are applied. Files which pass all filters are added to the queue and are ready to be uploaded.
Demos
Requires
- The AngularJS framework
- ES5 (Array.indexOf, Array.forEach, Array.filter, Array.every, Function.bind, Date.now) A shim is provided for older browsers
Includes
Directives
- ngFileSelect: Should be applied to
<input type="file" />
. The selected files are added to the uploaded queue if they have passed the filters. - ngFileDrop: Set up a drop area. Usually applied to the entire document. Caught files are added to the uploaded queue if they have passed the filters.
- ngFileOver: Should be applied to the element which will change class when files are about to be placed on the drop area. By default it adds the class
ng-file-over
but a different class can be specified with the parameter attributeng-file-over="className"
.
Service
- $fileUploader: Manages the upload queue and the uploading of files
The Uploader API:
Properties
- scope
{Object}
: Scope for HTML update, default is$rootScope
- url
{String}
: Path on the server to upload files - alias
{String}
: Name of the field which will contain the file, default isfile
- queue
{Array}
: Items to be uploaded - progress
{Number}
: Upload queue progress percentage. Read only. - headers
{Object}
: Headers to be sent along with the files. HTML5 browsers only. - formData
{Array}
: Data to be sent along with the files - filters
{Array}
: Filters to be applied to the files before adding them to the queue. If the filter returnstrue
the file will be added to the queue - autoUpload
{Boolean}
: Automatically upload files after adding them to the queue - method
{String}
: It's a request method. By defaultPOST
. HTML5 browsers only. - removeAfterUpload
{Boolean}
: Remove files from the queue after uploading - isHTML5
{Boolean}
:true
if uploader is html5-uploader. Read only. - isUploading
{Boolean}
:true
if an upload is in progress. Read only. - queueLimit
{Number}
: maximum count of files - withCredentials
{Boolean}
: enable CORS. HTML5 browsers only.
Methods
- bind
function(event, handler) {
: Registers an event handler - trigger
function(event[, params ]) {
: Executes all handlers bound to this event - addToQueue
function(items, options) {
: Add items to the queue, whereitems
is aFileList
,File
orInput
, andoptions
is anObject
- removeFromQueue
function({Item|Index}) {
: Remove an item from the queue, wherevalue
is a queue elementItem
or index - clearQueue
function() {
: Removes all elements from the queue - getIndexOfItem
function({Item}) {return {Number};}
: Returns the index of theItem
queue element - getReadyItems
function() {return {Array};}
: Return items are ready to upload - getNotUploadedItems
function() {return {Array};}
: Return an array of all pending items on the queue - uploadItem
function({Item|Index}) {
: Uploads an item, wherevalue
is a queue elementItem
or index - uploadAll
function() {
: Upload all pending items on the queue - cancelItem
function({Item|Index}) {
: Cancels uploading of item, wherevalue
is a queue elementItem
or index - cancelAll
function() {
: Cancels all current uploads
The Item API:
Properties
- url
{String}
: Path on the server in which this file will be uploaded - alias
{String}
: Name of the field which will contain the file, default isfile
- headers
{Object}
: Headers to be sent along with this file. HTML5 browsers only. - formData
{Array}
: Data to be sent along with this file - method
{String}
: It's a request method. By defaultPOST
. HTML5 browsers only. - withCredentials
{Boolean}
: enable CORS. HTML5 browsers only. - removeAfterUpload
{Boolean}
: Remove this file from the queue after uploading - index
{Number}
- A sequence number upload. Read only. - progress
{Number}
: File upload progress percentage. Read only. - isReady
{Boolean}
- File is ready to upload. Read only. - isUploading
{Boolean}
:true
if the file is being uploaded. Read only. - isUploaded
{Boolean}
:true
if the file was uploaded. Read only. - isSuccess
{Boolean}
:true
if the file was uploaded successfully. Read only. - isCancel
{Boolean}
:true
if uploading was canceled. Read only. - isError
{Boolean}
-true
if occurred error while file uploading. Read only. - uploader
{Object}
: Reference to the parentUploader
object for this file. Read only.
Methods
- remove
function() {
: Remove this file from the queue - upload
function() {
: Upload this file - cancel
function() {
: Cancels uploading of this file
Filters
Register a filter
var uploader = $fileUploader.create({
scope: $scope,
filters: [
function(item) { // A user-defined filter
return true;
}
]
});
// Another user-defined filter
uploader.filters.push(function(item) {
return true;
});
Predefined filters
Events
Supported events
- afteraddingfile
function(event, item) {
: Fires after adding a single file to the queue - whenaddingfilefailed
function(event, item) {
: When adding a file failed - afteraddingall
function(event, items) {
: Fires after adding all the dragged or selected files to the queue - beforeupload
function(event, item) {
: Fires before uploading an item - progress
function(event, item, progress) {
: On file upload progress - success
function(event, xhr, item, response) {
: On file successfully uploaded - cancel
function(event, xhr, item) {
- On cancel uploading - error
function(event, xhr, item[, response ]) {
: On upload error - complete
function(event, xhr, item, response) {
: On file upload complete (independently of the sucess of the operation) - progressall
function(event, progress) {
: On upload queue progress - completeall
function(event, items) {
: On all loaded when uploading an entire queue, or on file loaded when uploading a single independent file
Registering event handlers
var uploader = $fileUploader.create({scope: $scope});
uploader.bind('progress', function(event, item, progress) {
console.log('Progress: ' + progress);
});
FAQ
-
How to add the previously uploaded files in the queue?
// Add a item to the queue var item = { file: { name: 'Your file name', size: 1e6 }, progress: 100, isUploaded: true, isSuccess: true }; item.remove = function() { uploader.removeFromQueue(this); }; uploader.queue.push(item); uploader.progress = 100;
-
How do I deal with Cross Site Request Forgery protection?
See this issue: #40
For example, in Ruby on Rails, add an additional header, and use this method for verifying XSRF:
var csrf_token = document.querySelector('meta[name="csrf-token"]').getAttribute('content'); var uploader = $scope.uploader = $fileUploader.create({ // your code here... headers : { 'X-CSRF-TOKEN' : csrf_token // X-CSRF-TOKEN is used for Ruby on Rails Tokens }, //... });
Русская документация
О модуле
Angular File Upload - модуль загрузки файлов (html5 + iframe) для фреймворка AngularJS. Поддерживает drag-n-drop загрузку, индикацию прогресса загрузки, очередь. В старых браузерах деградирует до iframe загрузчика.
В общих чертах работа модуля выглядит так: директивы "ловят" файлы и добавляют их в очередь, если те прошли фильтры, после чего "загрузчик файлов" может ими (элементами очереди) манипулировать.
Примеры
Требует
- AngularJS фреймворк
- ES5 (Array.indexOf, Array.forEach, Array.filter, Array.every, Function.bind, Date.now)
Включает
Директивы
- ngFileSelect - применяется к
<input type="file" />
. Выбранные файлы добавляются в очередь загрузки, если они прошли фильтры. - ngFileDrop - задает область сброса файлов / элемент, который будет ловить файлы. Как правило, применяется ко всему документу. Пойманные файлы добавляются в очередь загрузки, если они прошли фильтры.
- ngFileOver - применяется к элементу, который будет реагировать (менять класс), когда файлы находятся над областью сброса. По умолчанию добавляется класс
ng-file-over
. Другой класс можно задать в параметре атрибутаng-file-over="className"
.
Сервис
- $fileUploader - управляет очередью и загрузкой файлов
Загрузчик API:
Свойства
- scope
{Object}
- ссылка на scope для обновления html. Если параметр опущен, используется$rootScope
- url
{String}
- путь на сервере, по которому будут загружаться файлы - alias
{String}
- псевдоним файла - queue
{Array}
- очередь загрузки - progress
{Number}
- прогресс загрузки очереди. Только для чтения. - headers
{Object}
- заголовки, которые будут переданы вместе с файлами. Только для HTML5 браузеров. - formData
{Array}
- данные, отправляемые вместе с файлами - filters
{Array}
- фильтры, применяемые к [файлу|элементу] перед добавлением его в очередь. Если фильтр возвращаетtrue
, [файл|элемент] будет добавлен в очередь - autoUpload
{Boolean}
- загружать автоматически после добавления элемента в очередь - method
{String}
: - метод запроса. По умолчаниюPOST
. Только для HTML5 браузеров. - removeAfterUpload
{Boolean}
- удалить файлы после загрузки - isHTML5
{Boolean}
-true
, если это html5-загрузчик. Только для чтения. - isUploading
{Boolean}
- загрузчик в процессе загрузки. Только для чтения. - queueLimit
{Number}
- максимальное количество файлов - withCredentials
{Boolean}
: включить CORS. Только для HTML5 браузеров.
Методы
- bind
function(event, handler) {
- регистрирует обработчик события - trigger
function(event[, params ]) {
- выполняет все обработчики, связанные с данным событием - addToQueue
function(items, options) {
- где items [FileList|File|Input], options [Object] - removeFromQueue
function({Item|Index}) {
- где value элемент очереди или его индекс [Item|Index] - clearQueue
function() {
- удаляет все элементы из очереди - getIndexOfItem
function(item) {return {Number};}
- где item элемент очереди - getReadyItems
function() {return {Array};}
- Возвращает элементы готовые к загрузке - getNotUploadedItems
function() { return {Array};}
- возвращает массив не загруженных элементов - uploadItem
function({Item|Index}) {
- где value элемент очереди или его индекс [Item|Index] - uploadAll
function() {
- загружает все незагруженные элементы - cancelItem
function({Item|Index}) {
- где value элемент очереди или его индекс [Item|Index] - cancelAll
function() {
- отменяет все текущие загрузки
Элемент очереди API:
Свойства
- url
{String}
- путь на сервере, по которому будет загружен файл - alias
{String}
- псевдоним файла - headers
{Object}
- заголовки, которые будут переданы вместе с файлом. Только для HTML5 браузеров. - formData
{Array}
- данные, отправляемые вместе с файлом - method
{String}
: - метод запроса. По умолчаниюPOST
. Только для HTML5 браузеров. - withCredentials
{Boolean}
: включить CORS. Только для HTML5 браузеров. - removeAfterUpload
{Boolean}
- удалить файл после загрузки - index
{Number}
- индекс / порядковый номер загрузки. Только для чтения. - progress
{Number}
- прогресс загрузки файла. Только для чтения. - isReady
{Boolean}
- файл готов к загрузке. Только для чтения. - isUploading
{Boolean}
- файл в процессе загрузки. Только для чтения. - isUploaded
{Boolean}
- файл загружен. Только для чтения. - isSuccess
{Boolean}
- файл успешно загружен. Только для чтения. - isCancel
{Boolean}
- загрузка файла была отменена. Только для чтения. - isError
{Boolean}
- при загрузке файла произошла ошибка. Только для чтения. - uploader
{Object}
- ссылка на загрузчик. Только для чтения.
Методы
- remove
function() {
- удаляет элемент - upload
function() {
- загружает элемент - cancel
function() {
- отменяет загрузку элемента
Фильтры
Добавить фильтр
var uploader = $fileUploader.create({
scope: $scope,
filters: [
function(item) { // first user filter
return true;
}
]
});
// second user filter
uploader.filters.push(function(item) {
return true;
});
Предустановленные фильтры
События
Список событий
- afteraddingfile
function(event, item) {
- после добавления файла в очередь - whenaddingfilefailed
function(event, item) {
: когда добавление файла в очередь не удалось - afteraddingall
function(event, items) {
- после добавления всех файлов в очередь - beforeupload
function(event, item) {
- перед загрузкой файла - progress
function(event, item, progress) {
- прогресс загрузки файла - success
function(event, xhr, item, response) {
- файл успешно загружен - cancel
function(event, xhr, item) {
- отменяет загрузку файла - error
function(event, xhr, item[, response ]) {
- ошибка при загрузке - complete
function(event, xhr, item, response) {
- файл загружен - progressall
function(event, progress) {
- прогресс загрузки очереди - completeall
function(event, items) {
- "очередь загружена", если была инициирована загрузка всей очереди; иначе "файл загружен", если была инициирована загрузка файла
Подписка на событие
var uploader = $fileUploader.create({scope: $scope});
uploader.bind('progress', function(event, item, progress) {
console.log('Progress: ' + progress);
});
FAQ / Вопросы и ответы
-
Как добавить ранее загруженные файлы в очередь?
// Add a item to the queue var item = { file: { name: 'Your file name', size: 1e6 }, progress: 100, isUploaded: true, isSuccess: true }; item.remove = function() { uploader.removeFromQueue(this); }; uploader.queue.push(item); uploader.progress = 100;