API de Sistema de Archivos

Conceptos y uso

Esta API permite interactuar con archivos en el dispositivo local de un usuario o en un sistema de archivos en red accesible para el usuario. Las funciones principales de esta API incluyen leer archivos, escribir o guardar archivos y acceder a la estructura de directorios.

La mayor parte de la interaccin con archivos y directorios se realiza a travs de manejadores. Una clase padre FileSystemHandle ayuda a definir dos clases hijas: FileSystemFileHandle y FileSystemDirectoryHandle, para archivos y directorios respectivamente.

Los manejadores representan un archivo o directorio en el sistema del usuario. Primero, puede acceder a ellos mostrando al usuario un selector de archivos o directorios mediante mtodos como window.showOpenFilePicker() y window.showDirectoryPicker(). Una vez que se invocan, aparece el selector de archivos y el usuario selecciona un archivo o un directorio. Una vez que esto se ha realizado de forma exitosa, se devuelve un manejador.

Tambin puede acceder a los manejadores de archivos a travs de:

• El metodo DataTransferItem.getAsFileSystemHandle() de la HTML Drag and Drop API.
• La File Handling API.

Cada manejador proporciona su propia funcionalidad, y existen algunas diferencias dependiendo del que se solicite (vase la seccin interfaces para obtener detalles especficos). A continuacin, se puede acceder a los datos del archivo o a la informacin (incluidos los hijos) del directorio seleccionado. Esta API abre nuevas posibilidades funcionales que hasta ahora no existan en la web. No obstante, la seguridad ha sido una prioridad a la hora de disear la API, y el acceso a los datos de archivos y directorios no est permitido a menos que el usuario lo autorice expresamente (tenga en cuenta que este no es el caso del sistema de archivos de origen privado, ya que no es visible para el usuario.)

Sistema de archivos de origen privado

El sistema de archivos de origen privado (OPFS por sus siglas en ingls) es un punto final de almacenamiento proporcionado como parte de la API de Sistema de Archivos, que es privado para el origen de la pgina y no es visible para el usuario como el sistema de archivos clsico. Proporciona acceso a un tipo especial de archivo que est altamente optimizado para el rendimiento y ofrece acceso de escritura in situ a su contenido.

A continuacin se presentan algunos posibles casos de uso:

• Aplicaciones con cargador persistente

  • Cuando se selecciona un archivo o directorio para cargar (subir al servidor), puede copiar el archivo en un entorno de pruebas local y cargar (subir al servidor) una fragmento cada vez.
  • La aplicacin puede reiniciar las cargas despus de una interrupcin, como el cierre o bloqueo del navegador, la interrupcin de la conectividad o el apagado del ordenador o computadora.

• Videojuegos u otras aplicaciones con gran cantidad de recursos multimedia.

  • La aplicacin descarga uno o varios archivos tar de gran tamao y los descomprime de forma local dentro de una estructura de directorios.
  • La aplicacin descarga previamente los recursos en segundo plano, de modo que el usuario puede pasar a la siguiente tarea o nivel del juego sin tener que esperar a que se complete la descarga.

• Editor de audio o de fotos con acceso sin conexin a internet o cach local (ideal para mejorar el rendimiento y la velocidad).

  • La aplicacin puede escribir en archivos en su ubicacin original (por ejemplo, sobrescribiendo solo las etiquetas ID3/EXIF y no todo el archivo).

• Reproductor de vdeo sin conexin a internet

  • La aplicacin puede descargar archivos grandes (>1 GB) para verlos mas tarde.
  • La aplicacin puede acceder a archivos descargados parcialmente (para que puedas ver el primer capitulo de tu DVD, incluso si la aplicacin aun esta descargando el resto del contenido o si la aplicacin no complet la descarga porque tuviste que salir corriendo para coger el tren).

• Cliente de correo web sin conexin a internet

  • El cliente descarga los archivos adjuntos y los almacena de forma local.
  • El cliente almacena en cach los archivos adjuntos para su posterior carga.

Lea nuestro Origin private file system Para obtener instrucciones sobre como utilizarlo.

Guardar archivos

• En el caso de los manejadores asncronos, utilice la interfaz FileSystemWritableFileStream. Una vez que los datos que desea guardar estn en formato Blob, objeto String, literal de cadena o buffer, puede abrir un flujo y guardar los datos en un archivo. Este puede ser un archivo existente o uno nuevo.
• En el caso del FileSystemSyncAccessHandle sncrono, los cambios se escriben en un archivo utilizando el mtodo write(). De manera opcional, tambin se puede llamar a flush() si se necesita que los cambios se guarden en el disco en un momento especfico (de lo contrario, se puede dejar que el sistema operativo subyacente se encargue de ello cuando lo considere oportuno, lo que debera funcionar correctamente en la mayora de los casos).

Interfaces

FileSystemChangeRecord

Contiene detalles de un nico cambio observado por un FileSystemObserver.

FileSystemHandle

Un objeto que representa una entrada de archivo o directorio. Varios manejadores pueden representar la misma entrada. En la mayora de los casos, no se trabaja directamente con FileSystemHandle, sino con sus interfaces hijas FileSystemFileHandle y FileSystemDirectoryHandle.

FileSystemFileHandle

Poporciona un manejador para una entrada del sistema de archivos.

FileSystemDirectoryHandle

Poporciona un manejador para un directorio del sistema de archivos.

FileSystemObserver

Proporciona un mecanismo para observar los cambios en los archivos o directorios seleccionados.

FileSystemSyncAccessHandle

Proporciona un manejador sncrono para una entrada del sistema de archivos, que opera in situ en un nico archivo del disco. La naturaleza sncrona de las lecturas y escrituras de archivos permite un mayor rendimiento para mtodos crticos en contextos en los que las operaciones asncronas conllevan una gran sobrecarga, por ejemplo, WebAssembly. Solo se puede acceder a esta clase dentro de Web Workers dedicados para archivos dentro del Sistema de archivos de origen pivado.

FileSystemWritableFileStream

Un objeto WritableStream con mtodos adicionales tiles, que opera sobre un nico archivo en el disco.

Extensiones a otras interfaces

Window.showDirectoryPicker()

Muestra un selector de directorios que permite al usuario seleccionar un directorio.

Window.showOpenFilePicker()

Muestra un selector de archivos que permite al usuario seleccionar uno o varios archivos.

Window.showSaveFilePicker()

Muestra un selector de archivos que permite al usuario guardar un archivo.

DataTransferItem.getAsFileSystemHandle()

Devuelve una Promise que se resuelve con un FileSystemFileHandle si el elemento arrastrado es un archivo, o con un FileSystemDirectoryHandle si el elemento arrastrado es un directorio.

StorageManager.getDirectory()

Se utiliza para obtener una referencia a un objeto FileSystemDirectoryHandle que permite acceder a un directorio y a su contenido, almacenado en el origin private file system. Devuelve una Promise que se resuelve con un objeto FileSystemDirectoryHandle.

Ejemplos

Acceso a archivos

El siguiente cdigo permite al usuario elegir un archivo desde el selector de archivos.

async function getFile() {
  // Abre el selector de archivos y desestructura el resultado del primer manejador
  const [fileHandle] = await window.showOpenFilePicker();
  const file = await fileHandle.getFile();
  return file;
}

La siguiente funcin asncrona presenta un selector de archivos y, una vez elegido el archivo, utiliza el mtodo getFile() para recuperar el contenido.

const pickerOpts = {
  types: [
    {
      description: "Images",
      accept: {
        "image/*": [".png", ".gif", ".jpeg", ".jpg"],
      },
    },
  ],
  excludeAcceptAllOption: true,
  multiple: false,
};

async function getTheFile() {
  // Abre el selector de archivos y desestructura el resultado del primer manejador.
  const [fileHandle] = await window.showOpenFilePicker(pickerOpts);

  // Obtener el contenido del archivo
  const fileData = await fileHandle.getFile();
}

Acceso a directorios

El siguiente ejemplo devuelve un manejador de directorio con el nombre especificado. Si el directorio no existe, este ser creado.

const dirName = "directoryToGetName";

// Suponiendo que tenemos un manejador de directorios: 'currentDirHandle'
const subDir = currentDirHandle.getDirectoryHandle(dirName, { create: true });

La siguiente funcin asncrona utiliza resolve() para encontrar la ruta de un archivo seleccionado, en relacin con un manejador de directorios especificado.

async function returnPathDirectories(directoryHandle) {
  // Obten un manejador de archivos mostrando un selector de archivos.
  const [handle] = await self.showOpenFilePicker();
  if (!handle) {
    // El usuario cancel o no pudo abrir un archivo.
    return;
  }

  // Comprueba si el manejador existe dentro de nuestro manejador de directorios.
  const relativePaths = await directoryHandle.resolve(handle);

  if (relativePaths === null) {
    // No existe dentro del manejador de directorios.
  } else {
    // relativePaths es un arreglo de nombres que proporciona la ruta relativa.

    for (const name of relativePaths) {
      // Registrar cada entrada
      console.log(name);
    }
  }
}

Escribir en archivos

La siguiente funcin asncrona abre el selector de archivos guardados, que devuelve un FileSystemFileHandle una vez seleccionado un archivo. A continuacin, se crea un flujo que puede ser escrito, utilizando el mtodo FileSystemFileHandle.createWritable().

Despus, se escribe un Blob definido por el usuario en el flujo, que posteriormente se cierra.

async function saveFile() {
  // Crear un nuevo manejador
  const newHandle = await window.showSaveFilePicker();

  // Crear un FileSystemWritableFileStream para escribir en l
  const writableStream = await newHandle.createWritable();

  // Escribe nuestro archivo
  await writableStream.write(imgBlob);

  // Cierra el archivo y escribe el contenido en el disco.
  await writableStream.close();
}

A continuacin se muestran diferentes ejemplos de opciones que se pueden pasar al mtodo write().

// Solo pasa los datos (sin opciones)
writableStream.write(data);

// Escribe los datos en el flujo desde la posicin determinada.
writableStream.write({ type: "write", position, data });

// Actualiza el desplazamiento del cursor del archivo a la posicin especificada.
writableStream.write({ type: "seek", position });

// Cambia el tamao del archivo para que su longitud est basada en un determinado nmero de bytes.
writableStream.write({ type: "truncate", size });

Lectura y escritura sncrona de archivos en OPFS

Este ejemplo lee y escribe de forma sncrona un archivo en el Sistema de archivos de origen privado.

La siguiente funcin, que maneja eventos asncronos, est contenida dentro de un Web Worker. Al recibir un mensaje del hilo principal, realiza lo siguiente:

• Crea un manejador sncrono de acceso a archivos.
• Obtiene el tamao del archivo y crea un ArrayBuffer para contenerlo.
• Lee el contenido del archivo dentro del bfer.
• Codifica el mensaje y lo escribe al final del archivo.
• Persiste (guarda) los cambios en el disco y cierra el manejador de acceso.

onmessage = async (e) => {
  // Recuperar el mensaje enviado al trabajo desde el script principal.
  const message = e.data;

  // Obtener manejador para el archivo boceto (borrador) en OPFS.
  const root = await navigator.storage.getDirectory();
  const draftHandle = await root.getFileHandle("draft.txt", { create: true });
  // Obtener manejador de acceso sync (sncrono).
  const accessHandle = await draftHandle.createSyncAccessHandle();

  // Obtener el tamao del archivo.
  const fileSize = accessHandle.getSize();
  // Leer el contenido del archivo en un bfer.
  const buffer = new DataView(new ArrayBuffer(fileSize));
  const readBuffer = accessHandle.read(buffer, { at: 0 });

  // Escribe el mensaje al final del archivo.
  const encoder = new TextEncoder();
  const encodedMessage = encoder.encode(message);
  const writeBuffer = accessHandle.write(encodedMessage, { at: readBuffer });

  // Persistir los cambios en el disco.
  accessHandle.flush();

  // Cerrar siempre FileSystemSyncAccesHandle cuando haya terminado.
  accessHandle.close();
};

Especificaciones

Compatibilidad con navegadores

api.FileSystemHandle

api.FileSystemFileHandle

api.FileSystemDirectoryHandle

api.FileSystemWritableFileStream

api.FileSystemSyncAccessHandle

Vase tambin

• The File System Access API: simplifying access to local files
• The origin private file system