Zarejestruj aplikację jako moduł obsługi plików w systemie operacyjnym.
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ć. Właśnie to umożliwia interfejs File handling API. 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 programy do tworzenia prezentacji;
- edytory grafik i narzędzia do rysowania;
- Narzędzia do edycji poziomów w grach 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 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
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óra jako 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ą ikonImageResource
. Niektóre systemy operacyjne umożliwiają powiązanie typu pliku na wyświetlanie ikony, która nie jest tylko ikoną aplikacji, ale specjalną ikoną związaną z wykorzystaniem danego 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 moduł obsługi plików został oznaczony adnotacją"multiple-clients"
jako"launch_type"
, uruchomi się więcej niż 1 aplikacja, a przy każdym uruchomieniu tablicaLaunchParams.files
(patrz więcej informacji) będzie mieć tylko 1 element.
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 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
Po zadeklarowaniu przez aplikację, jakie pliki obsługuje w przypadku określonych adresów URL objętych raportowaniem MRC, w praktyce musi wykonać pewne czynności 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, dopóki nie zostaną obsługiwane przez określonego konsumenta, co jest wywoływane dokładnie raz dla 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.
}
});
}
Pomoc do 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 dwukrotnie lub klikając prawym przyciskiem myszy i wybierając „Excalidraw” w menu kontekstowym. Implementację możesz sprawdzić w kodzie źródłowym.
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łów 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 ponowym otwarciu aplikacji internetowej.
Gdy plik manifestu zostanie zaktualizowany i wykryje zmiany w sekcji "file_handlers"
, uprawnienia zostaną zresetowane.
Testy związane z plikami
Istnieje duża kategoria wektorów ataku, które można otwierać, zezwalając 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 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 dla danego 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 użytkownika
Według specyfikacji przeglądarki nie powinny rejestrować każdej witryny, która może obsługiwać pliki jako moduł obsługi plików. 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 dowiedzieć się więcej o Twoich doświadczeniach 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 pytanie lub komentarz na temat modelu zabezpieczeń?
- 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 wyrzutów złości.
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.
- W wątku na forum Discourse dotyczącej WGICh opisz, jak zamierzasz go używać.
- Wyślij tweeta do @ChromiumDev, używając hashtaga
#FileHandling
, i powiedz nam, gdzie i jak z niego korzystasz.
Przydatne linki
- Publiczny film wyjaśniający
- Prezentacja interfejsu File handling API | Źródło demonstracyjne interfejsu File handling API
- Błąd śledzenia w Chromium
- Wpis na stronie ChromeStatus.com
- Komponent Blink:
UI>Browser>WebAppInstalls>FileHandling
- Sprawdzanie tagów
- Mozilla Standards Position
Podziękowania
Interfejs File handling API określili Eric Willigers, Jay Harris i Raymes Khoury. Ten artykuł zrecenzował Joe Medley.