270 lines
13 KiB
Markdown
270 lines
13 KiB
Markdown
|
<!--
|
||
|
|
# license: Licensed to the Apache Software Foundation (ASF) under one
|
||
|
|
# or more contributor license agreements. See the NOTICE file
|
||
|
|
# distributed with this work for additional information
|
||
|
|
# regarding copyright ownership. The ASF licenses this file
|
||
|
|
# to you under the Apache License, Version 2.0 (the
|
||
|
|
# "License"); you may not use this file except in compliance
|
||
|
|
# with the License. You may obtain a copy of the License at
|
||
|
|
#
|
||
|
|
# http://www.apache.org/licenses/LICENSE-2.0
|
||
|
|
#
|
||
|
|
# Unless required by applicable law or agreed to in writing,
|
||
|
|
# software distributed under the License is distributed on an
|
||
|
|
# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
|
||
|
|
# KIND, either express or implied. See the License for the
|
||
|
|
# specific language governing permissions and limitations
|
||
|
|
# under the License.
|
||
|
|
-->
|
||
|
|
|
||
|
|
# cordova-plugin-file-transfer
|
||
|
|
|
||
|
|
[](https://travis-ci.org/apache/cordova-plugin-file-transfer)
|
||
|
|
|
||
|
|
Documentation du plugin : <doc/index.md>
|
||
|
|
|
||
|
|
Ce plugin vous permet de télécharger des fichiers.
|
||
|
|
|
||
|
|
Ce plugin définit global `FileTransfer` , `FileUploadOptions` constructeurs.
|
||
|
|
|
||
|
|
Bien que dans la portée globale, ils ne sont pas disponibles jusqu'après la `deviceready` événement.
|
||
|
|
|
||
|
|
document.addEventListener (« deviceready », onDeviceReady, false) ;
|
||
|
|
function onDeviceReady() {console.log(FileTransfer);}
|
||
|
|
|
||
|
|
|
||
|
|
## Installation
|
||
|
|
|
||
|
|
cordova plugin add cordova-plugin-file-transfer
|
||
|
|
|
||
|
|
|
||
|
|
## Plates-formes supportées
|
||
|
|
|
||
|
|
* Amazon Fire OS
|
||
|
|
* Android
|
||
|
|
* BlackBerry 10
|
||
|
|
* Navigateur
|
||
|
|
* Firefox OS **
|
||
|
|
* iOS
|
||
|
|
* Windows Phone 7 et 8 *
|
||
|
|
* Windows 8
|
||
|
|
* Windows
|
||
|
|
|
||
|
|
\ * *Ne supportent pas `onprogress` ni `abort()` *
|
||
|
|
|
||
|
|
\ ** *Ne prennent pas en charge les `onprogress` *
|
||
|
|
|
||
|
|
# Transfert de fichiers
|
||
|
|
|
||
|
|
L'objet de `FileTransfer` fournit un moyen de télécharger des fichiers à l'aide d'une requête HTTP multi-part POST ou PUT et pour télécharger des fichiers.
|
||
|
|
|
||
|
|
## Propriétés
|
||
|
|
|
||
|
|
* **onprogress** : fonction appelée avec un `ProgressEvent` à chaque fois qu'un nouveau segment de données est transféré. *(Function)*
|
||
|
|
|
||
|
|
## Méthodes
|
||
|
|
|
||
|
|
* **upload** : envoie un fichier à un serveur.
|
||
|
|
|
||
|
|
* **download** : télécharge un fichier depuis un serveur.
|
||
|
|
|
||
|
|
* **abort** : annule le transfert en cours.
|
||
|
|
|
||
|
|
## upload
|
||
|
|
|
||
|
|
**Paramètres**:
|
||
|
|
|
||
|
|
* **fileURL** : système de fichiers URL représentant le fichier sur le périphérique. Pour la compatibilité ascendante, cela peut aussi être le chemin complet du fichier sur le périphérique. (Voir [Backwards Compatibility Notes] ci-dessous)
|
||
|
|
|
||
|
|
* **server** : l'URL du serveur destiné à recevoir le fichier, encodée via `encodeURI()`.
|
||
|
|
|
||
|
|
* **successCallback**: un rappel passé un `FileUploadResult` objet. *(Fonction)*
|
||
|
|
|
||
|
|
* **errorCallback**: un rappel qui s'exécute si une erreur survient récupérer la `FileUploadResult` . Appelée avec un `FileTransferError` objet. *(Fonction)*
|
||
|
|
|
||
|
|
* **options**: paramètres facultatifs *(objet)*. Clés valides :
|
||
|
|
|
||
|
|
* **fileKey**: le nom de l'élément form. Valeur par défaut est `file` . (DOMString)
|
||
|
|
* **fileName**: le nom de fichier à utiliser lorsque vous enregistrez le fichier sur le serveur. Valeur par défaut est `image.jpg` . (DOMString)
|
||
|
|
* **httpMethod**: méthode de The HTTP à utiliser - soit `PUT` ou `POST` . Valeur par défaut est `POST` . (DOMString)
|
||
|
|
* **type MIME**: le type mime des données à télécharger. Valeur par défaut est `image/jpeg` . (DOMString)
|
||
|
|
* **params**: un ensemble de paires clé/valeur facultative pour passer dans la requête HTTP. (Objet)
|
||
|
|
* **chunkedMode**: s'il faut télécharger les données en mode streaming mémorisé en bloc. Valeur par défaut est `true` . (Boolean)
|
||
|
|
* **headers**: une carte des valeurs d'en-tête en-tête/nom. Un tableau permet de spécifier plusieurs valeurs. Sur iOS, FireOS et Android, si un en-tête nommé Content-Type n'est présent, les données de formulaire multipart servira pas. (Object)
|
||
|
|
* **httpMethod**: The HTTP méthode à utiliser par exemple poster ou mis. Par défaut, `message`. (DOMString)
|
||
|
|
|
||
|
|
* **trustAllHosts**: paramètre facultatif, valeur par défaut est `false` . Si la valeur est `true` , il accepte tous les certificats de sécurité. Ceci est utile car Android rejette des certificats auto-signés. N'est pas recommandé pour une utilisation en production. Supporté sur Android et iOS. *(booléen)*
|
||
|
|
|
||
|
|
### Exemple
|
||
|
|
|
||
|
|
// !! Suppose fileURL variable contient une URL valide dans un fichier texte sur le périphérique, / / par exemple, cdvfile://localhost/persistent/path/to/file.txt var win = function (r) {console.log ("Code =" + r.responseCode) ;
|
||
|
|
Console.log ("réponse =" + r.response) ;
|
||
|
|
Console.log ("envoyés =" + r.bytesSent);}
|
||
|
|
|
||
|
|
échouer var = function (erreur) {alert ("une erreur est survenue : Code =" + error.code) ;
|
||
|
|
Console.log (« source de l'erreur de téléchargement » + error.source) ;
|
||
|
|
Console.log ("erreur de téléchargement cible" + error.target);}
|
||
|
|
|
||
|
|
options de var = new FileUploadOptions() ;
|
||
|
|
options.fileKey = « fichier » ;
|
||
|
|
options.fileName = fileURL.substr(fileURL.lastIndexOf('/') + 1) ;
|
||
|
|
options.mimeType = « text/plain » ;
|
||
|
|
|
||
|
|
var params = {} ;
|
||
|
|
params.value1 = « test » ;
|
||
|
|
params.Value2 = « param » ;
|
||
|
|
|
||
|
|
options.params = params ;
|
||
|
|
|
||
|
|
ft var = new FileTransfer() ;
|
||
|
|
ft.upload (fileURL, encodeURI ("http://some.server.com/upload.php"), win, fail, options) ;
|
||
|
|
|
||
|
|
|
||
|
|
### Exemple avec téléchargement du Header et des Progress Events (Android et iOS uniquement)
|
||
|
|
|
||
|
|
function win(r) {console.log ("Code =" + r.responseCode) ;
|
||
|
|
Console.log ("réponse =" + r.response) ;
|
||
|
|
Console.log ("envoyés =" + r.bytesSent);}
|
||
|
|
|
||
|
|
function fail(error) {alert ("une erreur est survenue : Code =" + error.code) ;
|
||
|
|
Console.log (« source de l'erreur de téléchargement » + error.source) ;
|
||
|
|
Console.log ("erreur de téléchargement cible" + error.target);}
|
||
|
|
|
||
|
|
var uri = encodeURI ("http://some.server.com/upload.php") ;
|
||
|
|
|
||
|
|
options de var = new FileUploadOptions() ;
|
||
|
|
options.fileKey="file" ;
|
||
|
|
options.fileName=fileURL.substr(fileURL.lastIndexOf('/')+1) ;
|
||
|
|
options.mimeType="text/plain" ;
|
||
|
|
|
||
|
|
en-têtes var ={'headerParam':'headerValue'} ;
|
||
|
|
|
||
|
|
options.Headers = en-têtes ;
|
||
|
|
|
||
|
|
ft var = new FileTransfer() ;
|
||
|
|
ft.OnProgress = function(progressEvent) {si (progressEvent.lengthComputable) {loadingStatus.setPercentage(progressEvent.loaded / progressEvent.total) ;
|
||
|
|
} else {loadingStatus.increment() ;
|
||
|
|
}
|
||
|
|
};
|
||
|
|
ft.upload (fileURL, uri, win, fail, options) ;
|
||
|
|
|
||
|
|
|
||
|
|
## FileUploadResult
|
||
|
|
|
||
|
|
A `FileUploadResult` objet est passé au rappel de succès la `FileTransfer` de l'objet `upload()` méthode.
|
||
|
|
|
||
|
|
### Propriétés
|
||
|
|
|
||
|
|
* **bytesSent** : le nombre d'octets envoyés au serveur dans le cadre du téléchargement. (long)
|
||
|
|
|
||
|
|
* **responseCode** : le code de réponse HTTP retourné par le serveur. (long)
|
||
|
|
|
||
|
|
* **response** : la réponse HTTP renvoyée par le serveur. (DOMString)
|
||
|
|
|
||
|
|
* **en-têtes** : en-têtes de réponse HTTP par le serveur. (Objet)
|
||
|
|
|
||
|
|
* Actuellement pris en charge sur iOS seulement.
|
||
|
|
|
||
|
|
### Notes au sujet d'iOS
|
||
|
|
|
||
|
|
* Ne prend pas en charge les propriétés `responseCode` et `bytesSent`.
|
||
|
|
|
||
|
|
## download
|
||
|
|
|
||
|
|
**Paramètres**:
|
||
|
|
|
||
|
|
* **source** : l'URL du serveur depuis lequel télécharger le fichier, encodée via `encodeURI()`.
|
||
|
|
|
||
|
|
* **target** : système de fichiers url représentant le fichier sur le périphérique. Pour la compatibilité ascendante, cela peut aussi être le chemin complet du fichier sur le périphérique. (Voir [Backwards Compatibility Notes] ci-dessous)
|
||
|
|
|
||
|
|
* **successCallback** : une callback de succès à laquelle est passée un objet `FileEntry`. *(Function)*
|
||
|
|
|
||
|
|
* **errorCallback**: un rappel qui s'exécute si une erreur se produit lors de la récupération du `FileEntry` . Appelée avec un `FileTransferError` objet. *(Fonction)*
|
||
|
|
|
||
|
|
* **trustAllHosts**: paramètre facultatif, valeur par défaut est `false` . Si la valeur est `true` , il accepte tous les certificats de sécurité. Ceci peut être utile car Android rejette les certificats auto-signés. N'est pas recommandé pour une utilisation en production. Supporté sur Android et iOS. *(booléen)*
|
||
|
|
|
||
|
|
* **options** : paramètres facultatifs, seules les en-têtes sont actuellement supportées (par exemple l'autorisation (authentification basique), etc.).
|
||
|
|
|
||
|
|
### Exemple
|
||
|
|
|
||
|
|
// !! Suppose fileURL variable contient une URL valide vers un chemin d'accès sur le périphérique, / / par exemple, transfert de fichiers var cdvfile://localhost/persistent/path/to/downloads/ = new FileTransfer() ;
|
||
|
|
var uri = encodeURI ("http://some.server.com/download.php") ;
|
||
|
|
|
||
|
|
fileTransfer.download (uri, fileURL, function(entry) {console.log ("téléchargement complet:" + entry.toURL()) ;
|
||
|
|
}, function(error) {console.log (« source de l'erreur de téléchargement » + error.source) ;
|
||
|
|
Console.log (« erreur de téléchargement cible » + error.target) ;
|
||
|
|
Console.log (« code d'erreur de téléchargement » + error.code) ;
|
||
|
|
}, faux, {en-têtes: {« Autorisation »: « dGVzdHVzZXJuYW1lOnRlc3RwYXNzd29yZA base == "}}) ;
|
||
|
|
|
||
|
|
|
||
|
|
### Quirks wp8
|
||
|
|
|
||
|
|
* Télécharger demande est mis en cache par l'implémentation native. Pour éviter la mise en cache, pass `if-Modified-Since` en-tête Télécharger méthode.
|
||
|
|
|
||
|
|
## abort
|
||
|
|
|
||
|
|
Abandonne un transfert en cours. Le rappel onerror est passé à un objet FileTransferError qui a un code d'erreur de FileTransferError.ABORT_ERR.
|
||
|
|
|
||
|
|
### Exemple
|
||
|
|
|
||
|
|
// !! Suppose fileURL variable contient une URL valide dans un fichier texte sur le périphérique, / / par exemple, cdvfile://localhost/persistent/path/to/file.txt var win = function(r) {console.log ("ne devrait pas être appelée.");}
|
||
|
|
|
||
|
|
var fail = function(error) {/ / error.code == FileTransferError.ABORT_ERR alert ("une erreur est survenue : Code =" + error.code) ;
|
||
|
|
Console.log (« source de l'erreur de téléchargement » + error.source) ;
|
||
|
|
Console.log ("erreur de téléchargement cible" + error.target);}
|
||
|
|
|
||
|
|
options de var = new FileUploadOptions() ;
|
||
|
|
options.fileKey="file" ;
|
||
|
|
options.fileName="myphoto.jpg" ;
|
||
|
|
options.mimeType="image/jpeg" ;
|
||
|
|
|
||
|
|
ft var = new FileTransfer() ;
|
||
|
|
ft.upload (fileURL, encodeURI ("http://some.server.com/upload.php"), win, fail, options) ;
|
||
|
|
ft.Abort() ;
|
||
|
|
|
||
|
|
|
||
|
|
## FileTransferError
|
||
|
|
|
||
|
|
A `FileTransferError` objet est passé à un rappel d'erreur lorsqu'une erreur survient.
|
||
|
|
|
||
|
|
### Propriétés
|
||
|
|
|
||
|
|
* **code** : l'un des codes d'erreur prédéfinis énumérés ci-dessous. (Number)
|
||
|
|
|
||
|
|
* **source** : l'URI de la source. (String)
|
||
|
|
|
||
|
|
* **target**: l'URI de la destination. (String)
|
||
|
|
|
||
|
|
* **http_status** : code d'état HTTP. Cet attribut n'est disponible que lorsqu'un code de réponse est fourni via la connexion HTTP. (Number)
|
||
|
|
|
||
|
|
* **corps** Corps de réponse. Cet attribut n'est disponible que lorsqu'une réponse est reçue de la connexion HTTP. (String)
|
||
|
|
|
||
|
|
* **exception**: soit e.getMessage ou e.toString (String)
|
||
|
|
|
||
|
|
### Constantes
|
||
|
|
|
||
|
|
* 1 = `FileTransferError.FILE_NOT_FOUND_ERR`
|
||
|
|
* 2 = `FileTransferError.INVALID_URL_ERR`
|
||
|
|
* 3 = `FileTransferError.CONNECTION_ERR`
|
||
|
|
* 4 = `FileTransferError.ABORT_ERR`
|
||
|
|
* 5 = `FileTransferError.NOT_MODIFIED_ERR`
|
||
|
|
|
||
|
|
## Backwards Compatibility Notes
|
||
|
|
|
||
|
|
Les versions précédentes de ce plugin n'accepterait périphérique--fichier-chemins d'accès absolus comme source pour les téléchargements, ou comme cible pour les téléchargements. Ces chemins seraient généralement de la forme
|
||
|
|
|
||
|
|
/ var/mobile/Applications/< application UUID >/Documents/chemin/vers/fichier (iOS), /storage/emulated/0/path/to/file (Android)
|
||
|
|
|
||
|
|
|
||
|
|
Pour vers l'arrière la compatibilité, ces chemins sont toujours acceptés, et si votre application a enregistré des chemins comme celles-ci dans un stockage persistant, alors ils peuvent continuer à être utilisé.
|
||
|
|
|
||
|
|
Ces chemins ont été précédemment exposés dans le `fullPath` propriété de `FileEntry` et `DirectoryEntry` les objets retournés par le fichier plugin. Nouvelles versions du fichier plugin, cependant, ne plus exposent ces chemins à JavaScript.
|
||
|
|
|
||
|
|
Si vous migrez vers une nouvelle (1.0.0 ou plus récent) version de fichier et vous avez précédemment utilisé `entry.fullPath` comme arguments à `download()` ou `upload()` , alors vous aurez besoin de modifier votre code pour utiliser le système de fichiers URL au lieu de cela.
|
||
|
|
|
||
|
|
`FileEntry.toURL()`et `DirectoryEntry.toURL()` retournent une URL de système de fichiers du formulaire
|
||
|
|
|
||
|
|
cdvfile://localhost/persistent/path/to/file
|
||
|
|
|
||
|
|
|
||
|
|
qui peut être utilisé à la place le chemin d'accès absolu au fichier dans les deux `download()` et `upload()` méthodes.
|