Registra una app como controlador de archivos con el sistema operativo.
Ahora que las apps web pueden leer y escribir archivos, el siguiente paso lógico es permitir que los desarrolladores declaren estas apps web como controladores de los archivos que sus apps pueden crear y procesar. La API de File Handling te permite hacer exactamente esto. Después de registrar una app de edición de texto como controlador de archivos y después de instalarla, puedes hacer clic con el botón derecho en un archivo .txt
en macOS y seleccionar "Obtener información" para indicarle al SO que siempre debe abrir los archivos .txt
con esta app de forma predeterminada.
Casos de uso sugeridos para la API de File Handling
Estos son algunos ejemplos de sitios que pueden usar esta API:
- Aplicaciones de oficina, como editores de texto, aplicaciones de hojas de cálculo y creadores de presentaciones de diapositivas
- Editores de gráficos y herramientas de dibujo
- Herramientas del editor de niveles de videojuegos
Cómo usar la API de File Handling
Mejora progresiva
La API de File Handling no puede tener polyfills. Sin embargo, la funcionalidad de abrir archivos con una app web se puede lograr a través de otros dos medios:
- La API de Web Share Target permite a los desarrolladores especificar sus apps como un objetivo de uso compartido para que los archivos se puedan abrir desde la hoja para compartir del sistema operativo.
- La API de File System Access se puede integrar con la función de arrastrar y soltar archivos, para que los desarrolladores puedan controlar los archivos soltados en la app ya abierta.
Navegadores compatibles
Detección de funciones
Para comprobar si la API de File Handling es compatible, utiliza lo siguiente:
if ('launchQueue' in window && 'files' in LaunchParams.prototype) {
// The File Handling API is supported.
}
La parte declarativa de la API de File Handling
Como primer paso, las aplicaciones web deben describir de forma declarativa en su manifiesto de aplicaciones web qué tipo de archivos pueden controlar. La API de File Handling extiende el manifiesto de la app web con una propiedad nueva llamada "file_handlers"
que acepta un array de controladores de archivos. Un controlador de archivos es un objeto con las siguientes propiedades:
- Una propiedad
"action"
que apunta a una URL dentro del alcance de la app como su valor. - Una propiedad
"accept"
con un objeto de tipos de MIME como claves y listas de extensiones de archivo como sus valores. - Una propiedad
"icons"
con un array de íconosImageResource
Algunos sistemas operativos permiten que una asociación de tipo de archivo muestre un ícono que no es solo el ícono de la aplicación asociado, sino un ícono especial relacionado con el uso de ese tipo de archivo con la aplicación. - Una propiedad
"launch_type"
que define si se deben abrir varios archivos en un solo cliente o en varios clientes. El valor predeterminado es"single-client"
. Si el usuario abre varios archivos y se anotó el controlador de archivos con"multiple-clients"
como su"launch_type"
, se iniciará más de una app. Por cada inicio, el arrayLaunchParams.files
(consulta más abajo) solo tendrá un elemento.
En el siguiente ejemplo, que muestra solo el extracto relevante del manifiesto de la app web, debería ser más claro:
{
"file_handlers": [
{
"action": "/open-csv",
"accept": {
"text/csv": [".csv"]
},
"icons": [
{
"src": "csv-icon.png",
"sizes": "256x256",
"type": "image/png"
}
],
"launch_type": "single-client"
},
{
"action": "/open-svg",
"accept": {
"image/svg+xml": ".svg"
},
"icons": [
{
"src": "svg-icon.png",
"sizes": "256x256",
"type": "image/png"
}
],
"launch_type": "single-client"
},
{
"action": "/open-graf",
"accept": {
"application/vnd.grafr.graph": [".grafr", ".graf"],
"application/vnd.alternative-graph-app.graph": ".graph"
},
"icons": [
{
"src": "graf-icon.png",
"sizes": "256x256",
"type": "image/png"
}
],
"launch_type": "multiple-clients"
}
]
}
Este es el caso de una aplicación hipotética que controla archivos de valores separados por comas (.csv
) en /open-csv
, archivos de gráficos vectoriales escalables (.svg
) en /open-svg
y un formato de archivo Grafr inventado con .grafr
, .graf
o .graph
como la extensión en /open-graf
. Los dos primeros se abrirán en un solo cliente y el último en varios clientes si se controlan varios archivos.
La parte imperativa de la API de File Handling
Ahora que, en teoría, la app declaró qué archivos puede controlar y en qué URL dentro del alcance, en la práctica, debe hacer algo con los archivos entrantes de forma imperativa. Aquí es donde launchQueue
entra en juego. Para acceder a los archivos que se iniciaron, un sitio debe especificar un consumidor para el objeto window.launchQueue
. Los lanzamientos se ponen en cola hasta que los maneja el consumidor especificado, que se invoca exactamente una vez por cada inicio. De esta manera, se controla cada lanzamiento, sin importar cuándo se especificó el consumidor.
if ('launchQueue' in window && 'files' in LaunchParams.prototype) {
launchQueue.setConsumer((launchParams) => {
// Nothing to do when the queue is empty.
if (!launchParams.files.length) {
return;
}
for (const fileHandle of launchParams.files) {
// Handle the file.
}
});
}
Asistencia para Herramientas para desarrolladores
En el momento de la redacción de este documento, no se ofrece asistencia para Herramientas para desarrolladores, pero envié una solicitud de función para que se agregue asistencia.
Demostración
Se agregó compatibilidad con el control de archivos a Excalidraw, una app de dibujo con estilo de dibujos animados. Para probarlo, primero debes instalar Excalidraw. Cuando creas un archivo con él y lo almacenas en algún lugar de tu sistema de archivos, puedes abrirlo haciendo doble clic o haciendo clic con el botón derecho y, luego, seleccionar "Excalidraw" en el menú contextual. Puedes verificar la implementación en el código fuente.
![Ventana del buscador de macOS con un archivo Excalidraw](https://developer.chrome.com/static/docs/capabilities/web-apis/file-handling/image/the-macos-finder-window-eac9df1131965.png?authuser=7&hl=es)
![El menú contextual que aparece cuando se hace clic con el botón derecho en un archivo con el elemento Abrir con... Excalidraw destacado.](https://developer.chrome.com/static/docs/capabilities/web-apis/file-handling/image/the-context-menu-appears-76d8a48d9d84e.png?authuser=7&hl=es)
.excalidraw
.
Seguridad
El equipo de Chrome diseñó e implementó la API de File Handling según los principios básicos definidos en Cómo controlar el acceso a funciones potentes de la plataforma web, incluidos el control de usuario, la transparencia y la ergonomía.
Permisos, persistencia de permisos y actualizaciones del controlador de archivos
Para garantizar la confianza del usuario y la seguridad de sus archivos, cuando la API de File Handling abra un archivo, se mostrará un mensaje de permiso antes de que la AWP pueda ver el archivo. Esta solicitud de permiso se mostrará justo después de que el usuario seleccione la AWP para abrir un archivo, de modo que el permiso esté estrechamente vinculado a la acción de abrir un archivo con la AWP, lo que lo hará más comprensible y relevante.
Este permiso se mostrará cada vez que el usuario haga clic en Permitir o Bloquear el manejo de archivos para el sitio, o hasta que ignore la solicitud tres veces (luego de eso, Chromium embargará y bloqueará este permiso). El parámetro de configuración seleccionado se mantendrá durante el cierre y la reapertura de la AWP.
Cuando se detecten actualizaciones del manifiesto y cambios en la sección "file_handlers"
, se restablecerán los permisos.
Desafíos relacionados con los archivos
Existe una gran categoría de vectores de ataque que se abren permitiendo que los sitios web accedan a los archivos. Estos se describen en el artículo sobre la API de File System Access. La capacidad adicional pertinente que brinda la API de File Handling con respecto a la API de File System Access es la capacidad de otorgar acceso a ciertos archivos a través de la IU integrada del sistema operativo, en lugar de hacerlo a través de un selector de archivos que muestra una aplicación web.
Aún existe el riesgo de que los usuarios lo abran y otorguen acceso involuntario a una aplicación web a un archivo. Sin embargo, se entiende que abrir un archivo permite que la aplicación con el que se abre lea o manipule ese archivo. Por lo tanto, la elección explícita de un usuario de abrir un archivo en una aplicación instalada, por ejemplo, a través de un menú contextual "Abrir con...", se puede leer como una señal suficiente de confianza en la aplicación.
Desafíos del controlador predeterminado
La excepción se da cuando no hay aplicaciones en el sistema host para un tipo de archivo determinado. En este caso, algunos sistemas operativos de host pueden ascender automáticamente el controlador recién registrado al controlador predeterminado para ese tipo de archivo de forma silenciosa y sin ninguna intervención del usuario. Esto significa que, si el usuario hace doble clic en un archivo de ese tipo, este se abrirá automáticamente en la app web registrada. En esos sistemas operativos de host, cuando el usuario-agente determina que no existe un controlador predeterminado para el tipo de archivo, podría ser necesario enviar una solicitud de permiso explícita a fin de evitar que se envíe accidentalmente el contenido de un archivo a una aplicación web sin el consentimiento del usuario.
Control de usuarios
La especificación establece que los navegadores no deben registrar todos los sitios que puedan manejar archivos como controladores. En cambio, el registro de manejo de archivos debe restringirse tras la instalación y nunca debe realizarse sin la confirmación explícita del usuario, en especial si un sitio se convertirá en el controlador predeterminado. En lugar
de piratear extensiones existentes como .json
, en las que el usuario probablemente ya tiene un controlador predeterminado
registrado, los sitios deben crear sus propias extensiones.
Transparencia
Todos los sistemas operativos permiten que los usuarios cambien las asociaciones de archivos actuales. Esto está fuera del alcance del navegador.
Comentarios
El equipo de Chrome quiere conocer tu experiencia con la API de File Handling.
Cuéntanos sobre el diseño de la API
¿Hay algo acerca de la API que no funciona como esperabas? ¿O faltan métodos o propiedades que necesitas para implementar tu idea? ¿Tienes alguna pregunta o comentario sobre el modelo de seguridad?
- Informa un problema de especificaciones en el repositorio de GitHub correspondiente o agrega tus ideas a un problema existente.
Informar un problema con la implementación
¿Encontraste un error en la implementación de Chrome? ¿O la implementación es diferente de la especificación?
- Informa un error en new.crbug.com. Asegúrate de incluir tantos detalles como puedas, además de instrucciones simples para reproducir el contenido, y, luego, ingresa
UI>Browser>WebAppInstalls>FileHandling
en el cuadro Componentes. Glitch funciona muy bien para compartir reproducciones rápidas y fáciles.
Muestra compatibilidad con la API
¿Planeas usar la API de File Handling? Tu asistencia pública ayuda al equipo de Chrome a priorizar funciones y le muestra a otros proveedores de navegadores la importancia de brindar compatibilidad.
- Comparte cómo planeas usarlo en la conversación del discurso de WICG.
- Envía un tweet a @ChromiumDev con el hashtag
#FileHandling
y cuéntanos dónde y cómo lo usas.
Vínculos útiles
- Explicación pública
- Demostración de la API de File Handling | Fuente de demostración de la API de File Handling
- Error de seguimiento de Chromium
- Entrada de ChromeStatus.com
- Componente de Blink:
UI>Browser>WebAppInstalls>FileHandling
- Revisión de la etiqueta
- Posición de los estándares de Mozilla
Agradecimientos
Eric Willigers, Jay Harris y Raymes Khoury especificaron la API de File Handling. Joe Medley revisó este artículo.