Permitir que aplicativos da Web instalados sejam gerenciadores de arquivos

Registrar um app como gerenciador de arquivos no sistema operacional.

Thomas Steiner

Agora que os apps da Web são capazes de ler e gravar arquivos, a próxima etapa lógica é permitir que os desenvolvedores declarem esses apps da Web como gerenciadores de arquivos que os apps podem criar e processar. A API File Handling permite que você faça exatamente isso. Depois de registrar um app de editor de texto como gerenciador de arquivos e instalá-lo, clique com o botão direito do mouse em um arquivo .txt no macOS e selecione "Get Info" para instruir o SO a sempre abrir arquivos .txt com esse app como padrão.

Casos de uso sugeridos para a API File Handling

Exemplos de sites que podem usar essa API incluem:

• Aplicativos do Office, como editores de texto, apps de planilhas e criadores de apresentações de slides.
• Editores gráficos e ferramentas de desenho
• Ferramentas de edição de níveis de videogame.

Como usar a API File Handling

Aprimoramento progressivo

A API File Handling por si só não pode ter polyfill aplicado. No entanto, há dois outros meios para abrir arquivos com um app da Web:

• A API Web Share Target permite que os desenvolvedores especifiquem o app como um alvo de compartilhamento para que os arquivos possam ser abertos na página de compartilhamento do sistema operacional.
• A API File System Access pode ser integrada ao recurso de arrastar e soltar para que os desenvolvedores possam processar arquivos soltos no app já aberto.

Suporte ao navegador

Compatibilidade com navegadores

• 102
• 102
• x
• x

Origem

Detecção de recursos

Para verificar se a API File Handling é compatível, use:

if ('launchQueue' in window && 'files' in LaunchParams.prototype) {
  // The File Handling API is supported.
}

Observação:no momento, o gerenciamento de arquivos está limitado aos sistemas operacionais de computadores.

A parte declarativa da API File Handling

Para começar, os apps da Web precisam descrever de maneira declarativa no manifesto do app da Web os tipos de arquivos que podem ser processados. A API File Handling estende o manifesto do app da Web com uma nova propriedade chamada "file_handlers", que aceita uma matriz de gerenciadores de arquivos. Um gerenciador de arquivos é um objeto com estas propriedades:

• Uma propriedade "action" que aponta para um URL dentro do escopo do app como o valor dele.
• Uma propriedade "accept" com um objeto de tipos MIME como chaves e listas de extensões de arquivo como valores.
• Uma propriedade "icons" com uma matriz de ícones ImageResource. Alguns sistemas operacionais permitem que uma associação de tipo de arquivo exiba um ícone que não é apenas o do aplicativo associado, mas um ícone especial relacionado ao uso desse tipo de arquivo com o aplicativo.
• Uma propriedade "launch_type" que define se vários arquivos precisam ser abertos em um único cliente ou em vários. O padrão é "single-client". Se o usuário abrir vários arquivos e se o gerenciador tiver a anotação "multiple-clients" como "launch_type", mais de uma inicialização do app vai ocorrer e, para cada inicialização, a matriz LaunchParams.files (consulte Mais abaixo) terá apenas um elemento.

O exemplo abaixo, que mostra apenas o trecho relevante do manifesto do app da Web, deixa o processo mais 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"
    }
  ]
}

Isso é para um aplicativo hipotético que processa arquivos de valores separados por vírgulas (.csv) em /open-csv, arquivos de gráficos vetoriais escalonáveis (.svg) em /open-svg e um formato de arquivo Grafr com qualquer .grafr, .graf ou .graph como a extensão em /open-graf. Os dois primeiros serão abertos em um único cliente, e o último em vários clientes se vários arquivos estiverem sendo processados.

Observação:para que essa declaração tenha efeito, o aplicativo precisa estar instalado. Para saber mais, consulte uma série de artigos neste site sobre como tornar seu app instalável.

A parte imperativa da API File Handling

Agora que o app declarou, na prática, quais arquivos pode processar com qual URL no escopo, ele precisa fazer algo imperativamente com os arquivos recebidos. É aqui que a launchQueue entra em jogo. Para acessar os arquivos iniciados, um site precisa especificar um consumidor para o objeto window.launchQueue. As inicializações são enfileiradas até serem processadas pelo consumidor especificado, que é invocado exatamente uma vez para cada inicialização. Dessa forma, todos os lançamentos são processados, independente de quando o consumidor foi especificado.

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.
    }
  });
}

Suporte ao DevTools

Não há suporte para DevTools no momento em que este artigo foi escrito, mas enviei uma solicitação de recurso para que o suporte seja adicionado.

Demonstração

Adicionei suporte ao processamento de arquivos para o Excalidraw, um app de desenho em estilo desenho animado. Para testá-lo, primeiro você precisa instalar o Excalidraw. Depois de criar um arquivo com ele e armazená-lo em algum lugar no sistema de arquivos, você pode abri-lo com um clique duplo ou com o botão direito do mouse e selecionar "Excalidraw" no menu de contexto. Confira a implementação no código-fonte.

Clique duas vezes ou clique com o botão direito do mouse em um arquivo no explorador de arquivos do sistema operacional.

O Excalidraw é o gerenciador padrão de arquivos .excalidraw.

Segurança

A equipe do Chrome projetou e implementou a API File Handling usando os princípios definidos em Como controlar o acesso a recursos avançados da plataforma Web, incluindo controle do usuário, transparência e ergonomia.

Permissões, persistência de permissões e atualizações no gerenciador de arquivos

Para garantir a confiança do usuário e a segurança dos arquivos dos usuários, quando a API File Handling abrir um arquivo, um pedido de permissão será exibido antes que um PWA possa visualizar um arquivo. Essa solicitação de permissão será exibida logo depois que o usuário selecionar o PWA para abrir um arquivo, para que a permissão esteja estreitamente associada à ação de abrir um arquivo usando o PWA, o que o torna mais compreensível e relevante.

Essa permissão será mostrada todas as vezes até que o usuário clique em Permitir ou Bloquear o processamento de arquivos para o site ou ignore a solicitação três vezes. Depois disso, o Chromium vai embargar e bloquear essa permissão. A configuração selecionada será mantida no fechamento e reabertura do PWA.

Quando as atualizações e mudanças do manifesto na seção "file_handlers" forem detectadas, as permissões serão redefinidas.

Desafios relacionados a arquivos

Existe uma grande categoria de vetores de ataque que são abertos ao permitir que os sites acessem os arquivos. Eles são descritos no artigo sobre a API File System Access. O recurso extra de segurança que a API File Handling oferece em relação à API File System Access é a capacidade de conceder acesso a determinados arquivos pela interface integrada do sistema operacional, em vez de por um seletor de arquivos mostrado por um app da Web.

Ainda há o risco de que os usuários concedam acidentalmente a um aplicativo da Web acesso a um arquivo abrindo-o. No entanto, geralmente entende-se que abrir um arquivo permite que o aplicativo com o qual ele é aberto leia e/ou manipule esse arquivo. Portanto, a escolha explícita do usuário de abrir um arquivo em um aplicativo instalado, como em um menu de contexto "Abrir com...", pode ser lida como um sinal suficiente de confiança no aplicativo.

Desafios de gerenciador padrão

A exceção é quando não há aplicativos no sistema host para um determinado tipo de arquivo. Nesse caso, alguns sistemas operacionais de host podem promover automaticamente o gerenciador recém-registrado para o gerenciador padrão para esse tipo de arquivo de forma silenciosa e sem qualquer intervenção do usuário. Isso significa que, se o usuário clicar duas vezes em um arquivo desse tipo, ele será aberto automaticamente no app da Web registrado. Nesses sistemas operacionais host, quando o user agent determina que não há um gerenciador padrão para o tipo de arquivo, um prompt de permissão explícita pode ser necessário para evitar o envio acidental do conteúdo de um arquivo para um aplicativo da Web sem o consentimento do usuário.

Controle do usuário

A especificação afirma que os navegadores não precisam registrar todos os sites que podem processar arquivos como um gerenciador de arquivos. Em vez disso, o registro de processamento de arquivos precisa ser protegido pela instalação e nunca acontecerá sem a confirmação explícita do usuário, especialmente se um site se tornar o gerenciador padrão. Em vez de invadir extensões como .json, para as quais o usuário provavelmente já tem um gerenciador padrão registrado, os sites precisam criar as próprias extensões.

Transparência

Todos os sistemas operacionais permitem que os usuários alterem as associações de arquivos atuais. Isso está fora do escopo do navegador.

Feedback

A equipe do Chrome quer saber mais sobre suas experiências com a API File Handling.

Fale sobre o design da API

Algo na API não funciona como você esperava? Ou há métodos ou propriedades ausentes que você precisa para implementar sua ideia? Tem alguma dúvida ou comentário sobre o modelo de segurança?

• Registre um problema de especificação no repositório do GitHub correspondente ou adicione suas ideias a um problema existente.

Informar um problema com a implementação

Você encontrou um bug na implementação do Chrome? Ou a implementação é diferente da especificação?

• Registre um bug em new.crbug.com. Inclua o máximo de detalhes possível, instruções simples para reprodução e insira UI>Browser>WebAppInstalls>FileHandling na caixa Componentes. O Glitch funciona muito bem para compartilhar repetições rápidas e fáceis.

Mostrar suporte à API

Você planeja usar a API File Handling? Seu suporte público ajuda a equipe do Chrome a priorizar recursos e mostra a outros fornecedores de navegador como é importante oferecer suporte a eles.

• Conte como você planeja usá-lo na conversa do discurso do WICG (em inglês).
• Envie um tweet para @ChromiumDev usando a hashtag #FileHandling e informe onde e como você está usando a ferramenta.

Links úteis

• Explicações públicas
• Demonstração da API de processamento de arquivos | Fonte da demonstração da API de processamento de arquivos
• Bug de rastreamento do Chromium
• Entrada ChromeStatus.com
• Componente Blink: UI>Browser>WebAppInstalls>FileHandling
• Análise da TAG
• Posição dos Padrões do Mozilla (em inglês)

Agradecimentos

A API File Handling foi especificada por Eric Willigers, Jay Harris e Raymes Khoury. Este artigo foi revisado por Joe Medley.