Pozwól zainstalowanym aplikacjom internetowym modułami obsługi plików

Zarejestruj aplikację jako obsługującą pliki w systemie operacyjnym.

Thomas Steiner

Teraz, gdy aplikacje internetowe mogą odczytywać i zapisywać pliki, kolejnym logicznym krokiem jest umożliwienie deweloperom deklarowania tych aplikacji jako programów obsługi plików, które mogą tworzyć i przetwarzać. Interfejs File Handling API umożliwia właśnie takie działanie. Po zarejestrowaniu aplikacji do edycji tekstu jako programu obsługującego pliki i po jej zainstalowaniu możesz kliknąć prawym przyciskiem myszy plik .txt w systemie macOS i wybrać „Pobierz informacje”, aby poinstruować system operacyjny, że pliki .txt mają być zawsze otwierane w tej aplikacji jako domyślnej.

Zalecane przypadki użycia interfejsu File Handling API

Przykłady witryn, które mogą korzystać z tego interfejsu API:

aplikacje biurowe, takie jak edytory tekstu, arkusze kalkulacyjne i programy do tworzenia prezentacji;
edytory grafiki i narzędzia do rysowania,
Narzędzia do edycji poziomów gier wideo.

Jak korzystać z interfejsu File Handling API

Stopniowe ulepszanie

Interfejs File Handling API nie może być polyfillowany. Funkcję otwierania plików za pomocą aplikacji internetowej można jednak uzyskać na 2 inne sposoby:

Web Share Target API umożliwia deweloperom określenie aplikacji jako miejsca docelowego udostępniania, dzięki czemu pliki można otwierać z arkusza udostępniania systemu operacyjnego.
Interfejs File System Access API można zintegrować z przeciąganiem i upuszczaniem plików, dzięki czemu deweloperzy mogą obsługiwać upuszczone pliki w już otwartej aplikacji.

Obsługa przeglądarek

Browser Support

Source

Wykrywanie cech

Aby sprawdzić, czy interfejs File Handling API jest obsługiwany, użyj tego kodu:

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

Deklaratywna część interfejsu File Handling API

W pierwszej kolejności aplikacje internetowe muszą deklaratywnie opisać w pliku manifestu aplikacji internetowej, jakie typy plików mogą obsługiwać. Interfejs File Handling API rozszerza manifest aplikacji internetowej o nową właściwość o nazwie "file_handlers", która akceptuje tablicę modułów obsługi plików. Obsługa plików to obiekt o tych właściwościach:

Właściwość "action", która jako wartość wskazuje adres URL w zakresie aplikacji.
Właściwość "accept" z obiektem typów MIME jako kluczami i listami rozszerzeń plików jako wartościami.
Właściwość "icons" z tablicą ikon ImageResource. Niektóre systemy operacyjne umożliwiają wyświetlanie ikony skojarzonej z typem pliku, która nie jest tylko ikoną powiązanej aplikacji, ale specjalną ikoną związaną z używaniem tego typu pliku w aplikacji.
Właściwość "launch_type", która określa, czy wiele plików ma być otwieranych w jednym czy w wielu klientach. Wartość domyślna to "single-client". Jeśli użytkownik otworzy wiele plików, a obsługa plików została oznaczona adnotacją "multiple-clients" jako "launch_type", uruchomionych zostanie więcej niż 1 aplikacja, a w przypadku każdego uruchomienia tablica LaunchParams.files (więcej informacji znajdziesz poniżej) będzie zawierać tylko 1 element.

Przykład poniżej, który zawiera tylko odpowiedni fragment manifestu aplikacji internetowej, powinien to wyjaśnić:

{
  "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"
    }
  ]
}

Dotyczy to hipotetycznej aplikacji, która obsługuje pliki wartości rozdzielonych przecinkami (.csv) w lokalizacji /open-csv, pliki grafiki wektorowej (.svg) w lokalizacji /open-svg oraz wymyślony format pliku Grafr z dowolnym rozszerzeniem .grafr, .graf lub .graph w lokalizacji /open-graf. Pierwsze 2 otworzą się w jednym kliencie, a ostatni w kilku klientach, jeśli obsługiwanych jest wiele plików.

Część imperatywna interfejsu File Handling API

Aplikacja zadeklarowała już, które pliki może obsługiwać w ramach danego adresu URL. Teraz musi w praktyce coś zrobić z przychodzącymi plikami. W tym momencie przydaje się launchQueue. Aby uzyskać dostęp do uruchomionych plików, witryna musi określić odbiorcę obiektu window.launchQueue. Uruchomienia są umieszczane w kolejce, dopóki nie zostaną obsłużone przez określonego odbiorcę, który jest wywoływany dokładnie raz dla każdego uruchomienia. W ten sposób obsługiwane jest każde uruchomienie, niezależnie od tego, kiedy określono konsumenta.

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

Obsługa Narzędzi deweloperskich

W momencie pisania tego artykułu narzędzia deweloperskie nie są obsługiwane, ale przesłałem prośbę o dodanie tej funkcji.

Prezentacja

Dodałem obsługę plików do Excalidraw, aplikacji do rysowania w stylu kreskówkowym. Aby ją przetestować, musisz najpierw zainstalować Excalidraw. Gdy utworzysz plik i zapiszesz go w systemie plików, możesz go otworzyć, klikając go dwukrotnie lub klikając go prawym przyciskiem myszy i wybierając „Excalidraw” w menu kontekstowym. Implementację możesz sprawdzić w kodzie źródłowym.

Okno Findera w systemie macOS z plikiem Excalidraw. — Kliknij dwukrotnie lub prawym przyciskiem myszy plik w eksploratorze plików systemu operacyjnego.

Menu kontekstowe, które pojawia się po kliknięciu prawym przyciskiem myszy pliku z zaznaczoną pozycją Otwórz za pomocą… Excalidraw. — Excalidraw jest domyślnym modułem obsługi plików `.excalidraw`.

Bezpieczeństwo

Zespół Chrome zaprojektował i wdrożył interfejs File Handling API zgodnie z głównymi zasadami określonymi w artykule Kontrolowanie dostępu do zaawansowanych funkcji platformy internetowej, w tym kontrolą użytkownika, przejrzystością i ergonomią.

Uprawnienia, trwałość uprawnień i aktualizacje modułu obsługi plików

Aby zapewnić użytkownikom zaufanie i bezpieczeństwo ich plików, gdy interfejs File Handling API otwiera plik, przed wyświetleniem pliku przez PWA pojawi się prośba o uprawnienia. Prośba o to uprawnienie będzie wyświetlana bezpośrednio po tym, jak użytkownik wybierze aplikację PWA, aby otworzyć plik. Dzięki temu uprawnienie będzie ściśle powiązane z czynnością otwierania pliku za pomocą aplikacji PWA, co sprawi, że będzie bardziej zrozumiałe i trafne.

Ten komunikat będzie się wyświetlać za każdym razem, dopóki użytkownik nie kliknie Zezwól lub Zablokuj obsługę plików w witrynie albo nie zignoruje go 3 razy (po czym Chromium zablokuje to uprawnienie). Wybrane ustawienie będzie obowiązywać po zamknięciu i ponownym otwarciu progresywnej aplikacji internetowej.

Gdy zostaną wykryte aktualizacje pliku manifestu i zmiany w sekcji "file_handlers", uprawnienia zostaną zresetowane.

Problemy związane z plikami

Istnieje duża kategoria wektorów ataku, które są otwierane przez zezwolenie witrynom na dostęp do plików. Są one opisane w artykule na temat interfejsu File System Access API. Dodatkową funkcją związaną z bezpieczeństwem, którą interfejs File Handling API udostępnia w porównaniu z interfejsem File System Access API, jest możliwość przyznawania dostępu do określonych plików za pomocą wbudowanego interfejsu systemu operacyjnego, a nie za pomocą selektora plików wyświetlanego przez aplikację internetową.

Istnieje ryzyko, że użytkownicy mogą nieumyślnie przyznać aplikacji internetowej dostęp do pliku, otwierając go. Ogólnie jednak przyjmuje się, że otwarcie pliku umożliwia aplikacji, w której został on otwarty, odczytanie lub zmodyfikowanie tego pliku. Dlatego wyraźny wybór użytkownika, aby otworzyć plik w zainstalowanej aplikacji, np. za pomocą menu kontekstowego „Otwórz za pomocą…”, można odczytać jako wystarczający sygnał zaufania do aplikacji.

Testy zabezpieczające dla domyślnego modułu obsługi

Wyjątkiem jest sytuacja, gdy w systemie hosta nie ma aplikacji dla danego typu pliku. W takim przypadku niektóre systemy operacyjne hosta mogą automatycznie promować nowo zarejestrowany moduł obsługi na domyślny moduł obsługi tego typu pliku bez interwencji użytkownika. Oznacza to, że jeśli użytkownik kliknie dwukrotnie plik tego typu, zostanie on automatycznie otwarty w zarejestrowanej aplikacji internetowej. W takich systemach operacyjnych hosta, gdy agent użytkownika stwierdzi, że nie ma domyślnego modułu obsługi tego typu pliku, może być konieczne wyświetlenie wyraźnego monitu o uprawnienia, aby uniknąć przypadkowego wysłania zawartości pliku do aplikacji internetowej bez zgody użytkownika.

Kontrola sprawowana przez użytkowników

Specyfikacja mówi, że przeglądarki nie powinny rejestrować każdej witryny, która może obsługiwać pliki, jako obsługującej pliki. Zamiast tego rejestracja obsługi plików powinna być ograniczona do instalacji i nigdy nie powinna następować bez wyraźnego potwierdzenia użytkownika, zwłaszcza jeśli witryna ma stać się domyślną aplikacją do obsługi. Zamiast przejmować istniejące rozszerzenia, takie jak .json, dla których użytkownik prawdopodobnie ma już zarejestrowany domyślny moduł obsługi, witryny powinny rozważyć tworzenie własnych rozszerzeń.

Przejrzystość

Wszystkie systemy operacyjne umożliwiają użytkownikom zmianę bieżących powiązań plików. To wykracza poza zakres przeglądarki.

Prześlij opinię

Zespół Chrome chce poznać Twoje wrażenia związane z korzystaniem z interfejsu File Handling API.

Opisz projekt interfejsu API

Czy w API jest coś, co nie działa tak, jak oczekujesz? Czy brakuje metod lub właściwości, które są potrzebne do realizacji Twojego pomysłu? Masz pytania lub uwagi dotyczące modelu zabezpieczeń?

Zgłoś problem ze specyfikacją w odpowiednim repozytorium GitHub lub dodaj swoje uwagi do istniejącego problemu.

Zgłaszanie problemu z implementacją

Czy w implementacji Chrome występuje błąd? Czy implementacja różni się od specyfikacji?

Zgłoś błąd na stronie new.crbug.com. Podaj jak najwięcej szczegółów, proste instrukcje odtworzenia problemu i wpisz UI>Browser>WebAppInstalls>FileHandling w polu Komponenty.

Wyrażanie poparcia dla interfejsu API

Czy planujesz używać interfejsu File Handling API? Twoje publiczne wsparcie pomaga zespołowi Chrome ustalać priorytety funkcji i pokazuje innym dostawcom przeglądarek, jak ważne jest ich obsługiwanie.

Opisz, jak zamierzasz z niej korzystać, w wątku na forum WICG Discourse.
Wyślij tweeta do @ChromiumDev z hasztagiem #FileHandling i daj nam znać, gdzie i jak z niego korzystasz.

Przydatne linki

Podziękowania

Interfejs File Handling API został opracowany przez Erica Willigersa, Jaya Harrisa i Raymesa Khoury’ego. Ten artykuł został sprawdzony przez Joe Medleya.