Zarejestruj aplikację jako moduł obsługi plików w systemie operacyjnym.
Teraz gdy aplikacje internetowe mogą odczytywać i zapisywać pliki, następnym logicznym krokiem jest umożliwienie deweloperom zadeklarowania tych aplikacji jako modułów obsługi plików, które ich aplikacje mogą tworzyć i przetwarzać. Służy do tego interfejs File handling API. Po zarejestrowaniu aplikacji edytora tekstu jako modułu obsługi plików i zainstalowaniu jej możesz kliknąć prawym przyciskiem myszy plik .txt
w systemie macOS, wybrać „Pobierz informacje”, a następnie wskazać systemowi operacyjnemu, że zawsze powinien otwierać pliki .txt
jako domyślny
w tej aplikacji.
Sugerowane przypadki użycia interfejsu File handling API
Przykłady witryn, w których można używać tego interfejsu API:
- Aplikacje pakietu Office, takie jak edytory tekstu, aplikacje do arkuszy kalkulacyjnych i kreatory pokazów slajdów.
- Edytory graficzne i narzędzia do rysowania.
- Narzędzia do edycji na poziomie gry wideo.
Jak używać interfejsu File handling API
Stopniowe ulepszanie
Interfejsu File handling API nie można wypełniać metodą poly. Otwieranie plików w aplikacji internetowej można jednak osiągnąć na 2 inne sposoby:
- Interfejs Web Share Target API pozwala programistom określić aplikację jako miejsce docelowe udostępniania, dzięki czemu można otwierać pliki z poziomu arkusza udostępniania systemu operacyjnego.
- Interfejs File System Access API można zintegrować z funkcją przeciągania i upuszczania plików, dzięki czemu deweloperzy mogą obsługiwać upuszczone pliki w już otwartej aplikacji.
Obsługiwane przeglądarki
Wykrywanie funkcji
Aby sprawdzić, czy interfejs File handling API jest obsługiwany, użyj polecenia:
if ('launchQueue' in window && 'files' in LaunchParams.prototype) {
// The File Handling API is supported.
}
Deklaratywna część interfejsu File handling API
Na początku aplikacje internetowe muszą deklaratywnie opisać w pliku manifestu aplikacji internetowej rodzaj plików, jakie mogą obsługiwać. Interfejs File handling API rozszerza plik manifestu aplikacji internetowej o nową właściwość o nazwie "file_handlers"
, która akceptuje tablicę modułów obsługi plików. Moduł obsługi pliku to obiekt o tych właściwościach:
- Właściwość
"action"
, która jako wartość wskazuje adres URL znajdujący się w zakresie aplikacji. - Właściwość
"accept"
z obiektem typu MIME jako kluczami i listą rozszerzeń plików jako ich wartościami. - Właściwość
"icons"
z tablicą ikonImageResource
. Niektóre systemy operacyjne umożliwiają powiązanie typu pliku z wyświetlaniem ikony, która nie jest tylko powiązaną ikoną aplikacji, ale też specjalną ikoną związaną z użyciem danego typu pliku w aplikacji. - Właściwość
"launch_type"
, która określa, czy w jednym kliencie należy otwierać wiele plików, czy w wielu klientach. Wartość domyślna to"single-client"
. Jeśli użytkownik otworzy wiele plików, a do obsługi pliku dodano adnotację"multiple-clients"
z atrybutem"launch_type"
, nastąpi więcej niż jedno uruchomienie aplikacji. Przy każdym uruchomieniu tablicaLaunchParams.files
(patrz dalej) będzie zawierała tylko 1 element.
Poniższy przykład, pokazujący 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"
}
]
}
Dotyczy to hipotetycznej aplikacji, która obsługuje pliki z wartościami rozdzielanymi przecinkami (.csv
) w pliku /open-csv
, skalowalne pliki grafiki wektorowej (.svg
) w języku /open-svg
i zmyślony format plików Grafr z dowolnym rozszerzeniem .grafr
, .graf
lub .graph
./open-graf
Pierwsze dwa są otwierane w jednym kliencie, a ostatni w wielu klientach, jeśli obsługiwanych jest wiele plików.
Kluczową częścią interfejsu File handling API jest
Po zadeklarowaniu, jakie pliki obsługuje, w której teorii jest adres URL, musi w praktyce wykonać odpowiednie działanie z plikami przychodzącymi. W tym miejscu do akcji wkracza launchQueue
. Aby uzyskać dostęp do uruchomionych plików, witryna musi określić konsumenta dla obiektu window.launchQueue
. Uruchomienia znajdują się w kolejce do momentu, gdy zostaną przetworzone przez określonego konsumenta, który jest wywoływany dokładnie raz przy każdym uruchomieniu. W ten sposób odbywa się każde uruchomienie niezależnie od daty podania 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
Obecnie nie udostępniamy pomocy dotyczącej Narzędzi deweloperskich, ale przesłałem(-am) prośbę o dodanie funkcji.
Pokaz
Dodaliśmy obsługę plików do Excalidraw, aplikacji do rysowania w stylu kreskówki. Aby przetestować tę funkcję, musisz najpierw zainstalować Excalidraw. Po utworzeniu pliku i zapisaniu go w systemie plików możesz go otworzyć, klikając dwukrotnie lub prawym przyciskiem myszy, a potem w menu kontekstowym wybrać „Excalidraw”. Implementację możesz sprawdzić w kodzie źródłowym.
![Okno wyszukiwania w systemie macOS z plikiem Excalidraw.](https://developer.chrome.google.cn/static/docs/capabilities/web-apis/file-handling/image/the-macos-finder-window-eac9df1131965.png?authuser=6&hl=pl)
![Menu kontekstowe, które pojawia się po kliknięciu pliku prawym przyciskiem myszy z wyróżnionym elementem „Otwórz za pomocą...”.](https://developer.chrome.google.cn/static/docs/capabilities/web-apis/file-handling/image/the-context-menu-appears-76d8a48d9d84e.png?authuser=6&hl=pl)
.excalidraw
.
Bezpieczeństwo
Zespół Chrome zaprojektował i wdrożył interfejs File handling API zgodnie z podstawowymi zasadami określonymi w artykule o kontrolowaniu dostępu do zaawansowanych funkcji platformy internetowej, takimi jak kontrola użytkownika, przejrzystość i ergonomia.
Uprawnienia, trwałość uprawnień i aktualizacje modułu obsługi plików
Aby zapewnić zaufanie użytkowników i bezpieczeństwo ich plików, po otwarciu pliku przez interfejs File handling API jest wyświetlana prośba o przyznanie uprawnień, zanim aplikacja PWA będzie mogła wyświetlić plik. Prośba o uprawnienia wyświetli się zaraz po wybraniu przez użytkownika aplikacji PWA w celu otwarcia pliku. Uprawnienia te są ściśle powiązane z czynnością polegającą na otwarciu pliku za pomocą aplikacji PWA, co sprawia, że jest on bardziej zrozumiały i trafny.
To uprawnienie będzie pojawiać się za każdym razem, dopóki użytkownik nie kliknie Zezwól lub Zablokuj obsługę plików w witrynie bądź trzykrotnie zignoruje prośbę (po tym czasie Chromium nałoży embargo i zablokuje to uprawnienie). Wybrane ustawienie będzie obowiązywać podczas zamykania i ponownego otwierania PWA.
Po wykryciu aktualizacji i zmian w pliku manifestu w sekcji "file_handlers"
uprawnienia zostaną zresetowane.
Wyzwania związane z plikami
Istnieje duża kategoria wektorów ataku, które otwierają się po zezwoleniem witrynom na dostęp do plików. Zostały one opisane w artykule o interfejsie File System Access API. Dodatkowa, niezbędna funkcja związana z zabezpieczeniami, którą zapewnia interfejs File handling API w stosunku do interfejsu File System Access API, polega na przyznawaniu dostępu do określonych plików za pomocą wbudowanego interfejsu systemu operacyjnego, a nie przy użyciu selektora plików wyświetlanego przez aplikację internetową.
Nadal istnieje ryzyko, że użytkownicy niechcący przyznają aplikacji internetowej dostęp do pliku, otwierając go. Ogólnie jednak wiadomo, że otwarcie pliku umożliwia aplikacji, w której go otworzyliśmy, jego odczytywanie i manipulowanie. Dlatego wyraźna decyzja użytkownika o otworzeniu pliku w zainstalowanej aplikacji (np. za pomocą menu kontekstowego „Otwórz za pomocą...”) może zostać odczytana jako wystarczający sygnał zaufania do tej aplikacji.
Domyślne wyzwania modułu obsługi
Wyjątkiem jest sytuacja, gdy w systemie hosta nie ma aplikacji dla określonego typu pliku. W takim przypadku niektóre systemy operacyjne hosta mogą automatycznie awansować nowo zarejestrowany moduł obsługi na domyślny moduł obsługi danego typu pliku w sposób dyskretny i bez żadnej interwencji użytkownika. Oznacza to, że jeśli użytkownik dwukrotnie kliknie plik tego typu, zostanie on automatycznie otwarty w zarejestrowanej aplikacji internetowej. Gdy klient użytkownika stwierdzi, że w takim systemie operacyjnym nie ma domyślnego modułu obsługi danego typu pliku, może być konieczne wysłanie wyraźnej prośby o przyznanie uprawnień, aby uniknąć przypadkowego wysłania zawartości pliku do aplikacji internetowej bez zgody użytkownika.
Kontrola użytkowników
Specyfikacja określa, że przeglądarki nie powinny rejestrować każdej witryny, która może obsługiwać pliki jako moduł obsługi plików. Zamiast tego proces rejestracji obsługi plików powinien być ograniczony po instalacji i nigdy nie może nastąpić bez wyraźnego potwierdzenia użytkownika, zwłaszcza jeśli witryna ma zostać domyślnym modułem 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 utworzyć własne rozszerzenia.
Przejrzystość
Wszystkie systemy operacyjne umożliwiają użytkownikom zmienianie bieżących powiązań plików. To wykracza poza zakres przeglądarki.
Prześlij opinię
Zespół Chrome chce poznać Twoje wrażenia z korzystania z interfejsu File handling API.
Opowiedz nam o projekcie interfejsu API
Czy jest coś, co nie działa w interfejsie API zgodnie z oczekiwaniami? A może brakuje metod lub właściwości, które potrzebujesz do realizacji swojego pomysłu? Masz pytanie lub komentarz na temat modelu bezpieczeństwa?
- Zgłoś problem ze specyfikacją w odpowiednim repozytorium GitHub lub dodaj swoje uwagi do istniejącego problemu.
Zgłoś problem z implementacją
Czy wystąpił błąd związany z implementacją przeglądarki Chrome? A może implementacja różni się od specyfikacji?
- Zgłoś błąd na new.crbug.com. Podaj jak najwięcej szczegółów, proste instrukcje odtwarzania i wpisz
UI>Browser>WebAppInstalls>FileHandling
w polu Komponenty. Usterka to doskonały sposób na udostępnianie szybkich i łatwych replik.
Pokaż obsługę interfejsu API
Czy zamierzasz użyć interfejsu File handling API? Twoja publiczna pomoc pomaga zespołowi Chrome priorytetowo traktować funkcje i pokazuje innym dostawcom przeglądarek, jak ważne jest ich wsparcie.
- W wątku WICG Discourse napisz, jak zamierzasz korzystać z tego narzędzia.
- Wyślij tweeta na adres @ChromiumDev, używając hashtagu
#FileHandling
, i daj nam znać, gdzie i do czego go używasz.
Przydatne linki
- Wyjaśnienie publiczne
- Prezentacja API obsługi plików | Źródło wersji demonstracyjnej interfejsu File handling API
- Błąd śledzenia w Chromium
- Wpis na ChromeStatus.com
- Komponent Blink:
UI>Browser>WebAppInstalls>FileHandling
- Przegląd tagów
- Stanowisko w standardzie Mozilla
Podziękowania
Interfejs File handling API został określony przez Erica Willigersa, Jaya Harrisa i Raymesa Khoury. Autor artykułu: Joe Medley.