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

Zarejestruj aplikację jako moduł obsługi plików w systemie operacyjnym.

Thomas Steiner

Teraz, gdy aplikacje internetowe potrafią odczytywać i zapisywać pliki, kolejnym logicznym krokiem jest umożliwienie deweloperom deklarowania tych aplikacji internetowych jako modułów obsługujących pliki, które mogą tworzyć i przetwarzać. Interfejs File Handling API umożliwia właśnie to. Po zarejestrowaniu aplikacji edytora tekstu jako modułu obsługi plików i jej zainstalowaniu możesz kliknąć plik .txt prawym przyciskiem myszy w systemie macOS i wybrać „Uzyskaj informacje”, aby wskazać systemowi, że domyślnie pliki .txt powinny być otwierane za pomocą tej aplikacji.

Sugerowane przypadki użycia interfejsu File Handling API

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

  • aplikacje pakietu Office, takie jak edytory tekstu, arkusze kalkulacyjne i aplikacje do tworzenia pokazów slajdów;
  • edytory grafik i narzędzi 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ć wypełniany automatycznie. Funkcję otwierania plików za pomocą aplikacji internetowej można jednak uzyskać na 2 inne sposoby:

  • Interfejs Web Share Target API pozwala deweloperom określić aplikację jako docelowe miejsce udostępniania, dzięki czemu pliki można otwierać z poziomu panelu udostępniania systemu operacyjnego.
  • Interfejs File System Access API można zintegrować z przeciąganiem i upuszczaniem plików, aby deweloperzy mogli obsługiwać upuszczane pliki w otwartej już aplikacji.

Obsługa przeglądarek

Obsługa przeglądarek

  • Chrome: 102.
  • Edge: 102.
  • Firefox: nieobsługiwane.
  • Safari: nieobsługiwane.

Źródło

Wykrywanie cech

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

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

Deklaratywna część interfejsu File Handling API

W pierwszym kroku aplikacje internetowe muszą w swoim pliku manifestu aplikacji internetowej deklaratywnie określić, z jakimi plikami mogą pracować. Interfejs File Handling API rozszerza plik manifestu aplikacji internetowej o nową właściwość o nazwie "file_handlers", która akceptuje tablicę elementów obsługujących pliki. Obsługa pliku to obiekt z tymi właściwościami:

  • Właściwość "action", której wartość wskazuje na adres URL w zakresie aplikacji.
  • Właściwość "accept" z obiektem typu 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 skojarzenia typu pliku, która nie jest tylko ikoną powiązanej aplikacji, ale specjalną ikoną związaną z korzystaniem z tego typu pliku w aplikacji.
  • Właściwość "launch_type", która określa, czy wiele plików ma być otwieranych w jednym kliencie, czy w kilku. Wartość domyślna to "single-client". Jeśli użytkownik otworzy wiele plików, a obsługa pliku zostanie oznaczona jako "multiple-clients", nastąpi więcej niż 1 uruchomienie aplikacji. W przypadku każdego uruchomienia tablica LaunchParams.files (patrz poniżej) będzie mieć tylko 1 element."launch_type"

Przykład poniżej, który pokazuje tylko odpowiedni fragment pliku manifestu aplikacji internetowej, powinien pomóc w zrozumieniu tej kwestii:

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

Jest to hipotetyczna aplikacja, która obsługuje pliki rozdzielcze rozdzielone przecinkami (.csv) w /open-csv, pliki wektorowej grafiki skalowanej (.svg) w /open-svg oraz wymyślony format pliku Grafr z rozszerzeniem .grafr, .graf lub .graph w /open-graf. Pierwsze 2 okna otworzą się w ramach jednego klienta, a ostatnie – w ramach wielu klientów, jeśli przetwarzane są liczne pliki.

Imperatywna część interfejsu File Handling API

Teraz, gdy aplikacja teoretycznie określiła, jakie pliki może obsługiwać na danym adresie URL w zakresie, musi w praktyce wykonać jakieś działanie z przychodzącymi plikami. Wtedy przydaje się launchQueue. Aby uzyskać dostęp do uruchomionych plików, witryna musi określić konsumenta obiektu window.launchQueue. Uruchomienia są umieszczane w kolejce do momentu, aż zostaną obsłużone przez określonego konsumenta, który jest wywoływany dokładnie raz w przypadku każdego uruchomienia. W ten sposób każda kampania jest obsługiwana niezależnie od tego, kiedy został określony konsument.

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

Wsparcie dotyczące Narzędzi deweloperskich

W momencie pisania tego artykułu nie ma obsługi w narzędziu DevTools, ale przesłałem prośbę o dodanie funkcji, aby umożliwić to.

Prezentacja

Dodałem obsługę obsługi plików w aplikacji do rysowania w stylu rysunkowego komiksu Excalidraw. Aby ją przetestować, musisz najpierw zainstalować Excalidraw. Gdy utworzysz plik i zapiszesz go w swoim systemie plików, możesz otworzyć go, klikając go dwukrotnie lub klikając 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 kliknij prawym przyciskiem myszy plik w eksploratorze plików systemu operacyjnego.
Menu kontekstowe, które pojawia się po kliknięciu prawym przyciskiem myszy pliku z wyróżnionym elementem 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, korzystając z podstawowych zasad zdefiniowanych w artykule Kontrolowanie dostępu do zaawansowanych funkcji platformy internetowej, w tym kontroli użytkownika, przejrzystości i ergonomiki.

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

Aby zapewnić użytkownikom bezpieczeństwo i zaufanie do plików, gdy interfejs API do obsługi plików otworzy plik, przed wyświetleniem pliku w aplikacji PWA wyświetli się prośba o uprawnienia. Ten komunikat o uprawnieniach będzie wyświetlany zaraz po wybraniu przez użytkownika aplikacji PWA do otwarcia pliku, aby uprawnienia były ściśle powiązane z działaniem polegającym na otwieraniu pliku za pomocą aplikacji PWA, co ułatwi ich zrozumienie i zwiększy ich trafność.

To uprawnienie będzie wyświetlane za każdym razem, dopóki użytkownik nie kliknie Zezwól lub Zablokuj obsługi plików w witrynie albo nie zignoruje tego prompta 3 razy (po czym Chromium zablokuje to uprawnienie). Wybrane ustawienie będzie obowiązywać po zamknięciu i ponownie uruchomieniu aplikacji PWA.

Gdy plik manifestu zostanie zaktualizowany i wykryje zmiany w sekcji "file_handlers", uprawnienia zostaną zresetowane.

Istnieje wiele rodzajów ataków, które są możliwe, gdy zezwolisz witrynom na dostęp do plików. Informacje na ten temat znajdziesz w artykule o interfejsie File System Access API. Dodatkowa funkcja zabezpieczeń, którą interfejs File Handling API oferuje w porównaniu z interfejsem File System Access API, to możliwość przyznawania dostępu do określonych plików za pomocą wbudowanego interfejsu użytkownika systemu operacyjnego, a nie za pomocą selektora plików wyświetlanego przez aplikację internetową.

Nadal 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, za pomocą której został otwarty, odczytywanie lub modyfikowanie tego pliku. Dlatego wyraźny wybór przez użytkownika pliku w zainstalowanej aplikacji, np. w menu kontekstowym „Otwórz za pomocą…”, może być uznany za wystarczający sygnał zaufania do aplikacji.

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

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

Kontrola użytkownika

Specyfikacja określa, że przeglądarki nie powinny rejestrować jako przetwarzacza plików wszystkich witryn, które mogą obsługiwać pliki. Zamiast tego rejestracja obsługi plików powinna być ograniczona do instalacji i nigdy nie powinna odbywać się bez wyraźnego potwierdzenia użytkownika, zwłaszcza jeśli witryna ma stać się domyślnym modułem obsługi. Zamiast przechwytywać istniejące rozszerzenia, takie jak .json, dla których użytkownik prawdopodobnie ma już zarejestrowany domyślny moduł obsługi, witryny powinny tworzyć własne rozszerzenia.

Przejrzystość

Wszystkie systemy operacyjne umożliwiają użytkownikom zmianę bieżących powiązań plików. Jest to poza zakresem przeglądarki.

Prześlij opinię

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

Poinformuj nas o projektowaniu interfejsu API

Czy coś w interfejsie API nie działa zgodnie z oczekiwaniami? A może brakuje metod lub właściwości, których potrzebujesz do wdrożenia swojego pomysłu? Masz pytania lub uwagi dotyczące modelu bezpieczeństwa?

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

Zgłaszanie problemów z implementacją

Czy znalazłeś/znalazłaś błąd w implementacji Chrome? A może implementacja różni się od specyfikacji?

  • Zgłoś błąd na stronie new.crbug.com. Podaj jak najwięcej szczegółów, proste instrukcje odtwarzania błędu i wpisz UI>Browser>WebAppInstalls>FileHandling w polu Składniki. Glitch świetnie sprawdza się do szybkiego i łatwego wyrażania niezadowolenia.

Pokaż informacje o pomocy dotyczącej interfejsu API

Zamierzasz używać interfejsu File Handling API? Twoja publiczna pomoc pomaga zespołowi Chrome ustalać priorytety funkcji i pokazuje innym dostawcom przeglądarek, jak ważne jest wspieranie tych funkcji.

Przydatne linki

Podziękowania

Interfejs File Handling API został opracowany przez Erica Willigera, Jaya Harrisa i Raymesa Khoury'ego. Ten artykuł został sprawdzony przez Joe Medley.