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 mogą odczytywać i zapisywać pliki, kolejnym logicznym krokiem jest umożliwienie deweloperom zadeklarowania ich jako modułów obsługi plików, 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ć „Pobierz informacje”, aby instruować system, że pliki .txt powinny zawsze otwierać się domyślnie w 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 programy do tworzenia prezentacji;
  • edytory grafik i narzędzia do rysowania;
  • narzędzia do edycji poziomów gier wideo;

Jak korzystać z interfejsu File handling API

Progresywne ulepszanie

Interfejs File Handling API nie może być wypełniany automatycznie. Funkcję otwierania plików za pomocą aplikacji internetowej można jednak udostępnić 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: funkcja nieobsługiwana.
  • 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ść "file_handlers", która akceptuje tablicę modułów obsługi plików. Obsługa pliku to obiekt z tymi właściwościami:

  • Właściwość "action", która jako wartość wskazuje adres URL będący 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" określająca, czy należy otworzyć wiele plików w jednym kliencie czy w kilku klientach. 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 zawierać tylko 1 element."launch_type"

Poniższy przykład, który zawiera tylko odpowiedni fragment pliku manifestu aplikacji internetowej, powinien być bardziej zrozumiały:

{
  "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 z wartościami rozdzielanymi przecinkami (.csv) w katalogu /open-csv, skalowalne pliki grafiki wektorowej (.svg) w /open-svg oraz wymyślony format pliku Grafr z rozszerzeniem .grafr, .graf lub .graph./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 dla 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 obsługiwane jest każde uruchomienie, niezależnie od tego, kiedy konsument został określony.

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

Obecnie pomoc dotycząca Narzędzi deweloperskich nie jest obsługiwana, ale otrzymaliśmy od Ciebie prośbę o dodanie funkcji.

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 dwukrotnie lub klikając prawym przyciskiem myszy i wybierając „Excalidraw” w menu kontekstowym. Implementację możesz sprawdzić w kodzie źródłowym.

Okno wyszukiwania systemu 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 zgodnie z podstawowymi zasadami określonymi w artykule Kontrola dostępu do zaawansowanych funkcji platformy internetowej, takimi jak kontrola użytkowników, przejrzystość i ergonomia.

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

Aby zapewnić użytkownikom zaufanie i bezpieczeństwo ich plików, po otwarciu pliku przez interfejs File Managing API przed wyświetleniem pliku pojawia się prośba o przyznanie uprawnień. 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 ponowym otwarciu aplikacji internetowej.

Po wykryciu aktualizacji pliku manifestu i zmian 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 te znajdziesz w artykule na temat interfejsu 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 tego pliku lub manipulowanie nim. 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 gdy użytkownik dwukrotnie kliknie plik tego typu, otworzy się on automatycznie w zarejestrowanej aplikacji internetowej. Gdy klient użytkownika stwierdzi, że nie ma domyślnego modułu obsługi dla danego typu pliku, może być konieczne wyraźne zezwolenie

Kontrola użytkownika

Specyfikacja określa, że przeglądarki nie powinny rejestrować jako modułu obsługi plików każdej witryny, która może obsługiwać pliki. Zamiast tego rejestracja obsługi plików powinna być powiązana z instalacją 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.

Prześlij informacje 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ł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 nadaje się do szybkiego i łatwego udostępniania materiałów.

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 określili Eric Willigers, Jay Harris i Raymes Khoury. Ten artykuł zrecenzował Joe Medley.