Permitir que aplicativos da Web instalados sejam gerenciadores de arquivos

Registre um app como um gerenciador de arquivos com o sistema operacional.

Thomas Steiner

Agora que os apps da Web podem ler e gravar arquivos, a próxima etapa lógica é permitir que os desenvolvedores declarem esses mesmos apps da Web como processadores de arquivos que eles podem criar e processar. A API File Handling permite fazer exatamente isso. Depois de registrar um app de editor de texto como um gerenciador de arquivos e instalá-lo, clique com o botão direito do mouse em um arquivo .txt no macOS e selecione "Obter informações" 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:

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

Como usar a API File Handling

Aprimoramento progressivo

A API File Handling não pode ser preenchida com polyfill. No entanto, a funcionalidade de abrir arquivos com um web app pode ser alcançada de duas outras maneiras:

• A API Web Share Target permite que os desenvolvedores especifiquem o app como um destino 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 arquivos para que os desenvolvedores possam processar arquivos soltos no app já aberto.

Suporte ao navegador

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

A parte declarativa da API File Handling

Como primeira etapa, os web apps precisam descrever de forma declarativa no manifesto do web app que tipo de arquivos eles podem processar. A API File Handling estende o manifesto do app da Web com uma nova propriedade chamada "file_handlers" que aceita uma matriz de, bem, manipuladores de arquivos. Um manipulador de arquivos é um objeto com estas propriedades:

• Uma propriedade "action" que aponta para um URL no escopo do app como valor.
• 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 mostre um ícone que não é apenas o ícone do aplicativo associado, mas sim um ícone especial relacionado ao uso desse tipo de arquivo com o aplicativo.
• Uma propriedade "launch_type" que define se vários arquivos devem ser abertos em um único cliente ou em vários clientes. O padrão é "single-client". Se o usuário abrir vários arquivos e o manipulador de arquivos tiver sido anotado com "multiple-clients" como "launch_type", mais de uma inicialização de app vai ocorrer. 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, deve deixar isso 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írgula (.csv) em /open-csv, arquivos de gráficos vetoriais escalonáveis (.svg) em /open-svg e um formato de arquivo Grafr inventado com qualquer uma das extensões .grafr, .graf ou .graph em /open-graf. Os dois primeiros vão abrir em um único cliente, e o último em vários clientes se vários arquivos estiverem sendo processados.

A parte imperativa da API File Handling

Agora que o app declarou quais arquivos ele pode processar e em qual URL no escopo, ele precisa fazer algo com os arquivos recebidos na prática. É aí que entra o launchQueue. Para acessar arquivos iniciados, um site precisa especificar um consumidor para o objeto window.launchQueue. Os lançamentos são enfileirados até serem processados pelo consumidor especificado, que é invocado exatamente uma vez para cada lançamento. Dessa forma, todos os lançamentos são processados, não importa 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 do DevTools

No momento da redação deste artigo, não há suporte para o DevTools, mas enviei uma solicitação de recurso para que o suporte seja adicionado.

Demonstração

Adicionei suporte ao processamento de arquivos ao Excalidraw, um app de desenho em estilo de desenho animado. Para testar, primeiro instale o Excalidraw. Quando você cria um arquivo com ele e o armazena em algum lugar no sistema de arquivos, é possível abrir o arquivo com um clique duplo ou um clique com o botão direito do mouse e selecionar "Excalidraw" no menu de contexto. Confira a implementação no código-fonte.

Segurança

A equipe do Chrome projetou e implementou a API File Handling usando os princípios básicos definidos em Controlling Access to Powerful Web Platform Features (em inglês), incluindo controle do usuário, transparência e ergonomia.

Permissões, persistência de permissões e atualizações do manipulador de arquivos

Para garantir a confiança do usuário e a segurança dos arquivos, quando a API File Handling abre um arquivo, uma solicitação de permissão é mostrada antes que um PWA possa acessar o conteúdo. Essa solicitação de permissão será mostrada logo depois que o usuário selecionar o PWA para abrir um arquivo. Assim, a permissão fica fortemente vinculada à ação de abrir um arquivo usando o PWA, o que a torna mais compreensível e relevante.

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

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

Desafios relacionados a arquivos

Há uma grande categoria de vetores de ataque que são abertos ao permitir que os sites acessem arquivos. Elas estão descritas no artigo sobre a API File System Access. A capacidade adicional relacionada à 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 um seletor de arquivos mostrado por um aplicativo da Web.

Ainda há o risco de os usuários concederem acesso a um arquivo a um aplicativo da Web sem querer ao abrir o arquivo. No entanto, geralmente se entende que abrir um arquivo permite que o aplicativo com que ele é aberto leia e/ou manipule esse arquivo. Portanto, a escolha explícita de um 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 do 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 host podem promover automaticamente o novo manipulador registrado para o manipulador padrão desse tipo de arquivo de forma silenciosa e sem 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. Em sistemas operacionais host, quando o user agent determina que não há um gerenciador padrão para o tipo de arquivo, talvez seja necessário um pedido de permissão explícito para evitar o envio acidental do conteúdo de um arquivo a um aplicativo da Web sem o consentimento do usuário.

Controle do usuário

A especificação afirma que os navegadores não devem registrar todos os sites que podem processar arquivos como um manipulador de arquivos. Em vez disso, o registro de processamento de arquivos precisa ser controlado por instalação e nunca acontecer sem confirmação explícita do usuário, principalmente se um site se tornar o gerenciador padrão. Em vez de sequestrar extensões atuais, como .json, para as quais o usuário provavelmente já tem um manipulador padrão registrado, os sites devem considerar a criação das próprias extensões.

Transparência

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

Feedback

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

Fale sobre o design da API

Há algo na API que não funciona como esperado? Ou há métodos ou propriedades ausentes que você precisa implementar sua ideia? Tem uma dúvida ou um 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.

Mostrar suporte à API

Você planeja usar a API File Handling? Seu apoio público ajuda a equipe do Chrome a priorizar recursos e mostra a outros fornecedores de navegadores a importância de oferecer suporte a eles.

• Compartilhe como você planeja usar isso na thread do WICG Discourse.
• Envie um tweet para @ChromiumDev usando a hashtag #FileHandling e diga onde e como você está usando.

Links úteis

• Explicação para o público
• Demonstração da API File Handling | Fonte da demonstração da API File Handling
• Bug de rastreamento do Chromium
• Entrada do ChromeStatus.com
• Componente Blink: UI>Browser>WebAppInstalls>FileHandling
• Análise da TAG
• Posição da Mozilla sobre padrões

Agradecimentos

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