API de File System Access: Simplificación del acceso a archivos locales

La API de File System Access permite que las apps web lean o guarden cambios directamente en archivos y carpetas del dispositivo del usuario.

Pete LePage

Thomas Steiner

Publicado: 19 de agosto de 2024

La API de File System Access permite a los desarrolladores compilar potentes apps web que interactúan con archivos en el dispositivo local del usuario, como IDE, editores de fotos y videos, editores de texto y mucho más. Después de que un usuario otorga acceso a una app web, esta API le permite leer o guardar cambios directamente en archivos y carpetas del dispositivo del usuario. Además de leer y escribir archivos, la API de File System Access permite abrir un directorio y enumerar su contenido.

Si ya trabajaste con la lectura y escritura de archivos, gran parte de lo que estoy a punto de compartir te resultará familiar. De todos modos, te recomiendo que lo leas, ya que no todos los sistemas son iguales.

La API de File System Access es compatible con la mayoría de los navegadores Chromium en Windows, macOS, ChromeOS, Linux y Android. Una excepción notable es Brave, donde actualmente solo está disponible detrás de una marca.

Cómo usar la API de File System Access

Para mostrar el poder y la utilidad de la API de File System Access, escribí un editor de texto de un solo archivo. Te permite abrir un archivo de texto, editarlo, guardar los cambios en el disco o iniciar un archivo nuevo y guardar los cambios en el disco. No es nada sofisticado, pero proporciona suficiente información para ayudarte a comprender los conceptos.

Navegadores compatibles

Detección de características

Para saber si se admite la API de File System Access, verifica si existe el método del selector que te interesa.

if ('showOpenFilePicker' in self) {
  // The `showOpenFilePicker()` method of the File System Access API is supported.
}

Probar

Observa la API de File System Access en acción en la demostración del editor de texto.

Leer un archivo del sistema de archivos local

El primer caso de uso que quiero abordar es pedirle al usuario que elija un archivo y, luego, abrir y leer ese archivo desde el disco.

Pedirle al usuario que elija un archivo para leer

El punto de entrada a la API de File System Access es window.showOpenFilePicker(). Cuando se llama, muestra un diálogo de selección de archivos y le solicita al usuario que seleccione uno. Después de que el usuario selecciona un archivo, la API devuelve un array de identificadores de archivos. Un parámetro options opcional te permite influir en el comportamiento del selector de archivos, por ejemplo, permitiendo que el usuario seleccione varios archivos, directorios o diferentes tipos de archivos. Sin opciones especificadas, el selector de archivos permite que el usuario seleccione un solo archivo. Esto es perfecto para un editor de texto.

Al igual que muchas otras APIs potentes, la llamada a showOpenFilePicker() debe realizarse en un contexto seguro y desde un gesto del usuario.

let fileHandle;
butOpenFile.addEventListener('click', async () => {
  // Destructure the one-element array.
  [fileHandle] = await window.showOpenFilePicker();
  // Do something with the file handle.
});

Una vez que el usuario selecciona un archivo, showOpenFilePicker() devuelve un array de identificadores, en este caso, un array de un solo elemento con un FileSystemFileHandle que contiene las propiedades y los métodos necesarios para interactuar con el archivo.

Es útil mantener una referencia al identificador de archivo para que se pueda usar más adelante. Será necesario para guardar los cambios en el archivo o realizar cualquier otra operación con el archivo.

Cómo leer un archivo del sistema de archivos

Ahora que tienes un identificador de un archivo, puedes obtener sus propiedades o acceder al archivo en sí. Por ahora, leeré su contenido. La llamada a handle.getFile() devuelve un objeto File, que contiene un BLOB. Para obtener los datos del blob, llama a uno de sus métodos (slice(), stream(), text() o arrayBuffer()).

const file = await fileHandle.getFile();
const contents = await file.text();

El objeto File que devuelve FileSystemFileHandle.getFile() solo se puede leer mientras no cambie el archivo subyacente en el disco. Si se modifica el archivo en el disco, el objeto File se vuelve ilegible y deberás volver a llamar a getFile() para obtener un nuevo objeto File y leer los datos modificados.

Revisión general

Cuando los usuarios hacen clic en el botón Abrir, el navegador muestra un selector de archivos. Una vez que seleccionan un archivo, la app lee el contenido y lo coloca en un <textarea>.

let fileHandle;
butOpenFile.addEventListener('click', async () => {
  [fileHandle] = await window.showOpenFilePicker();
  const file = await fileHandle.getFile();