File

File

Esta API te permite leer, escribir y navegar sobre el sistema de ficheros.

Objetos


File

Este objeto contiene atributos de un archivo o fichero en particular.

Atributos

Detalles

El objeto File contiene atributos sobre un fichero en particular. Puedes obtener una instancia de un fichero File, llamando al método file de un objeto FileEntry.

Plataformas Soportadas


FileReader

FileReader es un objeto que permite leer un fichero.

Atributos

Métodos

Detalles

El objeto FileReader permite leer ficheros del sistema de archivos del dispositivo. Los ficheros pueden ser leídos como texto plano o codificados en base64. Los desarrolladores pueden registrar sus propias funciones a los eventos 'loadstart', 'progress', 'load', 'loadend', 'error' y 'abort'.

Plataformas Soportadas

Leer como URL

Argumentos: - file - El objeto File a leer.

Ejemplo Rápido

function win(file) {
    var reader = new FileReader();
    reader.onloadend = function(evt) {
        console.log("read success");
        console.log(evt.target.result);
    };
    reader.readAsDataURL(file);
};

var fail = function(evt) {
    console.log(error.code);
};

entry.file(win, fail);

Leer como texto

Argumentos:

Ejemplo Rápido

function win(file) {
    var reader = new FileReader();
    reader.onloadend = function(evt) {
        console.log("read success");
        console.log(evt.target.result);
    };
    reader.readAsText(file);
};

var fail = function(evt) {
    console.log(error.code);
};

entry.file(win, fail);

Ejemplo Rápido del método 'abort'

function win(file) {
    var reader = new FileReader();
    reader.onloadend = function(evt) {
        console.log("read success");
        console.log(evt.target.result);
    };
    reader.readAsText(file);
    reader.abort();
};

function fail(error) {
    console.log(error.code);
}

entry.file(win, fail);

Ejemplo Completo

<!DOCTYPE html>
<html>
  <head>
    <title>Ejemplo de FileReader</title>

    <script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
    <script type="text/javascript" charset="utf-8">

    // Espera a que phonegap se inicie
    //
    function onLoad() {
        document.addEventListener("deviceready", onDeviceReady, false);
    }

    // PhoneGap esta listo
    //
    function onDeviceReady() {
        window.requestFileSystem(LocalFileSystem.PERSISTENT, 0, gotFS, fail);
    }

    function gotFS(fileSystem) {
        fileSystem.root.getFile("readme.txt", {create: true}, gotFileEntry, fail);
    }

    function gotFileEntry(fileEntry) {
        fileEntry.file(gotFile, fail);
    }

    function gotFile(file){
        readDataUrl(file);
        readAsText(file);
    }

    function readDataUrl(file) {
        var reader = new FileReader();
        reader.onloadend = function(evt) {
            console.log("Read as data URL");
            console.log(evt.target.result);
        };
        reader.readAsDataURL(file);
    }

    function readAsText(file) {
        var reader = new FileReader();
        reader.onloadend = function(evt) {
            console.log("Read as text");
            console.log(evt.target.result);
        };
        reader.readAsText(file);
    }

    function fail(evt) {
        console.log(evt.target.error.code);
    }

    </script>
  </head>
  <body>
    <h1>Ejemplo</h1>
    <p>Lectura de ficheros</p>
  </body>
</html>

Peculiaridades iOS


FileWriter

FileWriter es un objeto que permite escribir en un archivo.

Atributos

Métodos

Detalles

El objeto FileWriter es una forma de escribir ficheros al sistema de archivos del dispositivo. Los desarrolladores pueden registrar sus propias funciones 'callbacks' a los eventos 'writestart', 'progress', 'write', 'writeend', 'error' y 'abort'.

Se creara un FileWriter para un solo fichero. Puedes usarlo para escribir un fichero múltiples veces. El objeto FileWriter mantiene los atributos de posición y longitud, por lo que podrás usar FileWriter.seek y FileWriter.write en cualquier posición del archivo. Por defecto el objeto FileWriter escribe al inicio del fichero (sobreescribiendo información). Indica el atributo opcional append a true en el constructor de FileWriter para iniciar la escritura desde el final del archivo.

Plataformas Soportadas

Ejemplo Rápido de Seek

function win(writer) {
    // Adelanta rápidamente el puntero hacia el final del archivo
    writer.seek(writer.length); 
};

var fail = function(evt) {
    console.log(error.code);
};

entry.createWriter(win, fail);

Ejemplo Rápido de Truncate

function win(writer) {
    writer.truncate(10);    
};

var fail = function(evt) {
    console.log(error.code);
};

entry.createWriter(win, fail);

Ejemplo Rápido de Write

function win(writer) {
    writer.onwrite = function(evt) {
        console.log("Se escribió satisfactoriamente");
    };
    writer.write("Un texto de ejemplo");
};

var fail = function(evt) {
    console.log(error.code);
};

entry.createWriter(win, fail);

Ejemplo Rápido de Append

function win(writer) {
    writer.onwrite = function(evt) {
        console.log("Se escribió satisfactoriamente");
    };
    writer.seek(writer.length);
    writer.write("texto añadido");
};

var fail = function(evt) {
    console.log(error.code);
};

entry.createWriter(win, fail);

Ejemplo Rápido de Abort

function win(writer) {
    writer.onwrite = function(evt) {
        console.log("Se escribió satisfactoriamente");
    };
    writer.write("Un texto de ejemplo");
    writer.abort();
};

var fail = function(evt) {
    console.log(error.code);
};

entry.createWriter(win, fail);

Ejemplo Completo

<!DOCTYPE html>
<html>
  <head>
    <title>Ejemplo de FileWriter</title>

    <script type="text/javascript" charset="utf-8" src="phonegap.0.9.4.js"></script>
    <script type="text/javascript" charset="utf-8">

    // Espera a que PhoneGap se inicie
    //
    document.addEventListener("deviceready", onDeviceReady, false);

    // PhoneGap esta lista
    //
    function onDeviceReady() {
        window.requestFileSystem(LocalFileSystem.PERSISTENT, 0, gotFS, fail);
    }

    function gotFS(fileSystem) {
        fileSystem.root.getFile("leeme.txt", {create: true}, gotFileEntry, fail); 
    }

    function gotFileEntry(fileEntry) {
        fileEntry.createWriter(gotFileWriter, fail);
    }

    function gotFileWriter(writer) {
        writer.onwrite = function(evt) {
            console.log("Se escribió satisfactoriamente");
        };
        writer.write("some sample text");
        // El contenido del fichero ahora es 'some sample text'
        writer.truncate(11);
        // El contenido del fichero ahora es 'some sample'
        writer.seek(4);
        // El contenido del fichero aun es 'some sample' pero el puntero apunta después del carácter 'e' de 'some'
        writer.write(" different text");
        // El contenido del fichero ahora es 'some different text'
    }

    function fail(error) {
        console.log(error.code);
    }

    </script>
  </head>
  <body>
    <h1>Ejemplo</h1>
    <p>Escritura de ficheros</p>
  </body>
</html>

FileSystem

Este objeto modela al sistema de archivos.

Atributos

Detalles

El objeto FileSystem representa toda la información del sistema de archivos. El nombre del sistema de archivos sera único entre todos los sistemas de archivos. El atributo root contiene un objeto DirectoryEntry que representa el directorio raíz de este sistema de archivos.

Plataformas Soportadas

Ejemplo Rápido del Sistema de Archivos

function onSuccess(fileSystem) {
    console.log(fileSystem.name);
    console.log(fileSystem.root.name);
}

// Solicita el sistema de archivos persistente
window.requestFileSystem(LocalFileSystem.PERSISTENT, 0, onSuccess, null);

Ejemplo Completo

<!DOCTYPE html>
<html>
  <head>
    <title>Ejemplo de FileSystem</title>

    <script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
    <script type="text/javascript" charset="utf-8">

    // Espera a que PhoneGap se inicie
    //
    document.addEventListener("deviceready", onDeviceReady, false);

    // PhoneGap esta listo
    //
    function onDeviceReady() {
        window.requestFileSystem(LocalFileSystem.PERSISTENT, 0, onFileSystemSuccess, fail);
    }

    function onFileSystemSuccess(fileSystem) {
        console.log(fileSystem.name);
        console.log(fileSystem.root.name);
    }

    function fail(evt) {
        console.log(evt.target.error.code);
    }

    </script>
  </head>
  <body>
    <h1>Ejemplo</h1>
    <p>Sistema de Archivos</p>
  </body>
</html>

FileEntry

Este objeto representa un fichero de su sistema de archivos. Esto esta regulado por las especificaciones W3C Directories and Systems.

Atributos

NOTA: Los siguientes atributos están especificados por la W3C pero no están soportados por PhoneGap:

Métodos

Plataformas Soportadas

getMetadata

Busca metadatos en el fichero.

Argumentos:

Ejemplo Rápido

function success(metadata) {
    console.log("Ultima modificación: " + metadata.modificationTime);
}

function fail(error) {
    alert(error.code);
}

// Solicita los metadatos de este fichero
entry.getMetadata(success, fail);

moveTo

Mueve el fichero hacia una ruta diferente en el sistema de archivos. Las siguientes acciones se consideran erróneas:

También, si intentar mover el fichero sobre otro fichero existente, se intentara eliminarlo y reemplazarlo.

Argumentos:

Ejemplo Rápido

function success(entry) {
    console.log("Nueva ruta: " + entry.fullPath);
}

function fail(error) {
    alert(error.code);
}

function moveFile(entry) {
    var parent = document.getElementById('parent').value,
        parentEntry = new DirectoryEntry({fullPath: parent});

    // mueve el fichero a un nuevo directorio y lo renombra
    entry.moveTo(parentEntry, "newFile.txt", success, fail);
}

copyTo

Copia un fichero hacia una nueva ruta el sistema de archivos. Las siguientes acciones se consideran erróneas:

Argumentos:

Ejemplo Rápido

function win(entry) {
    console.log("Nueva ruta: " + entry.fullPath);
}

function fail(error) {
    alert(error.code);
}

function copyFile(entry) {
    var parent = document.getElementById('parent').value,
        parentEntry = new DirectoryEntry({fullPath: parent});

    // copia el fichero a un nuevo directorio y lo renombra
    entry.copyTo(parentEntry, "file.copy", success, fail);
}

toURI

Retorna una URI que puede ser usada para localizar el fichero

Ejemplo Rápido

// Obtiene la URI de esta entrada
var uri = entry.toURI();
console.log(uri);

remove

Elimina el fichero.

Argumentos:

Ejemplo Rápido

function success(entry) {
    console.log("Eliminado satisfactoriamente");
}

function fail(error) {
    alert('Error eliminando el archivo: ' + error.code);
}

// elimina el archivo
entry.remove(success, fail);

getParent

Busca el DirectoryEntry padre que contiene al archivo.

Argumentos:

Ejemplo Rápido

function success(parent) {
    console.log("Nombre del padre: " + parent.name);
}

function fail(error) {
    alert(error.code);
}

// Obtiene el `DirectoryEntry` padre
entry.getParent(success, fail);

createWriter

Crea un objeto FileWriter asociado con este FileEntry.

Argumentos:

Ejemplo Rápido

function success(writer) {
    writer.write("Vamos a escribir algo...");
}

function fail(error) {
    alert(error.code);
}

// crea un objeto `FileWriter` para escribir en el archivo
entry.createWriter(success, fail);

file

Retorna un objeto File que modela el estado actual del fichero asociado a este FileEntry.

Argumentos:

Ejemplo Rápido

function success(file) {
    console.log("Tamaño del archivo: " + file.size);
}

function fail(error) {
    alert("No se pudo obtener las propiedades del fichero: " + error.code);
}

// obtiene las propiedades del fichero
entry.file(success, fail);

DirectoryEntry

Este objeto modela un directorio en el sistema de archivos. Esta API esta regulada por la especificación W3C Directories and Systems.

Atributos

NOTA: Los siguientes atributos están definidos en las especificaciones W3C pero no están soportados por PhoneGap:

Métodos

Los siguientes métodos pueden ser llamados en un objeto DirectoryEntry:

Plataformas Soportadas

getMetadata

Busca metadatos sobre el directorio.

Argumentos:

Ejemplo Rápido

function success(metadata) {
    console.log("Ultima modificación: " + metadata.modificationTime);
}

function fail(error) {
    alert(error.code);
}

// Solicita el objeto Metadata de esta entrada
entry.getMetadata(success, fail);

moveTo

Mueve un directorio a un sitio diferente en el sistema de archivos. Las siguientes acciones se consideran erróneas:

Además, al mover un directorio sobre otro directorio vacio, se intentara eliminarlo y reemplazarlo.

Argumentos:

Ejemplo Rápido

function success(entry) {
    console.log("Nueva ruta: " + entry.fullPath);
}

function fail(error) {
    alert(error.code);
}

function moveDir(entry) {
    var parent = document.getElementById('parent').value,
        newName = document.getElementById('newName').value,
        parentEntry = new DirectoryEntry({fullPath: parent});

    // moverá este directorio hacia un nuevo directorio y luego lo renombrara
    entry.moveTo(parentEntry, newName, success, fail);
}

copyTo

Copia un directorio hacia otro diferente en el sistema de archivos. Las siguientes acciones se consideran erróneas:

Las copias de directorios son siempre recursivas, esto quiere decir que se copia todo el contenido del directorio.

Argumentos:

Ejemplo Rápido

function win(entry) {
    console.log("Nueva ruta: " + entry.fullPath);
}

function fail(error) {
    alert(error.code);
}

function copyDir(entry) {
    var parent = document.getElementById('parent').value,
        newName = document.getElementById('newName').value,
        parentEntry = new DirectoryEntry({fullPath: parent});

    // moverá este directorio hacia un nuevo directorio y lo renombrara
    entry.copyTo(parentEntry, newName, success, fail);
}

toURI

Retorna una URI que podrá ser usada para localizar el directorio.

Ejemplo Rápido

// Obtiene la URI de este directorio
var uri = entry.toURI();
console.log(uri);

remove

Elimina el directorio. Las siguientes acciones se consideran erróneas:

Argumentos:

Ejemplo Rápido

function success(entry) {
    console.log("Eliminado satisfactoriamente");
}

function fail(error) {
    alert('Hubo un error eliminando el directorio: ' + error.code);
}

// elimina el directorio
entry.remove(success, fail);

getParent

Busca el DirectoryEntry padre que contiene al directorio.

Argumentos:

Ejemplo Rápido

function success(parent) {
    console.log("Nombre del padre: " + parent.name);
}

function fail(error) {
    alert('Ocurrió un error obteniendo el padre: ' + error.code);
}

// Obtiene el DirectoryEntry padre
entry.getParent(success, fail);

createReader

Crea un nuevo objeto DirectoryReader para leer las entradas en un directorio.

Ejemplo Rápido

// crea un lector de directorios
var directoryReader = entry.createReader();

getDirectory

Crea o busca un directorio existente. Es un error el intentar:

Argumentos:

Ejemplo Rápido

function success(parent) {
    console.log("Nombre del padre: " + parent.name);
}

function fail(error) {
    alert("No se pudo crear el nuevo directorio: " + error.code);
}

// Retorna un directorio existe, o lo crea si no existiera
entry.getDirectory("newDir", {create: true, exclusive: false}, success, fail);

getFile

Crea o busca un fichero. Es un error el intentar:

Argumentos:

Ejemplo Rápido

function success(parent) {
    console.log("Nombre del padre: " + parent.name);
}

function fail(error) {
    alert("Ocurrió un error recuperando el fichero: " + error.code);
}

// Retorna un fichero existe, o lo crea si no existiera
entry.getFile("newFile.txt", {create: true, exclusive: false}, success, fail);

removeRecursively

Elimina un directorio y todo su contenido, si durante el proceso algún fichero no puede ser eliminado y se dispara el evento errorCallback, lo mas seguro es que parte del contenido ya halla sido eliminado.

Las siguientes acciones se consideran erróneas:

Argumentos:

Ejemplo Rápido

function success(parent) {
    console.log("Eliminación recursiva terminada");
}

function fail(error) {
    alert("Ocurrió un error al eliminar el directorio y su contenido: " + error.code);
}

// elimina el directorio y todo su contenido
entry.removeRecursively(success, fail);

DirectoryReader

Un objeto que enumera los ficheros y directorios existentes dentro de un directorio. Esta API esta definida por las especificaciones W3C Directories and Systems.

Métodos

Plataformas Soportadas

readEntries

Lee las entradas de este directorio

Argumentos:

Ejemplo Rápido

function success(entries) {
    var i;
    for (i=0; i<entries.length; i++) {
        console.log(entries[i].name);
    }
}

function fail(error) {
    alert("Ocurrió un error mientras se obtenía la lista: " + error.code);
}

// Obtiene un lector de directorio
var directoryReader = dirEntry.createReader();

// Obtiene la lista de todas las entradas de este directorio
directoryReader.readEntries(success,fail);

FileTransfer

FileTransfer es un objeto que permite subir archivos a un servidor.

Atributos

N/A

Métodos

Detalles

El objeto FileTransfer proporciona una forma de subir archivos a un servidor remoto usando una petición HTTP POST de varias partes. Están soportados los protocolos HTTP y HTTPS. Se pueden especificar parámetros opcionales pasándole al método FileTranfer.upload un objeto FileUploadOptions. Tras una subida satisfactoria, se llamara a la función 'success' y se le pasara como argumento el objeto FileUploadResult. Si ocurre un error, se llamara a la función 'error', y se le pasara un objeto FileTransferError.

Plataformas Soportadas

Ejemplo Rápido

// !! Se asume que la variable fileURI contiene un URI válido a un archivo de texto en el dispositivo

var win = function(r) {
    console.log("Código = " + r.responseCode);
    console.log("Respuesta = " + r.response);
    console.log("Enviado = " + r.bytesSent);
}

var fail = function(error) {
    alert("Ocurrió un error: Código = " = error.code);
}

var options = new FileUploadOptions();
options.fileKey="file";
options.fileName=fileURI.substr(fileURI.lastIndexOf('/')+1);
options.mimeType="text/plain";

var params = new Object();
params.value1 = "test";
params.value2 = "param";

options.params = params;

var ft = new FileTransfer();
ft.upload(fileURI, "http://ejemplo.servidor.com/upload.php", win, fail, options);

Ejemplo Completo

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
    <title>Ejemplo de FileTransfer</title>

    <script type="text/javascript" charset="utf-8" src="phonegap.0.9.4.min.js"></script>
    <script type="text/javascript" charset="utf-8">

        // Espera a que PhoneGap se inicie
        //
        document.addEventListener("deviceready", onDeviceReady, false);

        // PhoneGap esta lista
        //
        function onDeviceReady() {

            // Retorna la ruta hacia el archivo de imagen
            navigator.camera.getPicture(uploadPhoto,
                                        function(message) { alert('Fallo obteniendo imagen'); },
                                        { quality: 50, 
                                        destinationType: navigator.camera.DestinationType.FILE_URI,
                                        sourceType: navigator.camera.PictureSourceType.PHOTOLIBRARY }
                                        );

        }

        function uploadPhoto(imageURI) {
            var options = new FileUploadOptions();
            options.fileKey="file";
            options.fileName=imageURI.substr(imageURI.lastIndexOf('/')+1);
            options.mimeType="image/jpeg";

            var params = new Object();
            params.value1 = "test";
            params.value2 = "param";

            options.params = params;

            var ft = new FileTransfer();
            ft.upload(imageURI, "http://ejemplo.servidor.com/upload.php", win, fail, options);
        }

        function win(r) {
            console.log("Código = " + r.responseCode);
            console.log("Respuesta = " + r.response);
            console.log("Enviados = " + r.bytesSent);
        }

        function fail(error) {
            alert("Ocurrió un error: Código = " = error.code);
        }

        </script>
</head>
<body>
    <h1>Ejemplo</h1>
    <p>Subida de Fichero</p>
</body>
</html>

FileUploadOptions

Puede pasarse un objeto FileUploadOptions al método FileTransfer.upload para indicar parámetros adicionales a la hora de subir el archivo.

Atributos

Descripción

Puede pasarle un objeto FileUploadOptions al método FileTranfer.upload para indicar parámetros adicionales a la hora de subir el archivo.


FileUploadResult

El objeto FileUploadResult se obtiene por medio de la función 'callback' 'success' del método FileTransfer.upload.

Atributos

Descripción

El objeto FileUploadResult se obtiene por medio de la función 'callback' 'success' del método FileTransfer.upload.

Peculiaridades iOS


Flags

Este objeto se usa para pasarle argumentos a los métodos getFile y getDirectory de DirectoryEntry, que busca o crea ficheros y directorios.

Atributos

Plataformas Soportadas

Ejemplo Rápido

// Obtiene el directorio, creándolo si no existiera.
dataDir = fileSystem.root.getDirectory("data", {create: true});

// Crea el fichero (Si no existiera).
lockFile = dataDir.getFile("lockfile.txt", {create: true, exclusive: true});

LocalFileSystem

Este objeto proporciona la forma de obtener la raíz del sistema de archivos.

Métodos

Constantes

Detalles

El objeto LocalFileSystem esta definido en el objeto window.

Plataformas Soportadas

Ejemplo Rápido de Petición del Sistema de Archivos

function onSuccess(fileSystem) {
    console.log(fileSystem.name);
}

// Solicita el sistema de archivos persistente
window.requestFileSystem(LocalFileSystem.PERSISTENT, 0, onSuccess, onError);

Ejemplo Rápido de Resolución URI

function onSuccess(fileEntry) {
    console.log(fileEntry.name);
}

window.resolveLocalFileSystemURI("file:///ejemplo.txt", onSuccess, onError);

Ejemplo Completo

<!DOCTYPE html>
<html>
  <head>
    <title>Ejemplo de LocalFileSystem</title>

    <script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
    <script type="text/javascript" charset="utf-8">

    // Espere a que PhoneGap se inicie
    //
    document.addEventListener("deviceready", onDeviceReady, false);

    // PhoneGap esta listo
    //
    function onDeviceReady() {
        window.requestFileSystem(LocalFileSystem.PERSISTENT, 0, onFileSystemSuccess, fail);
        window.resolveLocalFileSystemURI("file:///ejemplo.txt", onResolveSuccess, fail);
    }

    function onFileSystemSuccess(fileSystem) {
        console.log(fileSystem.name);
    }

    function onResolveSuccess(fileEntry) {
        console.log(fileEntry.name);
    }

    function fail(evt) {
        console.log(evt.target.error.code);
    }

    </script>
  </head>
  <body>
    <h1>Ejemplo</h1>
    <p>Sistema de Archivos Local</p>
  </body>
</html>

Metadata

Esta interfaz proporciona información acerca de los estados de un fichero o directorio.

Atributos

Detalles

El objeto Metadata proporciona toda la información sobre el estado de un fichero o directorio. Puedes obtener una instancia del objeto Metadata llamando a los métodos DirectoryEntry.getMetadata y FileEntry.getMetadata.

Plataforma Soportadas

Ejemplo Rápido

function win(metadata) {
    console.log("Ultima modificación: " + metadata.modificationTime);
}

// Solicita el objeto metadata de esta entrada
entry.getMetadata(win, null);

FileError

Un objeto FileError sera creado cada vez que ocurra un error en cualquier método de la API File.

Atributos

Constantes

Descripción

El objeto FileError es el único parámetro que tienen las funciones 'callbacks' de error en la API File. Los desarrolladores deberían consultar el atributo code para determinar que tipo de error es.


FileTransferError

El objeto FileTransferError se obtiene por medio de las funciones 'callback' de errores.

Atributos

Constantes

Descripción

El objeto FileTransferError se obtiene por medio de las funciones 'callbacks' de errores cuando falla la subida.