Documentation officielle de SWFUpload (v2.5.0)

Pour le guide d'utilisation de SWFUpload, veuillez consulter :https://www.example.com/w3cnote/swfupload-guide.html

Table des matières

SWFUpload

SWFUploadÀ l'origineVinterwebb.seUn outil d'envoi de fichiers côté client développé. Il combine JavaScript et Flash pour offrir une capacité (et une bonne expérience utilisateur) dans le navigateur qui est supérieure à la balise de téléversement traditionnelle <input type="file" />.

Principales fonctionnalités de SWFUpload :

Plusieurs fichiers peuvent être sélectionnés dans la boîte de dialogue de navigation des fichiers.
Téléversements de type AJAX sans rafraîchissement de la page.
Divers événements pendant le processus de téléversement.
Peut redimensionner les images côté client.
L'espace de noms de classe qu'il utilise est compatible avec diverses bibliothèques JS (c'est-à-dire jQuery, Prototype, etc.).
Prend en charge Flash 9 et Flash 10 (la prise en charge de Flash 8 a été abandonnée après la version 2.2.0).

La philosophie de conception de SWFUpload diffère des autres outils de téléversement basés sur Flash. SWFUpload donne aux développeurs autant de contrôle que possible sur l'interface utilisateur. Les développeurs peuvent utiliser XHTML, CSS et JavaScript pour mieux l'adapter au style de leur site web. Il fournit un ensemble d'événements JS simples pour mettre à jour l'état du téléversement, et les développeurs peuvent utiliser ces événements pour afficher la progression du téléversement de fichiers sur la page web.

Malheureusement, Flash Player 10 nous oblige à utiliser un bouton (après un clic) pour déclencher la boîte de dialogue de sélection de fichiers, mais SWFUpload permet aux développeurs d'utiliser JS pour modifier le texte et l'apparence du bouton.

SWFUpload v2

SWFUpload v2 inclut de nombreuses nouvelles fonctionnalités, une stabilité améliorée, corrige certains bugs dans Flash Player et fournit quelques plug-ins utiles. Les nouvelles fonctionnalités comprennent :

Peut tirer parti des fonctionnalités de sécurité de Flash Player 10.
Peut envoyer des données supplémentaires en POST lors des téléversements.
Envoie des données POST pour chaque téléversement de fichier.
Ensemble complet d'événements.
Tous les réglages et paramètres peuvent être configurés de manière flexible.
Peut récupérer les données renvoyées par le serveur.
Peut mettre en pause les fichiers en cours de téléversement au lieu de les annuler.
Peut modifier arbitrairement l'ordre de téléversement.
Peut proposer une boîte de dialogue de sélection d'un seul fichier ou de plusieurs fichiers.
Peut limiter la longueur de la file d'attente de téléversement, la taille des fichiers et le nombre de fichiers téléversés.
Peut mieux gérer les fichiers de 0 octet.
Chaque fichier dispose d'un événement de confirmation de téléversement.

Aperçu

Téléversement HTML

Le champ de téléversement HTML standard ne fournit qu'un bouton et une zone de texte permettant aux utilisateurs de sélectionner un seul fichier. Il est ensuite soumis via un formulaire. Il faut attendre que le téléversement du fichier entier soit terminé avant de pouvoir confirmer et vérifier sa taille et son extension, et il y a peu de retour d'information pendant le processus de téléversement. Cela occasionne quelques désagréments.

Mais le téléversement HTML traditionnel est très simple, en une seule étape, et pris en charge par tous les navigateurs.

SWFUpload

SWFUpload utilise une animation Flash pour sélectionner et téléverser des fichiers. L'animation dispose d'un bouton personnalisable pour activer la boîte de dialogue de sélection de fichiers. La boîte de dialogue de sélection de fichiers permet aux utilisateurs de sélectionner un seul fichier ou plusieurs fichiers. Les types de fichiers pouvant être sélectionnés peuvent également être restreints ; les développeurs peuvent limiter les utilisateurs à la sélection de fichiers appropriés spécifiés, par ex., *.jgp;*.gif.

Une fois les fichiers sélectionnés et le bouton OK cliqué, chaque fichier est validé et placé dans la file d'attente. Lorsque Flash téléverse les fichiers, des événements JavaScript prédéfinis sont déclenchés pour mettre à jour l'affichage de l'interface utilisateur sur la page, et fournissent également l'état du téléversement et les informations d'erreur en temps réel.

Les téléversements de fichiers sont indépendants de la page et du formulaire. Chaque fichier est téléversé séparément vers la page de traitement, ce qui rend la gestion des fichiers simple et facile pour le serveur. Le service de téléversement fourni par Flash signifie que la page entière n'a pas besoin d'être soumise ou actualisée. Cela ressemble un peu à une application AJAX. Les données de formulaire sur la page sont traitées séparément du téléversement de fichiers contrôlé par Flash.

Pour commencer

SWFUpload n'est pas un contrôle de téléversement par glisser-déposer. Par conséquent, certaines connaissances en DOM et JS sont requises. Plusieurs démos montreront les capacités de SWFUpload et comment les utiliser pour accomplir des tâches.

SWFUpload se compose de 4 parties :

Initialisation et paramètres (JavaScript)
Bibliothèque JavaScript : SWFUpload.js
Contrôle Flash : swfupload.swf et swfupload_fp9.swf
Mécanisme de gestion des événements (JavaScript)

De nombreux problèmes liés à l'utilisation de SWFUpload proviennent de la configuration. Une gestion incorrecte des événements, des bogues de Flash/navigateur ou une configuration du serveur.

Initialisation et paramètres

SWFUpload doit être initialisé sur la page. Cela se fait généralement dans l'événement window.onload de JS. Le constructeur SWFUpload doit recevoir un objet de type Object (JS). Les données de cet objet sont transmises directement au constructeur.

La référence de l'objet SWFUpload initialisé doit être bien conservée (yukon : c'est-à-dire, la stocker dans une variable, comme 'swfu' dans l'exemple), car cette référence est également nécessaire lors du démarrage des téléversements de fichiers et du contrôle d'autres fonctionnalités.

Exemple :Lors de l'initialisation de SWFUpload, passez directement un objet anonyme pour configurer les paramètres.

var swfu;
	
window.onload = function () {
	swfu = new SWFUpload({
		upload_url : "http://www.swfupload.org/upload.php",			//处理上传文件的地址
		flash_url : "http://www.swfupload.org/swfupload.swf",		//核心功能swf的地址
		flash9_url : "http://www.swfupload.org/swfupload_fp9.swf",
		file_size_limit : "20 MB"									//文件大小限制                               
	});
};

Exemple :Vous pouvez également utiliser une variable objet (settings_object) pour transmettre les paramètres de configuration lors de l'initialisation de 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",
		flash9_url : "http://www.swfupload.org/swfupload_fp9.swf",
		file_size_limit : "20 MB"
	};
	
	swfu = new SWFUpload(settings_object);
};

Bibliothèque JavaScript

Pour utiliser SWFUpload, le fichier de bibliothèque JS (swfupload.js) doit être inclus dans la page qui l'utilise.

Une fois l'objet SWFUpload créé, il est possible d'accéder à de nombreuses fonctions. Les développeurs peuvent l'utiliser pour contrôler SWFUpload.

Exemple :Comment inclure la bibliothèque swfupload.js


<script type="text/javascript" src="../www.swfupload.org/swfupload.js"></script>

Exemple :Initialiser SWFUpload à la demande.

var swfu = new SWFUpload({
	upload_url : "http://www.swfupload.org/upload.php",
	flash_url : "http://www.swfupload.org/swfupload.swf",
	flash9_url : "http://www.swfupload.org/swfupload_fp9.swf",
	button_placeholder_id : "spanSWFUploadButton"               
    //yukon：这里有个新参数，将会使用js在id为"spanSWFUploadButton"的标签容器如span，div中创建一个"选择"按钮
});

[Nouveau contenu] Contrôle Flash

La bibliothèque JavaScript SWFUpload peut charger dynamiquement le contrôle Flash (swfupload.swf ou swfupload_fp9.swf).

L'adresse du fichier du contrôle Flash doit être définie dans l'objet de paramètres SWFUpload lors de l'initialisation.

Le contrôle Flash est en fait un petit film Flash qui peut contrôler la sélection, la validation et le téléversement des fichiers.

Ce qu'il présente à l'utilisateur sur la page est un bouton avec une interface utilisateur personnalisable, et il peut détecter la version de Flash Player (9, 10) et charger automatiquement le contrôle Flash adapté à la version du lecteur de l'utilisateur.

Utilisez flash_url et flash9_url pour définir les chemins de swfupload.swf ou swfupload_fp9.swf. (yukon : Les exemples précédents l'ont déjà mentionné.)

Gestionnaires d'événements

Les développeurs doivent créer un ensemble de fonctions JavaScript pour gérer les événements SWFUpload. Ces fonctions sont déclenchées lorsque divers événements importants se produisent.

En gérant les événements SWFUpload, les développeurs peuvent fournir des retours sur la progression du téléversement, les messages d'erreur et l'achèvement du téléversement. Remarque : Les développeurs ne doivent pas redéfinir les fonctions stockées dans SWFUpload.prototype.

Exemple :Gestion des événements et initialisation de SWFUpload.

// uploadStart event handler function. The value of the "upload_start_handler" property in the settings object should be the name of this function.
    var myCustomUploadStartEventHandler = 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 event handler function. The value of the "upload_success_handler" property in the settings object should be the name of this function. 
    var myCustomUploadSuccessEventHandler = function (file, server_data, receivedResponse) {
	alert("The file " + file.name + " has been delivered to the server. The server responded with " + server_data);
};

// Create the SWFUpload Object
var swfu = new SWFUpload({
	upload_url : "http://www.swfupload.org/upload.php",
	flash_url : "http://www.swfupload.org/swfupload.swf",
	flash9_url : "http://www.swfupload.org/swfupload_fp9.swf",
	file_size_limit : "200 MB",
	
	upload_start_handler : myCustomUploadStartEventHandler,
	upload_success_handler : myCustomUploadSuccessEventHandler

Objet JavaScript SWFUpload

Constructeur

SWFUpload(objet de paramètres) //SWFUpload(objet de paramètres)

Retourne :Une instance de SWFUpload

var swfupload_instance = new SWFUpload(settings_object);

Variables globales et constantes

SWFUpload définit certaines variables globales et constantes utiles pour les applications SWFUpload avancées et la gestion des erreurs. Elles sont toutes en lecture seule.

[Nouveau contenu] SWFUpload.instances

SWFUpload.instances est un objet tableau qui stocke des références à toutes les instances SWFUpload d'une page. Flash Player s'appuie sur ce tableau d'objets pour appeler les fonctions de gestion des événements correctes. L'index du tableau d'objets SWFUpload.instances (SWFUpload.instances[index]) est la propriété movieName.

SWFUpload.movieCount

SWFUpload.movieCount est une variable globale qui enregistre le nombre d'instances de l'objet SWFUpload créées sur la page et garantit que chaque animation Flash reçoit un movieName unique.

[Nouveau contenu] SWFUpload.QUEUE_ERROR

SWFUpload.QUEUE_ERROR est un objet JavaScript simple contenant des constantes pour les codes d'erreur de file d'attente. Il est utilisé pour déterminer quel code d'erreur est envoyé lorsqu'une erreur de file d'attente de fichier (fileQueueError) se produit.

SWFUpload.QUEUE_ERROR = {
	QUEUE_LIMIT_EXCEEDED		: -100,
	FILE_EXCEEDS_SIZE_LIMIT 	: -110,
	ZERO_BYTE_FILE			: -120,
	INVALID_FILETYPE		: -130
};

QUEUE_LIMIT_EXCEEDED - Indique que l'utilisateur a mis en file d'attente trop de fichiers, dépassant la longueur maximale de la file d'attente. Toutefois, une fois que les fichiers de la file d'attente sont téléversés ou supprimés, l'utilisateur peut encore ajouter des fichiers à la file d'attente de téléversement.
FILE_EXCEEDS_SIZE_LIMIT - Indique que le fichier dépasse la limite de taille de fichier définie (file_size_limit).
ZERO_BYTE_FILE - Indique que le fichier sélectionné fait 0 bytes. Flash Player ne peut pas gérer les fichiers vides. Le téléversement d'icônes de raccourci Windows peut également déclencher cette erreur.
INVALID_FILETYPE - Indique que l'extension du fichier sélectionné ne correspond pas aux types autorisés. Cette erreur peut être déclenchée lorsque l'utilisateur saisit manuellement un nom de fichier avec une extension incorrecte au lieu de sélectionner un fichier en cliquant avec la souris.

[Nouveau contenu] SWFUpload.UPLOAD_ERROR

SWFUpload.UPLOAD_ERROR est également un simple objet JavaScript contenant les constantes de code d'erreur de téléversement. Il est utilisé pour déterminer quel code d'erreur est envoyé lorsqu'un événement d'erreur de téléversement (uploadError) se produit.

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
};

HTTP_ERROR - Une tentative de téléversement vers le serveur a été effectuée, mais le serveur n'a pas renvoyé de code de statut 200 (200 indique aucune erreur).
MISSING_UPLOAD_URL - L'URL de téléversement (upload_url) n'est pas définie.
IO_ERROR - Une erreur s'est produite lors de la lecture et de l'envoi du fichier. Cela se produit généralement lorsque le serveur ferme la connexion de manière inattendue.
SECURITY_ERROR - Une erreur de sécurité ; le téléversement a violé des contraintes de sécurité. Cela est rare.
UPLOAD_LIMIT_EXCEEDED - L'utilisateur a tenté de téléverser plus de fichiers que la limite prédéfinie.
UPLOAD_FAILED - Une erreur s'est produite lors de la tentative d'initialisation du téléversement. Cela est rare.
SPECIFIED_FILE_ID_NOT_FOUND - Un fichier a commencé à être téléversé, mais le fichier est introuvable. (yukon: après que le fichier a été sélectionné et ajouté à la file d'attente, l'utilisateur l'a renommé ou supprimé du disque, etc.)
FILE_VALIDATION_FAILED - Une erreur a été renvoyée au démarrage du téléversement.
FILE_CANCELLED - Le téléversement a été annulé (la fonction cancelUpload a été appelée).
UPLOAD_STOPPED - Le téléversement a été mis en pause (la fonction stopUpload a été appelée).
RESIZE_ERROR - Une erreur s'est produite lors du redimensionnement de l'image.

[Nouveau contenu] SWFUpload.FILE_STATUS

SWFUpload.FILE_STATUS est un objet JavaScript contenant des constantes de code d'état de fichier. Il est utilisé pour vérifier la propriété d'état de fichier de l'objet File.

SWFUpload.FILE_STATUS = {
	QUEUED		 : -1,
	IN_PROGRESS	 : -2,
	ERROR		 : -3,
	SUCCESS	 	 : -4,
	CANCELLED	 : -5
};

QUEUED - Indique que le fichier est en attente dans la file d'attente de téléversement.
IN_PROGRESS - Indique que le fichier est en cours de téléversement.
ERROR - Indique que le fichier a provoqué une erreur de file d'attente ou de téléversement.
COMPLETE - Indique que le fichier a été transmis avec succès au serveur.
CANCELLED - Indique que le téléversement de ce fichier a été annulé (la fonction cancelUpload a été appelée).

[Nouveau contenu] SWFUpload.UPLOAD_TYPE [Objectif : Détermine le type de téléversement]

SWFUpload.UPLOAD_TYPE est un objet JavaScript contenant des constantes de type de téléversement. Il est utilisé pour vérifier la propriété de type de téléversement de l'objet File.

NORMAL - Un téléversement SWFUpload normal.
RESIZED - Un téléversement d'image redimensionnée, avec les données envoyées via HTTP POST.

[Nouveau contenu] SWFUpload.BUTTON_ACTION [Objectif : Détermine l'action à effectuer lorsque le bouton est cliqué]

SWFUpload.BUTTON_ACTION est un objet JavaScript contenant les constantes de code d'action de bouton. Il est utilisé pour définir la valeur de button_action, configurant ainsi le bouton interactif dans les réponses du film Flash aux diverses actions de la souris.

SWFUpload.BUTTON_ACTION = { SELECT_FILE : -100, SELECT_FILES : -110, START_UPLOAD : -120 }

SELECT_FILE - Lorsque l'on clique sur le bouton, une boîte de dialogue de sélection d'un seul fichier s'ouvre. L'événement de clic de souris (défini en JavaScript) n'est pas déclenché.
SELECT_FILES - Lorsque l'on clique sur le bouton, une boîte de dialogue de sélection de plusieurs fichiers s'ouvre. L'événement de clic de souris (défini en JavaScript) n'est pas déclenché.
START_UPLOAD - Lorsque l'on clique sur le bouton, le premier fichier de la file d'attente de téléversement sera téléversé. L'événement de clic de souris (défini en JavaScript) n'est pas déclenché.
NONE - Dans ce cas, l'événement de clic de souris (défini en JavaScript) est déclenché.
JAVASCRIPT - Identique à NONE. Cette valeur est obsolète.

[Nouveau contenu] SWFUpload.CURSOR [Objectif : Modifie le style du curseur de la souris]

SWFUpload.CURSOR est un objet JavaScript contenant les constantes de curseur de bouton. Il est utilisé pour définir la valeur de button_cursor, modifiant ainsi le style du curseur de la souris lorsque le pointeur survole le bouton.

SWFUpload.CURSOR = {
	ARROW : -1,
	HAND : -2
}

ARROW - Le curseur se présente sous la forme d'un pointeur en flèche.
HAND - Le curseur se présente sous la forme d'une main.

[Nouveau contenu] SWFUpload.WINDOW_MODE [Objectif : Le mode d'affichage du film]

SWFUpload.WINDOW_MODE est un objet tableau JS qui contient les constantes du paramètre wmode du film du bouton. Il est utilisé pour indiquer au navigateur comment restituer le film Flash.

Certains paramètres WINDOW_MODE/WMODE peuvent provoquer des problèmes de navigateur ; voir ci-dessous pour plus de détails.Problèmes connus.

SWFUpload.WINDOW_MODE = {
	WINDOW : "window",
	TRANSPARENT : "transparent",
	OPAQUE : "opaque"
};

WINDOW est le mode par défaut. Le film Flash est dessiné sur la couche supérieure de la page.
OPAQUE permet à d'autres éléments de la page de recouvrir ce film de bouton.
TRANSPARENT. L'arrière-plan du bouton est transparent, ce qui permet aux éléments HTML de s'afficher en dessous.

[Nouveau] SWFUpload.RESIZE_ENCODING [Objectif : indique le format d'encodage de l'image]

SWFUpload.RESIZE_ENCODING est un objet tableau JS qui contient des constantes de type d'encodage de redimensionnement. Il est utilisé pour indiquer le format d'encodage de l'image redimensionnée.

JPEG - format d'encodage JPEG
PNG - format d'encodage PNG

[Nouveau] SWFUpload.onload [Objectif : définit la fonction d'opération après le chargement de la page]

onload est une fonction qui peut être exécutée via la méthode addDOMLoadEvent de swfobject. Vous pouvez utiliser cette méthode pour exécuter votre script après le chargement de la page. Toutefois, vous devez vous assurer de ne pas utiliser d'autres méthodes similaires (comme la méthode "Ready" de jQuery ou dom:loaded de Prototype).

SWFUpload.onload = function () {
	new SWFUpload(settingsObject);	
}

L'exemple ci-dessus initialisera SWFUpload lors du premier événement de chargement du navigateur. La plupart des événements DOM ready s'exécutent immédiatement après l'événement window.onload.

Propriétés

Veuillez suivre les descriptions de la liste de propriétés ci-dessous lorsque vous utilisez ces propriétés. Si une propriété en lecture seule ou en écriture seule est utilisée de manière incorrecte, cela provoquera des erreurs SWFUpload.

[Nouveau contenu] customSettings (lecture/écriture) [Objectif : paramètres personnalisés du développeur]

La propriété customSettings est un objet JS vide. Elle est utilisée pour stocker des données liées à une instance de SWFUpload. Son contenu peut être initialisé à l'aide de la propriété custom_settings dans l'objet settings.

Exemple :

// 初始化 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";	// 添加一个新的自定义设置

// 用一个全新的对象来重写自定义设置
swfu.customSettings = {
	custom_setting_A : "custom_setting_value_A",
	custom_setting_B : "custom_setting_value_B"
};

Les valeurs stockées dans l'objet customSettings sont facilement accessibles par les gestionnaires d'événements : (yukon : cette propriété utilise les fonctionnalités dynamiques de JS pour offrir aux développeurs une grande liberté)


function uploadSuccess(file, serverData, receivedResponse) {
	if (this.customSettings.custom_setting_A === true) {
		alert("Checked the custom setting!");
	}
}

movieName (lecture seule) [Objectif : stocke un identifiant unique pour une instance de SWFUpload]

Contient le nom d'identifiant unique d'une instance de SWFUpload. Cette valeur peut être transmise à Flash pour faciliter l'interaction AS-JS. Elle est utilisée pour indexer l'instance dans le tableau SWFUpload.instances. Vous ne devez pas et ne pouvez pas la modifier.

Méthodes

Les méthodes suivantes sont utilisées pour faire fonctionner SWFUpload. Certaines méthodes peuvent être liées à des événements de clic d'éléments DOM, et d'autres sont utilisées en interne par SWFUpload lors du traitement des événements.

object addSetting(setting_name, value, default_value)

Obsolète La fonction addSetting définit une valeur de paramètre. Si la valeur est undefined, alors la default_value est utilisée. La fonction est utilisée par SWFUpload

addSetting renvoie la valeur qui a été stockée dans le paramètre.

object getSetting(setting_name)

Obsolète La fonction getSetting récupère la valeur d'un paramètre. Si le paramètre est introuvable, une chaîne vide est renvoyée.

object retrieveSetting(setting_value, default_value)

Supprimé dans la v2.1.0. La fonction retrieveSetting est similaire à la fonction addSetting, sauf qu'elle ne modifie pas l'objet interne settings. retrieveSetting renvoie setting_value sauf si celui-ci est undefined, auquel cas elle renvoie default_value.bool destroy() [Objectif : détruire une instance SWFUpload]

Ceci est une fonction utilitaire.

Ajouté dans la v2.1.0

Supprime un élément DOM SWF et détruit les références internes de SWFUpload. Elle est utilisée pour supprimer complètement une instance SWFUpload de la page, ce qui évite les problèmes de fuite de mémoire dans IE.

Renvoie true si la suppression a réussi ; renvoie false si une erreur se produit, laissant l'instance SWFUpload dans un état incohérent.

void displayDebugInfo() [Objectif : afficher les informations de débogage]

Lors des événements de débogage, displayDebugInfo() affiche les paramètres SWFUpload. Si le paramètre debug est défini sur true lors de l'initialisation, cette fonction est appelée automatiquement.

Non recommandé. Incompatible avec Flash Player 10.

void selectFile()

Non recommandé. Incompatible avec Flash Player 10.

selectFile amène le contrôle Flash à afficher une fenêtre de dialogue de sélection de fichier. Un seul fichier peut être sélectionné dans la fenêtre de dialogue.

Appeler selectFile démarre la chaîne d'événements de fichier.

void selectFiles()

Non recommandé. Incompatible avec Flash Player 10.

selectFiles amène le contrôle Flash à afficher une fenêtre de dialogue de sélection de fichiers. Plusieurs fichiers peuvent être sélectionnés dans la fenêtre de dialogue.

L'appel de selectFiles démarre la chaîne d'événements de fichier.

void startUpload(file_id) [Objectif : démarrer l'envoi de fichiers]

startUpload accepte le paramètre file_id pour envoyer un fichier. Si aucune valeur file_id ne lui est transmise, le premier fichier de la file d'attente d'envoi sera envoyé par défaut.

L'appel de startUpload déclenche la chaîne d'événements d'envoi.

[Nouveau] void startResizedUpload(file_id, width, height, encoding, quality, allowEnlarging) [Objectif : envoyer avec redimensionnement d'image]

startResizedUpload accepte le paramètre file_id pour envoyer un fichier. SWFUpload tente d'ajuster la largeur/hauteur du fichier et d'autres paramètres (si le format d'image est pris en charge par Flash). Si le format d'image n'est pas pris en charge, une uploadError est déclenchée.

Les paramètres width et height sont utilisés pour définir la largeur et la hauteur maximales de l'image. Toutefois, le rapport d'aspect est conservé lors du redimensionnement.

La valeur encoding doit être une constante dans SWFUpload.RESIZE_ENCODING.

La valeur quality ne peut être utilisée que pour ajuster la qualité des images au format JPEG. Elle accepte une plage de 0-100. Si elle est en dehors de cette plage, elle est forcée à 0 ou 100.

Le paramètre allowEnlarging définit si SWFUpload autorise l'agrandissement de l'image d'origine (la valeur par défaut est true) lorsque la largeur/hauteur de l'image d'origine est inférieure à la largeur et à la hauteur spécifiées. S'il est défini sur false, l'image sera quand même encodée, mais elle ne sera pas agrandie.

L'appel de la méthode startResizedUpload déclenche la chaîne d'événements de téléversement normale. Toutefois, Flash Player ne fournit pas périodiquement d'événements uploadProgress. SWFUpload envoie uniquement des événements uploadProgress simulés à 0% et 100%.

L'image redimensionnée est soumise via POST (plutôt qu'en tant que FILE) parce que Flash Player 10 a introduit des fonctionnalités de sécurité.La page de traitement PHP pour le téléversement avec redimensionnement d'image diffère de la page de traitement PHP normale de téléversement :

$resizedImageData = $_POST["Filedata"];	// 服务器端以$_POST方式接收数据而不是 $_FILE
$fileHandle = fopen("image.jpg", "w");            //以file系列操作函数来存储图片
fwrite($fileHandle, $resizedImageData);
fclose($fileHandle);

void cancelUpload(file_id, trigger_error_event) [Objectif : supprime un téléversement]

cancelUpload accepte le paramètre file_id pour supprimer un téléversement de fichier. Ce fichier sera retiré de la file d'attente de téléversement.

Si aucun file_id n'est fourni, le premier fichier de la file d'attente de téléversement sera annulé par défaut.

Si le paramètre facultatif trigger_error_event est défini sur false, l'événement uploadError ne sera pas déclenché.

void stopUpload() [Objectif : arrête le téléversement de fichier]

stopUpload arrête le fichier en cours de téléversement et le restaure dans la file d'attente de téléversement. (yukon : contrairement au retrait, il annule le téléversement de ce fichier mais ne le retire pas de la file d'attente de téléversement)

Lorsque stopUpload est appelé, si un fichier est en cours de téléversement, l'événement uploadError sera déclenché ; si aucun fichier n'est en cours de téléversement à ce moment-là, aucune action ne se produira et aucun événement ne sera déclenché.

[Nouveau] bool requeueUpload(file_id ou index) [Objectif : remettre en file d'attente]

requeueUpload ajoute à nouveau un fichier précédemment mis en file d'attente dans la file d'attente de téléversement.

Renvoie false si le fichier est introuvable, ou s'il est actuellement en cours de téléversement.

Remarque : un fichier remis dans la file d'attente ne sera pas vérifié à nouveau par rapport à la taille du fichier, à la taille de la file d'attente, au nombre total de téléversements ou à d'autres restrictions ; il est seulement ajouté à la file d'attente, si la référence du fichier existe encore.

object getStats() [Objectif : renvoie l'objet stats actuel]

Renvoie l'objet stats.

void setStats(stats_object) [Objectif : définit ou modifie l'objet stats]

Définit ou modifie l'objet Stats. Si vous souhaitez modifier le nombre de téléversements réussis ou le nombre d'échecs de téléversement après la fin du téléversement, vous pouvez utiliser cette méthode.

object getFile(file_id|index) [Objectif : obtient un objet fichier spécifique depuis la file d'attente]

getFile renvoie l'objet fichier dans la file d'attente en acceptant un id de fichier (l'id d'un objet fichier) ou un index de fichier (l'attribut index d'un objet fichier).

Lorsqu'un file_id est passé à getFile, seuls les fichiers présents dans la file d'attente peuvent être récupérés ; si aucun fichier n'est trouvé, null est renvoyé.

Lorsqu'un index est passé à getFile, tous les fichiers qui ont tenté d'être mis en file d'attente (y compris les fichiers qui ont provoqué des erreurs lors de la mise en file d'attente) peuvent être récupérés. Si l'index est hors plage, null est renvoyé.

[Nouveau] object getQueueFile(file_id|index) [Objectif : renvoie un objet fichier spécifique dans la file d'attente de téléversement]

getQueueFile est utilisé pour renvoyer un seul objet fichier depuis la file d'attente de téléversement. Plus précisément, il renvoie l'objet fichier dans la file d'attente en acceptant un id de fichier (l'id d'un objet fichier) ou un index de fichier (l'attribut index d'un objet fichier). L'index commence à 0.

Lorsqu'un file_id est passé à getQueueFile, seuls les fichiers de la file d'attente des téléversements en attente peuvent être récupérés ; si aucun fichier n'est trouvé, null est renvoyé.

Lorsqu'un index est passé à getQueueFile, seuls les fichiers de la file d'attente des téléversements en attente peuvent être récupérés. Par exemple : getQueueFile(0) renvoie un objet fichier en tête de la file d'attente des téléversements en attente. Si la fonction startUpload est appelée, il sera téléversé après la fin du téléversement en cours.

(yukon : La différence entre les deux méthodes ci-dessus peut être : getFile récupère les fichiers de la file d'attente des fichiers, y compris les files d'attente des fichiers téléversés, des fichiers en erreur et des téléversements en attente. getQueueFile récupère uniquement les fichiers de la file d'attente des téléversements en attente.)

void addPostParam(name, value) [Objectif : Ajoute une paire clé/valeur]

addPostParam ajoute une paire clé/valeur qui est envoyée via POST lors du téléversement de chaque fichier.

Cela correspond à la même paire clé/valeur dans le paramètre post_params. Si la valeur existe déjà dans post_params, elle sera effectivement écrasée.

void removePostParam(name) [Objectif : Supprime une paire clé/valeur]

removePostParam supprime une paire clé/valeur qui était auparavant envoyée via POST lors du téléversement de chaque fichier.

Cela correspond à la même paire clé/valeur dans le paramètre post_params. Si la valeur existe déjà dans post_params, elle sera effectivement supprimée.

bool addFileParam(file_idspan>, name, value)

Ajoute une paire clé/valeur POST à un objet fichier spécifique avec le file_id spécifié. Si l'attribut name ajouté existe déjà, la valeur d'origine sera écrasée.

Si vous devez ajouter des valeurs POST à tous les objets fichier, vous pouvez utiliser la propriété post_params dans les paramètres.

bool removeFileParam(file_id, name)

Supprime la paire de valeurs POST ajoutée par addFileParam.

Renvoie false si cette propriété n'existe pas dans les paramètres POST.

void setUploadURL(url)

Modifie dynamiquement la propriété upload_url dans les paramètres.

void setPostParams(param_object)

Modifie dynamiquement post_params, toutes les propriétés précédentes sont écrasées. param_object doit être un objet JavaScript de base, et toutes les propriétés et valeurs doivent être de type chaîne.

void setFileTypes(types, description)

Modifie dynamiquement file_types et file_types_description dans les paramètres ; les deux paramètres sont requis.

void setFileSizeLimit(file_size_limit)

Modifie dynamiquement file_size_limit dans les paramètres ; cette modification est valable pour le filtrage ultérieur de la taille des fichiers. Le paramètre file_size_limit accepte une unité ; les unités valides sont B, KB, MB, GB, et l'unité par défaut est KB.

Par exemple : 2147483648 B, 2097152, 2097152KB, 2048 MB, 2 GB

void setFileUploadLimit(file_upload_limit)

Modifie dynamiquement file_upload_limit dans les paramètres ; la valeur spéciale 0 signifie illimité.

Remarque :Ceci limite le nombre total de fichiers téléversés avec succès sous le contrôle d'une instance SWFUpload.

void setFileQueueLimit(file_queue_limit)

Modifie dynamiquement file_queue_limit dans les paramètres ; la valeur spéciale 0 signifie illimité.

Remarque :Ceci limite le nombre total de fichiers autorisés à être mis en file d'attente dans la file d'attente de téléversement (les fichiers qui passent la détection de file d'attente sont ajoutés à la file d'attente de téléversement pour attendre le téléversement).

void setFilePostName(file_post_name)

Modifie dynamiquement file_post_name dans les paramètres. Notez que FlashPlayer ignore ce paramètre dans l'environnement Linux.

void setUseQueryString(use_query_string)

Modifie dynamiquement use_query_string dans les paramètres. Lorsqu'il est défini sur true, SWFUpload envoie les données via GET ; s'il est false, il envoie les données via POST.

void setDebugEnabled(debug_enabled)

Active/désactive dynamiquement la sortie de débogage ; le paramètre debug_enabled est une valeur booléenne.

void setButtonImageURL(url)

Modifie dynamiquement l'image du bouton. Le paramètre url est une image relative au fichier swf ou une adresse absolue (par exemple : un chemin relatif commençant par / ou un chemin absolu : http://www.swfupload.org/buttonImage.png). Tous les types d'images pris en charge par FLASH peuvent être utilisés (gif, jpg, png).

L'image du bouton doit être traitée selon certaines règles (CSS Sprite). L'image du bouton doit inclure les 4 états du bouton, de haut en bas : normal, survol, enfoncé/clic, désactivé. (Reportez-vous à l'image dans la démo officielle.)

void setButtonDimensions(width, height)

Modifie dynamiquement la taille du film SWF pour l'adapter à la taille de l'image du bouton. La valeur doit être un nombre pur et ne peut pas inclure d'unités de longueur. La hauteur doit être égale à 1/4 de la hauteur totale de l'image du bouton pour garantir un affichage correct.

void setButtonText(text)

Définit dynamiquement le texte affiché dans le bouton Flash, avec prise en charge du HTML. Le style du texte HTML peut être défini via des sélecteurs CSS avec la méthode setButtonTextStyle. Si le texte est trop grand, la partie qui dépasse sera masquée. Pour plus de détails sur la prise en charge HTML du texte Flash, voir...Documentation Flash d'Adobe。

void setButtonTextStyle(css_style_text)

Conjointement avec la méthode setButtonText, des styles CSS peuvent être utilisés pour définir dynamiquement le style du texte dans le bouton Flash. Pour plus de détails sur la prise en charge CSS du texte Flash, voir...Documentation Flash d'Adobe

void setButtonTextPadding(left, top)

Définit les marges intérieures gauche et droite du texte du bouton Flash. La valeur peut être négative.

void setButtonDisabled(isDisabled)

Lorsqu'il est défini sur 'true', le bouton Flash est désactivé, et toutes les actions et opérations du bouton seront ignorées.

void setButtonAction(buttonAction)

Définit l'action à exécuter après le clic de la souris. L'énumération de constantes BUTTON_ACTION stocke les valeurs disponibles pour cette méthode.

void setButtonCursor(buttonCursor)

Définit le style du pointeur de la souris lorsqu'il pointe sur le bouton. L'énumération de constantes CURSOR stocke les valeurs disponibles pour cette méthode.

[Nouveau contenu] Événements

SWFUpload déclenche une série d'événements pendant l'exécution. Les développeurs peuvent utiliser ces événements de gestion des rappels pour contrôler l'interface utilisateur, contrôler les opérations ou signaler des erreurs.

Tous les événements sont appelés dans le contexte de l'instance SWFUpload, donc l'utilisation de this dans ces événements de rappel permet d'accéder directement à l'objet d'instance qui a déclenché l'événement.

Tous les événements doivent être prédéfinis dans le paramètre setting lors de l'initialisation de l'instance.

[Nouveau :]

Lors du téléversement d'un fichier, les événements sont appelés dans l'ordre suivant (chaîne d'événements de téléversement) :

Début du téléversement avec fonction supplémentaire de redimensionnement d'image uploadResizeStart
Début du téléversement normal uploadStart
Téléversement en cours uploadProgress (appelé de manière répétée pendant le processus de téléversement du fichier)
Erreur de téléversement uploadError (appelé lorsque certaines erreurs se produisent ; le téléversement sera annulé ou arrêté)
Téléversement réussi uploadSuccess (le fichier a été téléversé avec succès et le serveur a reçu des données utilisables)
Téléversement terminé uploadComplete (téléversement terminé, SWFUpload est prêt à commencer le suivant)

flashReady()

Cette fonction d'événement est un événement interne et ne peut donc pas être redéfinie. Lorsque le contrôle Flash chargé termine toutes les opérations d'initialisation, cet événement est déclenché pour informer SWFUpload qu'il peut accepter diverses commandes.

Remarque :Correspond à l'événement personnalisé swfupload_loaded_handler dans les paramètres.

[Nouveau] swfUploadPreload()

L'événement swfUploadPreload est déclenché après que SWFUpload a confirmé les fonctionnalités disponibles, mais avant que le film Flash ne soit entièrement chargé. Si le gestionnaire de cet événement renvoie false, swfupload arrêtera le chargement. Il est généralement utilisé pour gérer les cas où le navigateur ne prend pas en charge un paramètre de fonctionnalité important.

Ce gestionnaire d'événement peut être défini dans la propriété swfupload_preload_handler de l'objet de paramètres.

[Nouveau] swfUploadLoadFailed()

Lorsque la page ne peut pas charger normalement le film Flash. Généralement parce que Flash Player n'est pas installé ou que sa version est inférieure à 9.0.28.

Ce gestionnaire d'événement peut être défini dans la propriété swfupload_load_failed_handler de l'objet settings.

[Nouveau] swfUploadLoaded()

L'événement swfUploadLoaded est déclenché après le chargement et la préparation de Flash. Il est configurable. L'événement swfUploadLoaded vous signale que Flash est chargé et que toutes les méthodes peuvent être exécutées en toute sécurité.

Ce gestionnaire d'événement peut être défini dans la propriété swfupload_loaded_handler de l'objet settings.

[Nouveau] mouseClick()

L'événement mouseClick est déclenché uniquement lorsque le bouton est cliqué (et que la valeur du paramètre button_action est SWFUpload.BUTTON_ACTION.NONE, ou que le bouton Flash est défini sur désactivé). Si la valeur des paramètres button_action est autre, ou si le bouton Flash est activé, cet événement ne sera pas déclenché.

Cette fonction de gestionnaire d'événement peut être définie dans la propriété mouse_click_handler de l'objet settings.

[Nouveau] mouseOver()

L'événement mouseOver sera déclenché lorsque la souris se déplace sur n'importe quelle partie du film Flash.

Cette fonction de gestionnaire d'événement peut être définie dans la propriété mouse_over_handler de l'objet settings.

[Nouveau] mouseOut()

L'événement mouseOut est déclenché lorsque la souris quitte le film Flash.

Cette fonction de gestionnaire d'événement peut être définie dans la propriété mouse_out_handler de l'objet settings.

fileDialogStart()

Cet événement est déclenché après l'appel de selectFile ou selectFiles, et avant l'affichage de la boîte de dialogue de sélection de fichier. Une seule boîte de dialogue de fichier peut exister à la fois.Cependant, cette fonction de gestionnaire d'événement ne sera pas exécutée tant que la boîte de dialogue de sélection de fichier n'est pas fermée.

Cette fonction de gestionnaire d'événement peut être définie dans la propriété file_dialog_start_handler de l'objet settings.

fileQueued(objet fichier)

Lorsque les fichiers sont sélectionnés et que la boîte de dialogue de sélection de fichier se ferme et disparaît, si les fichiers sélectionnés sont ajoutés avec succès à la file d'attente de téléversement, cet événement sera déclenché une fois pour chaque fichier ajouté avec succès (N fichiers ajoutés avec succès à la file d'attente, l'événement se déclenche N fois).

Correspond à l'événement personnalisé file_queued_handler dans settings.

[Nouveau contenu]fileQueueError(objet fichier, code d'erreur, message)

Lorsque la boîte de dialogue de sélection de fichier se ferme, si les fichiers sélectionnés ne parviennent pas à être ajoutés à la file d'attente de téléversement, cet événement sera déclenché une fois pour chaque fichier ayant rencontré une erreur (cet événement et l'événement fileQueued sont déclenchés de manière exclusive ; il n'y a que deux possibilités lors de l'ajout d'un fichier à la file d'attente : succès ou échec).

Raisons possibles des erreurs de file d'attente de fichiers : 1. Dépasse la limite de taille de téléversement, 2. Le fichier est de zéro octet, 3. Dépasse la limite de quantité de la file d'attente de fichiers, 4. Type de fichier non valide en dehors des types autorisés.

(yukon : après les tests, le contenu du message est le suivant :

1. Dépasse la limite de taille de téléversement : message=La taille du fichier dépasse la limite autorisée.

2. Le fichier fait zéro octet : message=Le fichier fait zéro octet et ne peut pas être téléversé.

3. Dépasse la limite de quantité de la file d'attente de fichiers : message=int (fait référence à la limite de taille de la file d'attente que vous avez définie).

4. Type de fichier non valide en dehors des types autorisés : message=Le fichier n'est pas d'un type autorisé.

Si vous souhaitez modifier ces messages, veuillez les modifier dans swfupload.as du paquet open source, puis recompiler dans swfupload.swf.

)

La cause spécifique de l'erreur peut être obtenue à partir du paramètre de code d'erreur. Le type de code d'erreur est visible dans les définitions de SWFUpload.QUEUE_ERROR.

Rappel :Correspond à l'événement personnalisé file_queue_error_handler dans les paramètres.

Remarque :Si le nombre de fichiers sélectionnés à mettre en file d'attente dépasse la limite de quantité définie dans les paramètres, aucun fichier ne sera mis en file d'attente et cet événement n'est déclenché qu'une seule fois. Si la limite de quantité n'est pas dépassée, chaque fichier sera vérifié pour son type et sa taille ; pour les fichiers qui échouent à la vérification, cet événement est déclenché, tandis que les fichiers qui passent sont mis en file d'attente avec succès.

fileDialogComplete(nombre de fichiers sélectionnés, nombre de fichiers mis en file d'attente, nombre total de fichiers dans la file d'attente)

Lorsque la boîte de dialogue de sélection de fichier se ferme et que tous les fichiers sélectionnés ont été traités (qu'ils aient été ajoutés avec succès à la file d'attente de téléversement ou qu'ils aient échoué), cet événement est déclenché. nombre de fichiers sélectionnés est le nombre de fichiers sélectionnés, nombre de fichiers mis en file d'attente est le nombre de fichiers de cette sélection qui ont été ajoutés avec succès à la file d'attente.

Rappel :Correspond à l'événement personnalisé file_dialog_complete_handler dans les paramètres.

Remarque :Si vous souhaitez que les fichiers soient téléversés automatiquement après leur sélection, appeler this.startUpload() dans cet événement est un bon choix. Si une détermination plus stricte est nécessaire, vous pouvez vérifier le nombre de fichiers en file d'attente avant de lancer l'envoi ; s'il est supérieur à 0, vous pouvez démarrer le téléversement.

[Nouveau] uploadResizeStart(objet fichier, largeur, hauteur, encodage, qualité)

La fonction de gestionnaire d'événement uploadResizeStart est appelée lorsqu'une image commence à être redimensionnée. Aucun événement de progression ni méthode de gestion n'est fourni pendant le processus de redimensionnement. Cependant, le ré-encodage de l'image peut prendre un certain temps. Si une erreur se produit pendant cette période, l'événement uploadError sera déclenché.

Lorsque le redimensionnement est terminé, SWFUpload continue à déclencher l'événement uploadStart et entame la même chaîne d'événements qu'un téléversement normal.

uploadStart(objet fichier)

L'événement uploadStart est déclenché avant que le fichier ne commence à être téléversé vers le serveur. Cette fonction de gestionnaire d'événement peut effectuer une validation finale avant le téléversement et d'autres opérations dont vous avez besoin, telles que l'ajout, la modification ou la suppression de données POST.

Après avoir terminé les opérations finales, si la fonction renvoie false, le téléversement ne sera pas lancé ; si elle renvoie true ou ne renvoie rien, le téléversement démarrera officiellement.

Rappel :Correspond à l'événement personnalisé upload_start_handler dans les paramètres.

uploadProgress(objet fichier, octets terminés, octets totaux)

L'événement uploadProgress est déclenché périodiquement par le contrôle Flash.Il fournit trois paramètres pour accéder respectivement à l'objet fichier téléversé, aux octets téléversés et aux octets totaux. Par conséquent, vous pouvez mettre à jour périodiquement les éléments d'interface utilisateur de la page dans cet événement afin d'afficher l'avancement du téléversement en temps opportun.

Remarque :Sous Linux, Flash Player ne déclenche cet événement qu'une seule fois après que le fichier entier a été téléversé. Officiellement, il s'agit d'un bug du Flash Player sous Linux, et la bibliothèque SWFUpload actuelle ne peut pas le résoudre.。

Rappel :Correspond à l'événement personnalisé upload_progress_handler dans les paramètres.

uploadError(objet fichier, code d'erreur, message)

Chaque fois que l'envoi est interrompu ou ne se termine pas correctement, alorsuploadErrorl'événement sera déclenché. Le paramètre code d'erreur indique le type d'erreur actuel. Pour des types d'erreur plus spécifiques, voirSWFUpload.UPLOAD_ERRORles définitions dans. Le paramètre Message représente la description de l'erreur. Le paramètre File représente l'objet fichier dont l'envoi a échoué.

Par exemple, si nous demandons une page de traitement de fichier inexistante sur le serveur, alors le code d'erreur sera -200 et le message sera 404. L'arrêt, la fermeture, le retour false de uploadStart, les erreurs HTTP, les erreurs IO, le dépassement de la limite du nombre d'envois de fichiers, etc., déclencheront tous cet événement. L'erreur d'envoi ne se déclenchera pas pour les fichiers qui sont annulés mais qui attendent encore dans la file d'attente.(J'ai encore des doutes sur cette déclaration officielle. Après qu'un fichier est annulé, comment peut-il rester dans la file d'attente d'envoi ?)

Rappel :Correspond à l'événement personnalisé upload_error_handler dans les paramètres.

Remarque :À ce stade, le cycle d'envoi de fichier n'est pas encore terminé, donc vous ne pouvez pas commencer à envoyer le fichier suivant ici.

[Nouveau contenu] uploadSuccess(objet fichier, données serveur, réponse reçue)

Lorsque le traitement de l'envoi du fichier est terminé (ici « terminé » signifie seulement que les informations Files ont été envoyées au gestionnaire cible ; il ne se préoccupe que de l'envoi, pas de savoir s'il a été reçu avec succès), et que le serveur renvoie un statut HTTP 200, leuploadSuccessl'événement est déclenché.données serveurDésignent certaines données envoyées par le serveur (par exemple, ce que vous renvoyez avec echo), tandis queréponse reçueest le code de statut HTTP envoyé par le serveur lui-même.

En raison de certains bugs de Flash Player, le code d'état HTTP peut ne pas être obtenu, ce qui empêche le déclenchement de l'événement uploadSuccess. Pour cette raison, la version 2.50 a ajouté une nouvelle propriété assume_success_timeout dans l'objet settings pour définir si le temps maximal d'attente du code d'état HTTP a été dépassé ; si dépassé, uploadSuccess est déclenché. Dans ce cas,（réponse reçue）le paramètre sera invalide.

Le http_success dans l'objet settings permet de définir que l'événement uploadSuccess soit également déclenché lorsque le code d'état HTTP est une valeur différente de 200. Dans ce cas, aucune donnée serveur n'est disponible depuis le Flash Player.

Dans

Rappel :Correspond à l'événement personnalisé upload_success_handler dans settings.

Remarque :

les données serveur sont les données renvoyées par le gestionnaire côté serveur.
À ce stade, le cycle de téléversement du fichier n'est pas encore terminé, vous ne pouvez donc pas commencer à téléverser le fichier suivant ici.
Sur la plateforme Windows, le gestionnaire côté serveur doit renvoyer une valeur non vide après avoir traité le stockage du fichier ; sinon, cet événement ne sera pas déclenché, et l'événement uploadComplete suivant ne pourra pas être exécuté.

uploadComplete(objet fichier)

Lorsqu'un fichier de la file d'attente de téléversement termine un cycle de téléversement, qu'il réussisse (uoloadSuccess déclenché) ou échoue (uploadError déclenché), l'événement uploadComplete sera déclenché. Cela marque également la fin du téléversement d'un fichier, et le fichier suivant peut être téléversé.

Si vous souhaitez que le fichier suivant soit téléversé automatiquement, appeler this.startUpload() à ce stade pour commencer le téléversement du fichier suivant est un bon choix. Cependant, utilisez-le avec prudence. Voir les notes.

Rappel :Correspond à l'événement personnalisé upload_complete_handler dans settings.

Remarque :Lors du téléversement de plusieurs fichiers, si vous utilisez cancelUpload en cours de route pour annuler le fichier en cours de téléversement, ou si vous utilisez stopUpload pour arrêter le fichier en cours de téléversement, vous devez être très prudent lorsque vous utilisez this.startUpload() dans uploadComplete, car dans les cas ci-dessus uploadError et uploadComplete s'exécuteront séquentiellement. Par conséquent, bien que le téléversement du fichier actuel soit arrêté, le fichier suivant sera téléversé immédiatement. Cela peut vous sembler étrange, mais en réalité le programme n'est pas erroné. Si vous souhaitez interrompre le téléversement automatique de toute la file d'attente, vous devrez effectuer un traitement supplémentaire dans le programme.

debug(message)

Si le paramètre debug est défini sur true, une textArea sera automatiquement ajoutée en bas de la page. Si cet événement debug n'a pas été remplacé, la bibliothèque SWFUpload et Flash appelleront tous deux cet événement pour ajouter des informations de débogage à la zone de sortie en bas de la page à des fins de débogage.

Rappel :Correspond à l'événement personnalisé debug_handler dans les paramètres.

Objets utilitaires SWFUpload Objets utilitaires

Objet Settings Objet Settings

Il s'agit d'une variable de type JavaScript Object qui fournit la configuration pour l'initialisation d'une instance SWFUpload.Chaque propriété de configuration qu'il contient ne peut apparaître qu'une seule fois.De nombreuses propriétés sont facultatives. Si une propriété facultative n'est pas configurée, la valeur par défaut appropriée spécifiée dans la bibliothèque SWFUpload sera utilisée. Pour plus de détails, consultez la présentation détaillée des paramètres.

Par exemple :(Toutes les propriétés pouvant être configurées dans settings)

Exemple :

{
	upload_url : "http://www.swfupload.org/upload.php",
	flash_url : "http://www.swfupload.org/swfupload.swf",
	flash9_url : "http://www.swfupload.org/swfupload_fp9.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],
	assume_success_timeout : 0,
	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,
	preserve_relative_urls : false,
	
	button_placeholder_id : "element_id",
	button_image_url : "http://www.swfupload.org/button_sprite.png",
	button_width : 61,
	button_height : 22,
	button_text : "<b>Click</b> <span class="redText">here</span>",
	button_text_style : ".redText { color: #FF0000; }",
	button_text_left_padding : 3,
	button_text_top_padding : 2,
	button_action : SWFUpload.BUTTON_ACTION.SELECT_FILES,
	button_disabled : false,
	button_cursor : SWFUpload.CURSOR.HAND,
	button_window_mode : SWFUpload.WINDOW_MODE.TRANSPARENT,
	
	swfupload_loaded_handler : swfupload_loaded_function,
	mouse_click_handler : mouse_click_function,
	mouse_over_handler : mouse_over_function,
	mouse_out_handler : mouse_out_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",
	}
}

Description détaillée des paramètres de configuration Description des paramètres

Nouveau upload_url

Valeur par défaut :Chaîne vide

Le paramètre upload_url accepte une URL complète absolue ou relative par rapport au fichier SWF. Il est recommandé d'utiliser un chemin absolu complet pour éviter les erreurs de chemin de requête causées par les navigateurs et FlashPlayer modifiant le paramètre de chemin de base. (yukon : En fait, c'est relatif. Si votre swfupload et la page de traitement des fichiers de téléversement PHP sont toujours placés dans le même dossier de site web, je recommanderais d'utiliser un chemin relatif)

Si la propriété preserve_relative_urls de l'objet settings est false, SWFUpload convertira les chemins relatifs en chemins absolus pour éviter que les URL soient analysées sous diverses formes différentes par Flash Player sur différents systèmes. Si vous désactivez cette conversion de SWFUpload, vous devez utiliser un chemin relatif pour définir l'emplacement de swfupload.swf.

Remarque :Le modèle de domaine de sécurité de FlashPlayer doit être pris en compte ici.

file_post_name

Valeur par défaut :Filedata

Le paramètre file_post_name permet de définir la valeur du nom du fichier téléversé dans les informations POST (similaire à la définition de l'attribut name de <input type="file" name="Filedata"/> dans un formulaire traditionnel).

Remarque : (En attente dans la version 2.5)Le réglage de ce paramètre est non valide sous Linux ; le nom reçu est toujours Filedata. Par conséquent, pour garantir une compatibilité maximale, il est recommandé d'utiliser la valeur par défaut de ce paramètre.

Nouveau post_params

Valeur par défaut :Objet vide

post_params définit un ensemble de paires clé/valeur qui sont envoyées au serveur lors du téléversement de chaque fichier. Cette propriété peut être assignée avec un objet tableau JavaScript. Les paires clé/valeur doivent être des chaînes de caractères ou des nombres simples. (Peut être vérifié avec la fonction typeof() de JavaScript)

Remarque : Flash Player 8 ne prend pas en charge l'envoi de données POST. SWFUpload enverra automatiquement post_params sous la forme d'une chaîne de requête.

use_query_string

Valeur par défaut :false

Cette propriété peut être définie sur true ou false, et détermine si post_params sont envoyés via GET. Si elle est définie sur false, ils sont envoyés via POST. Introduite dans la v2.1.0.

Nouveau preserve_relative_urls

Valeur par défaut :false

preserve_relative_urls accepte une variable booléenne. Il indique si SWFUpload convertit les URL relatives en URL absolues. S'il est défini sur true, elles ne seront pas converties. La valeur par défaut est false, c'est-à-dire une conversion automatique.

requeue_on_error

Valeur par défaut :false

Cette propriété peut être définie sur true ou false. Si elle est définie sur true, lorsqu'un uploadError se produit sur un objet fichier (sauf pour les erreurs fileQueue et les erreurs FILE_CANCELLED), l'objet fichier sera réinséré au début de la file d'attente d'envoi au lieu d'être écarté. Si nécessaire, le fichier remis en file d'attente peut être envoyé à nouveau. Si vous souhaitez retirer l'objet fichier de la file d'attente d'envoi, vous devez utiliser la méthode cancelUpload.

Tous les événements associés à un échec d'envoi seront également déclenchés un par un. Par conséquent, la remise en file d'attente d'un fichier dont l'envoi a échoué peut entrer en conflit avec le Queue Plugin (ou du code personnalisé qui envoie automatiquement toute la file d'attente de fichiers). Si le code appelle la méthode startUpload pour envoyer automatiquement le fichier suivant et qu'aucune mesure n'est prise pour retirer le fichier dont l'envoi a échoué de la file d'attente d'envoi, alors le fichier dont l'envoi a échoué et qui a été remis en file d'attente recommencera à être envoyé, échouera à nouveau, sera remis en file d'attente, sera envoyé à nouveau... ce qui crée une boucle sans fin.

Ce paramètre a été introduit dans la v2.1.0.

http_success

Valeur par défaut :[]

Ce tableau permet de personnaliser les valeurs de statut HTTP qui déclenchent l'événement success. Le statut 200 déclenche toujours le succès, et seul le statut 200 fournit serverData.

Lorsqu'on accepte une valeur de statut HTTP autre que 200, le serveur n'a pas besoin de renvoyer de contenu.

Nouveau assume_success_timeout

Valeur par défaut : 0

assume_success_timeout définit le nombre de secondes pendant lesquelles SWFUpload attendra pour détecter une réponse du serveur ; en cas d'expiration, il forcera le déclenchement de l'événement de réussite de l'envoi (uploadSuccess). Cette propriété est destinée à contourner correctement un bug de Flash Player, en évitant de longues attentes de réponses du serveur, et à résoudre également le bug où Flash Player sur Mac OS ne peut pas faire en sorte que le serveur renvoie du contenu.

Flash ignorera la réponse du serveur 30 secondes après le déclenchement du dernier événement uploadProgress et forcera l'événement de réussite de l'envoi.

Si assume_success_timeout est défini sur 0, cette fonctionnalité sera désactivée. SWFUpload attendra longtemps que Flash Player déclenche l'événement uploadSuccess.

file_types

Valeur par défaut :*.*

Définit les règles de filtrage des types de fichiers pour la boîte de dialogue de sélection de fichiers. Cette propriété accepte des extensions de type de fichier séparées par des points-virgules, par exemple "*.jpg;*.gif", ce qui permet uniquement aux utilisateurs de voir et de sélectionner des fichiers jpg et gif dans la boîte de dialogue de sélection de fichiers. Par défaut, tous les types de fichiers sont acceptés.

Rappel :Ce paramètre n'est qu'un filtre pour le navigateur client et n'impose aucune restriction sur le filtrage des types de fichiers dans le traitement de fichiers côté serveur. Si vous avez besoin d'un filtrage strict des fichiers, le côté serveur doit également disposer d'une détection par programme.

file_types_description

Valeur par défaut :Tous les fichiers

Définit la description du fichier affichée à l'utilisateur dans la boîte de dialogue de sélection de fichiers.

file_size_limit

Valeur par défaut :0

Définit les règles de filtrage de taille de fichier pour la boîte de dialogue de sélection de fichiers. Cette propriété accepte une valeur numérique avec une unité ; les unités disponibles sont B, KB, MB, GB. Si l'unité est omise, KB est utilisé par défaut. La valeur spéciale 0 signifie aucune limite de taille de fichier.

Rappel :Ce paramètre n'a d'effet que pour le navigateur client et n'impose aucune restriction sur le traitement des fichiers côté serveur. Si vous avez besoin d'un filtrage strict des fichiers, le côté serveur doit également prévoir une gestion dans le programme.

file_upload_limit

Valeur par défaut :0

Définit le nombre maximum de fichiers qu'une instance SWFUpload est autorisée à téléverser, et constitue également la limite supérieure de la propriété file_queue_limit dans l'objet settings. Une fois que l'utilisateur a téléversé avec succès des fichiers ou ajouté des fichiers à la file d'attente jusqu'à atteindre le nombre maximum, aucun autre fichier ne peut être ajouté. La valeur spéciale 0 signifie qu'il n'y a aucune limite sur le nombre de téléversements. Seuls les fichiers téléversés avec succès (le téléversement a déclenché l'événement uploadSuccess) comptent dans la limite de téléversement. La méthode setStats peut être utilisée pour modifier le nombre de fichiers téléversés avec succès.

Remarque :Cette valeur ne peut pas être utilisée d'une page à l'autre ; elle est également réinitialisée lorsque la page est actualisée. Les limites strictes du nombre de téléversements de fichiers doivent être détectées et gérées par le serveur.

file_queue_limit

Valeur par défaut :0

Définit la limite maximale des fichiers en attente dans la file d'attente de téléversement de fichiers. Lorsqu'un fichier est téléversé avec succès, rencontre une erreur ou est retiré de la file d'attente de téléversement, si le nombre de fichiers dans la file d'attente n'a pas encore atteint la limite, de nouveaux fichiers peuvent être ajoutés à la file d'attente pour remplacer la position de ce fichier. Si le nombre maximum de fichiers autorisés à être téléversés (file_upload_limit) ou le nombre restant de téléversements autorisés est inférieur à la limite de file d'attente de fichiers (file_queue_limit), la valeur la plus petite sera utilisée.

flash_url

Valeur par défaut :Chaîne vide

Définit une URL complète absolue ou relative par rapport à cette page de téléversement. Une fois l'instance SWFUpload instanciée, ce paramètre ne peut pas être modifié.

Remarque :Des tests ont montré que la méthode setUploadURL peut être utilisée pour modifier ce paramètre.

[Nouveau] flash9_url

(Ajouté dans la v2.5.0)Contrôle Flash (SWF) prenant en charge Flash Player 9. URL absolue ou relative.

flash_width

(Supprimé dans la v2.1.0) Définit la largeur de l'élément HTML qui contient le flash. Certains navigateurs ne fonctionnent pas correctement si ce paramètre est inférieur à 1 px. Ce paramètre est facultatif et a une valeur par défaut de 1px.

flash_height

(Supprimé dans la v2.1.0) Définit la hauteur de l'élément HTML qui contient le flash. Certains navigateurs ne fonctionnent pas correctement si ce paramètre est inférieur à 1 px. Ce paramètre est optionnel et a une valeur par défaut de 1px.

flash_color

(Supprimé dans la v2.2.0) Ce paramètre définit la couleur d'arrière-plan de l'élément HTML qui contient le flash. La valeur par défaut est '#FFFFFF'.

Remarque : Ce paramètre peut ne pas être efficace pour le "skinning" d'un élément flash de 1px dans tous les navigateurs.

prevent_swf_caching

Valeur par défaut :true

(Ajouté dans la v2.2.0)Cette valeur booléenne définit s'il faut ajouter une valeur aléatoire à l'URL Flash pour empêcher le navigateur de mettre en cache le film SWF. Cela permet de résoudre un bug qui apparaît dans certains navigateurs basés sur le moteur IE.

Remarque :SWFUpload ajoute directement un paramètre aléatoire appelé swfuploadrnd après flash_url. Si l'URL flash_url fournie contient déjà des paramètres GET, deux points d'interrogation apparaîtront comme concaténateurs, provoquant une erreur.

debug

Valeur par défaut :false

Cette valeur est de type booléen, elle définit si l'événement de débogage est déclenché.

Remarque :Le code de SWFUpload compare cette variable à la chaîne "true" en utilisant une égalité stricte, il ne considère donc que true comme activant le mode de débogage. Si elle est définie à 1, bien que JS le considère comme activé, et qu'une console de débogage sera générée après l'initialisation, Flash ne produira pas d'informations de débogage lors des opérations suivantes. (Comme j'ai l'habitude d'utiliser 1 et 0 pour les variables booléennes, j'ai déjà été perplexe quant à la raison pour laquelle les informations de débogage de Flash ne pouvaient pas être produites.)

button_placeholder_id

Valeur par défaut :null

(Ajouté dans la v2.2.0)Ce paramètre requis spécifie l'ID de l'élément DOM de la page que swfupload.swf remplacera. Lorsque l'élément DOM correspondant est remplacé par l'élément SWF, un sélecteur de style nommé "swfupload" sera ajouté au conteneur SWF pour la personnalisation CSS.

button_image_url

Valeur par défaut :Chaîne vide

(Ajouté dans la v2.2.0)Le plus grand changement de la V2.2.0 est l'introduction d'un bouton dans le SWF. À l'aide de ce paramètre, vous pouvez définir une image (ou un SWF) relative au fichier swf ou une adresse absolue comme interface utilisateur du bouton. Tous les types d'images pris en charge par Flash peuvent être utilisés (gif, jpg, png ou un SWF).

L'image du bouton doit être traitée selon certaines règles (Sprite CSS). L'image du bouton doit inclure les 4 états du bouton, de haut en bas : normal, survol, enfoncé/clic, désactivé. (Voir l'image dans la démo officielle.)

button_width

Valeur par défaut :1

(Ajouté dans la v2.2.0)Définit l'attribut width du SWF.

button_height

Valeur par défaut :1

(Ajouté dans la v2.2.0)Définit l'attribut height du SWF (1/4 de la hauteur de l'image du bouton)

button_text

Valeur par défaut :Chaîne vide

(Ajouté dans la v2.2.0)Cette propriété définit le texte affiché dans le bouton Flash, avec prise en charge du HTML. Le style du texte HTML peut être défini via des sélecteurs CSS avec le paramètre button_text_style. Pour plus de détails sur la prise en charge du HTML par le texte Flash, voirDocumentation Flash d'Adobe。

button_text_style

Valeur par défaut :"color: #000000; font-size: 16pt;"

(Ajouté dans la v2.2.0)Ce paramètre fonctionne avec le paramètre button_text pour définir le style du texte dans le bouton Flash via des styles CSS. Pour plus de détails sur la prise en charge du texte Flash pour CSS, voirla documentation Flash d'Adobe

button_text_top_padding

Valeur par défaut :0

(Ajouté dans la v2.2.0)Définit la distance du texte sur le bouton Flash depuis le haut. Des valeurs négatives peuvent être utilisées.

button_text_left_padding

Valeur par défaut :0

(Ajouté dans la v2.2.0)Définit la distance du texte sur le bouton Flash depuis la gauche. Des valeurs négatives peuvent être utilisées.

button_action

Valeur par défaut :SWFUpload.BUTTON_ACTION.SELECT_FILES (envoi de plusieurs fichiers)

(Ajouté dans la v2.2.0)Définit l'action après avoir cliqué sur le bouton Flash. La valeur par défaut est SWFUpload.BUTTON_ACTION.SELECT_FILES ; cliquer sur le bouton ouvre la boîte de dialogue d'envoi de plusieurs fichiers. Si la valeur est SWFUpload.BUTTON_ACTION.SELECT_FILE, il s'agit d'un envoi de fichier unique. Si la valeur est SWFUpload.BUTTON_ACTION.START_UPLOAD, il démarre l'envoi du fichier.

button_disabled

Valeur par défaut :false

(Ajouté dans la v2.2.0)Cette valeur booléenne définit si le bouton Flash est dans un état désactivé. Lorsqu'il est désactivé, un clic n'effectue aucune opération.

button_cursor

Valeur par défaut :SWFUpload.CURSOR.ARROW (curseur en forme de flèche)

(Ajouté dans la v2.2.0)Ce paramètre définit l'état du curseur lorsque la souris survole le bouton Flash. La valeur par défaut est SWFUpload.CURSOR.ARROW ; s'il est défini sur SWFUpload.CURSOR.HAND, il s'agit d'un curseur en forme de main.

button_window_mode

Valeur par défaut :SWFUpload.WINDOW_MODE.WINDOW

(Ajouté dans la v2.2.0)Ce paramètre définit le mode spécifique dans lequel le navigateur affiche le film SWF.

custom_settings

Valeur par défaut :Objet vide

Cette propriété accepte des données de type Object et peut être utilisée pour stocker en toute sécurité des informations personnalisées associées à l'instance SWFUpload, telles que des propriétés et des méthodes, sans se soucier des conflits avec les méthodes et propriétés internes de SWFUpload, ni de la compatibilité avec les mises à niveau de version.

Après la configuration, il est possible d'y accéder via la propriété customSettings de l'instance.

var swfu = new SWFUpload({
	custom_settings : {
		"My Setting" : "This is my setting",
		myothersetting : "This is my other setting",
		integer_setting : 100,
		a_dom_setting : document.getElementById("some_element_id")
	}
});

var my_setting = swfu.customSettings["My Setting"]);
swfu.customSettings["My Setting"] = "This is my new setting";
swfu.customSetting.myothersetting = "another new value";
swfu.customSetting.integer_setting += 25;
swfu.customSetting["a_dom_setting"].style.visibility = "hidden";

Gestionnaires d'événements

Valeur par défaut :null

Les paramètres restants définissent une série de fonctions de rappel de gestion d'événements. Pendant le fonctionnement de SWFUpload,les événements correspondantsseront déclenchés. Si vous devez effectuer des opérations personnalisées dans ces rappels, vous devez définir les fonctions JavaScript correspondantes dans les paramètres.

[Nouveau] Prise en charge des objets

La propriété support de l'instance SWFUpload (son type est un objet) permet de confirmer si certaines fonctionnalités de SWFUpload sont prises en charge par la version de Flash Player utilisée par le navigateur.

{
	load : bool,			// 标示SWFupload是否能在当前版本的 Flash Player中载入
	imageResize : bool,		// 标示当前时候安装了Flash Player 10或更新版本的Flash Player，并且SWFUpload 是否支持客户端调节上传图片的大小。
}

Objet File

L'objet File contient un ensemble de propriétés de fichier disponibles. De nombreux événements de traitement passent un paramètre File Object pour accéder aux propriétés pertinentes du fichier.

{
	id : string,			// SWFUpload控制的文件的id,通过指定该id可启动此文件的上传、退出上传等
	index : number,			// 文件在选定文件队列（包括出错、退出、排队的文件）中的索引，getFile可使用此索引
	name : string,			// 文件名，不包括文件的路径。
	size : number,			// 文件字节数
	type : string,			// 客户端操作系统设置的文件类型
	creationdate : Date,		// 文件的创建时间
	modificationdate : Date,	// 文件的最后修改时间
	filestatus : number		// 文件的当前状态，对应的状态代码可查看SWFUpload.FILE_STATUS
	
}

Objet Stats

Cet objet fournit des informations sur l'état de la file d'attente de téléversement. Vous pouvez obtenir cet objet en accédant à la méthode getStats de l'instance.

Cet objet inclut les propriétés suivantes :

{
	in_progress : number		// 值为1或0，1表示当前有文件正在上传，0表示当前没有文件正在上传
	files_queued : number		// 当前上传队列中存在的文件数量
	successful_uploads : number	// 已经上传成功（uploadSuccess触发）的文件数量
	upload_errors : number		// 已经上传失败的文件数量 (不包括退出上传的文件)
	upload_cancelled : number	// 退出上传的文件数量
	queue_errors : number		// 入队失败（fileQueueError触发）的文件数量

Les valeurs de toutes ces propriétés peuvent être modifiées à l'aide de la méthode setStats, saufin_progressetfiles_queued。

Plug-ins SWFUpload

Plusieurs plug-ins ont été introduits après SWFUpload v2.0. Ils aident SWFUpload à implémenter certaines fonctions.

La documentation de la plupart des plug-ins se trouve dans le dossier des plug-ins js.

SWFObject

Le plug-in SWFObject utilisela bibliothèque SWFObjectpour insérer le composant Flash SWFUpload dans la page.

Ce plug-in fournit également une fonctionnalité de détection de fin de chargement de la structure du document (chargement Document Ready). (yukon : cette fonctionnalité pourrait être semblable à $(document).ready() de jQuery) et une détection de version de Flash. L'utilisation détaillée est documentée dans le dossier de ce plug-in. Il vaut mieux ne pas mélanger la détection de fin de chargement Document Ready de SWFObject avec des fonctions similaires d'autres bibliothèques. N'en utilisez qu'une seule.

Flash Player 10 : Comme Flash Player 10 exige un bouton pour déclencher les opérations associées du film, si ce bouton (son id peut être indiqué par la propriété button_placeholder_id de l'objet settings) est défini sur hidden ou display:none par CSS ou similaire, SWFUpload ne parviendra pas à se charger.

Cookies

Pour corriger le bug des cookies Flash, le plug-in Cookies récupérera automatiquement les cookies de votre navigateur et les enverra avec le téléversement. Les cookies seront envoyés avec l'URL de téléversement sous la forme POST ou GET.

Ce plug-in envoie des paires clé/valeur de cookie via POST ou GET. Côté serveur, elles ne seront pas analysées comme des cookies. Certains frameworks qui détectent automatiquement les cookies pour confirmer la session et l'authentification peuvent ne pas pouvoir obtenir les valeurs transmises par ce plug-in.

Gestion de la file d'attente

Le plugin Queue Handling fournit des fonctionnalités de traitement de file d'attente. Par exemple, l'envoi de toute la file d'attente, l'annulation de toute la file d'attente, et le démarrage automatique de l'envoi après la mise en file d'attente.

Vitesse

Le plugin speed étend plusieurs propriétés de l'objet 'file' pour décrire l'état actuel de l'envoi. Ce plugin inclut des valeurs telles que la vitesse actuelle, la vitesse moyenne, le temps écoulé et le temps restant.

Problèmes connus

Les bogues dans Flash Player et de nombreux navigateurs ont tourmenté SWFUpload. Mais nous avons travaillé dur.

Annulation sous Linux

Avec Flash 9 Player et les versions antérieures, effectuer une opération d'annulation d'envoi sous Linux peut provoquer le plantage du navigateur. Cependant, les versions plus récentes de Flash Player ont amélioré ce problème.

Progression de l'envoi sous Linux

Flash Player sous Linux n'émet un événement de progression de l'envoi (uploadProgress) qu'après la fin de l'envoi, plutôt que continuellement pendant l'envoi comme il le fait sous Windows.

C'est parce que certaines distributions Linux verrouillent tout le navigateur pendant l'envoi.

Progression de l'envoi sous OS X

Nous avons reçu quelques rapports selon lesquels Flash Player sous MAC OS ne déclenche pas l'événement uploadProgress. Les circonstances exactes sont encore inconnues, mais veuillez garder à l'esprit le problème potentiel.

Type MIME

Quel que soit le type MIME réel du fichier, Flash Player utilise le format mimeapplication/octet-streampour téléverser tous les fichiers.

Nombre maximal de fichiers sélectionnés

Flash Player lui-même ne limite pas le nombre maximal de fichiers pouvant être sélectionnés pour le téléversement, mais il limite la longueur totale maximale des noms de fichiers. Cette chaîne est composée ainsi : « nom de fichier » espace « nom de fichier » ... Le nombre de fichiers pouvant être téléversés dépend de la limite du système d'exploitation quant à la longueur totale des noms de fichiers. Si l'utilisateur sélectionne trop de fichiers, un message d'avertissement de Flash Player s'affichera dans la boîte de dialogue de sélection de fichiers (yukon : j'ai déjà téléversé 173 fichiers d'un coup sur XP sans avertissement...).

Proxys

Flash Player peut ne pas fonctionner correctement avec les proxys. Il rencontre quelques problèmes lors de la gestion de l'authentification par proxy, ce qui peut provoquer certains conflits.

Certains logiciels antivirus utilisent un proxy client local pour recevoir les fichiers téléversés et les analyser (il semble intercepter le fichier téléversé, l'écrire dans un serveur proxy, et ce n'est qu'après la fin de l'analyse qu'il l'envoie réellement au serveur cible). Cela amène SWFUpload à croire à tort que le fichier entier a été téléversé ; il émettra un grand nombre d'événements uploadProgress jusqu'à atteindre 100%. Pendant que le proxy téléverse réellement vers le serveur cible, SWFUpload semble être en pause.

Antivirus Kaspersky : Kaspersky(et certains autres logiciels antivirus) mettent en œuvre un proxy côté client pour intercepter les données de téléversement sortantes locales. SWFUpload ne peut pas détecter l'existence de ce système de proxy. Ces serveurs proxy peuvent recevoir très rapidement les fichiers téléversés, les analyser, puis les envoyer au serveur cible.

Module de sécurité Apache mod_security

Le module de sécurité d'Apache mod_security valide les messages POST reçus par le serveur. Flash Player implémente un cas limite (faut-il traduire « an edge case » par « moyen astucieux de » ?) (il existe un paramètre qui permet de décider s'il faut valider). Les téléversements POST envoient des fichiers, et le serveur implémente également cela.

Secure Sockets Layer SSL

Nous avons reçu des rapports indiquant que Flash Player ne peut pas téléverser via SSL. Les circonstances précises de ce problème n'ont pas encore été confirmées, mais il semble bien que le téléversement sous SSL soit peu fiable. Des problèmes surviennent particulièrement lors de l'utilisation de certificats auto-signés à clé publique.

De même, les certificats SSL émis par des autorités de certification (CA) non fiables ne peuvent pas être acceptés par Flash, car Flash ne fournit pas de méthode pour accepter de tels certificats. Comme pour le bogue de cookie mentionné précédemment, Flash Player sous Windows n'accepte que les certificats émis par des CA figurant sur sa liste de confiance, quel que soit le certificat actuellement utilisé par le navigateur.

Authentification

Les mécanismes d'authentification HTTP ne sont pas bien pris en charge par Flash Player. Les versions plus récentes de Flash Player sont un peu meilleures ; les versions plus anciennes peuvent provoquer des plantages du navigateur.

Connexions interrompues prématurément

Le fait de terminer prématurément la réponse (comme la méthode Response.end() en ASP.NET) peut amener SWFUpload à signaler un échec de téléversement alors que le téléversement était en réalité terminé.

Nom POST du fichier : nom POST Filedata sous Linux

La modification du nom de réception du fichier (par défaut "Filedata", définie via la propriété file_post_name de l'objet de paramètres) ne fonctionne pas dans Flash Player sous Linux.

Bogue des cookies

Sous Windows, dans les navigateurs autres qu'IE (FireFox, Opera, Safari, etc.), le plugin Flash envoie les cookies d'IE. Cela casse les mécanismes de session et d'authentification sur de nombreux serveurs.

Les développeurs doivent résoudre manuellement le problème de transmission des informations de session et de cookie d'authentification, et également modifier manuellement la session sur le serveur s'ils veulent utiliser des sessions.

Cependant, le paquet SWFUpload fournit un exemple de code pour résoudre ce bogue en PHP ou ASP.Net.

Bogues d’ExternalInterface

Lors de l’interaction avec le navigateur/JS, Flash Player ne peut pas utiliser correctement la méthode escape pour encoder les données. SWFUpload a fait de grands efforts pour résoudre ce problème. À l’avenir, si ce bogue est corrigé, SWFUpload enverra des données supplémentaires encodées avec escape.

Bogues de longueur des données du serveur

Des données de réponse serveur excessivement longues peuvent provoquer des erreurs sous Flash Player sur les systèmes MAC ou Linux. Les données peuvent être tronquées, altérées ou, dans certains cas, dupliquées. Nous recommandons que le serveur renvoie des données aussi courtes et concises que possible.

Avant Browser

Une fois mis en cache, SWFUpload ne fonctionne pas correctement sur Avant Browser.

Depuis SWFUpload v2.2.0, le paramètre prevent_swf_caching a été ajouté pour tenter de résoudre ce problème.

Boîte de dialogue de fichier et changement de page

Le fait de quitter ou d’actualiser la page pendant que la boîte de dialogue de sélection de fichier est ouverte provoquera le plantage du navigateur. (Sur tous les navigateurs, tous les systèmes d’exploitation.)

Cette situation se produit principalement lorsque vous définissez l’attribut "onclick" d’un lien hypertexte <a> pour appeler selectFile/selectFiles, mais que vous n’empêchez pas son action de navigation par défaut. Cliquer sur le lien naviguera vers une autre page tout en ouvrant la boîte de dialogue de sélection de fichier.

(yukon : Autre possibilité : le programme force une actualisation ou une redirection de page. Par exemple, une actualisation dans une balise HTML <meta>, Response.Redirect() d’ASP.NET, header() de PHP, etc.)

Scripts de téléversement de longue durée

Après que Flash téléverse un fichier vers le serveur web, le script de réception de l’envoi est exécuté. Le script de réception décide s’il faut stocker les fichiers, créer des vignettes, analyser les virus, etc. Si le script de réception ne renvoie aucune donnée dans les 30 secondes, Flash déconnectera la connexion et renverra une erreur IO.

Si vous ne voulez pas que cela se produise, alors pendant le traitement, faites en sorte que le serveur renvoie quelques caractères ou données (si possible).

Par exemple avec PHP, bien que le script PHP puisse continuer à terminer ses opérations avec succès après que Flash se déconnecte, Flash ne recevra aucune donnée renvoyée après la déconnexion.

Mode de fenêtre WMODE / BUTTON_WINDOW_MODE

Dans certains navigateurs, si le contrôle Flash ne se trouve pas dans la zone visible de l’écran, le WMODE défini (configuré par BUTTON_WINDOW_MODE) empêchera le contrôle Flash de se charger. Ce n’est que lorsque vous faites défiler et amenez le contrôle Flash dans la zone visible de l’écran qu’il se chargera et s’affichera.

(yukon : ceci est fait pour que la page s’affiche aussi rapidement que possible. Par exemple, si vous ouvrez un dossier plein d’images, réglez le mode d’affichage sur vignettes et faites défiler rapidement vers le bas, vous verrez les fichiers image en dessous afficher progressivement leur contenu.)

Ce comportement peut avoir un effet néfaste sur le plugin SWFObject. Les événements SWFUpload peuvent ne pas être déclenchés, et l’image d’arrière-plan du bouton peut ne pas se charger tant que le contrôle n’a pas été rendu.

Sur certains systèmes d’exploitation (Linux), lorsque WMODE est défini sur transparent, la boîte de dialogue de sélection de fichier ouverte par Flash apparaîtra derrière la fenêtre du navigateur.

Fuites de mémoire

Certains navigateurs (en particulier IE) ne peuvent pas récupérer la mémoire après que Flash Player utilise la classe ExternalInterface pour interagir avec JS (par exemple SWFUpload). Créer trop d’instances SWFUpload et actualiser la page plusieurs fois amènera le navigateur à occuper une mémoire excessive, ce qui entraîne à son tour des plantages du navigateur ou d’autres erreurs système.

Dans SWFUpload v2.2.0, nous avons implémenté certains mécanismes pour éviter les fuites de mémoire. Cependant, il est toujours recommandé d’appeler la méthode destroy() lorsque la page est fermée. Si vous utilisez des centaines d’instances SWFUpload sur une seule page, vous devez tester soigneusement pour éviter les fuites de mémoire.

Quelques problèmes liés à Mac OS — Autres problèmes Mac

Les données renvoyées par le serveur ou par Flash Player sur les systèmes Mac peuvent ne pas déclencher l’événement uploadSuccess. Nous avons ajouté un paramètre assume_success_timeout pour aider à résoudre ce problème. Cependant, en général, il est très simple et fiable de renvoyer un champ court après une réception réussie.
Certains utilisateurs ont signalé des problèmes lors du téléversement vers des adresses comportant un sous-domaine sur les systèmes Mac.
Certains utilisateurs ont signalé que les redirections (code d’état HTTP 302) ne sont pas bien gérées par Flash Player sur Mac. Il semble que ce problème n’existe pas sous Windows. Les redirections 302 sont souvent utilisées dans certains modes d’autorisation et frameworks de conception MVC.
La documentation de développement Flash indique que, sur les systèmes antérieurs à OS X 10.3, les octets chargés seront toujours -1. SWFUpload le remplace par 0, mais le nombre total d’octets ne sera pas envoyé, et la progression n’atteindra jamais 100%. Par conséquent, veuillez mettre à jour l’interface utilisateur pour afficher 100% lorsque le téléversement est terminé et que l’événement uploadSuccess ou uploadComplete est déclenché. Cela permet de garder l’interface utilisateur cohérente sur tous les systèmes.
Certains utilisateurs ont signalé que Flash Player sur Mac rencontre des problèmes lorsque le chemin de téléversement contient des espaces. Veuillez les remplacer par + ou %20.
Certains utilisateurs ont signalé que Flash Player sur Mac ajoute le numéro de port à l’en-tête HTTP HOST (par exemple, http://www.example.com:80). Si vous vérifiez ce paramètre, faites attention à gérer ce problème.
Si un fichier ne contient qu’un fork de ressources, il sera traité par Flash Player comme un fichier de 0 octet et ne pourra pas être téléversé (Remarque : Flash Player 10.1 a peut-être corrigé ce problème).