Tarayıcılar uzun zamandır dosya ve dizinlerle çalışabiliyor. File API, web uygulamalarında dosya nesnelerini temsil etmenin yanı sıra bunları programatik olarak seçmek ve verilerine erişmek için özellikler sağlar. Ancak daha yakından baktığınızda her şeyin göründüğü gibi olmadığını görebilirsiniz.
Dosyalarla çalışmanın geleneksel yolu
Dosyaları açma
Geliştirici olarak <input type="file"> öğesini kullanarak dosyaları açıp okuyabilirsiniz.
Bir dosyayı açma işleminin en basit hali aşağıdaki kod örneğine benzer şekilde görünebilir.
input nesnesi size bir FileList verir. Aşağıdaki örnekte bu nesne yalnızca bir File içerir.
File, belirli bir tür Blob'dir ve bir Blob'ın kullanılabildiği her bağlamda kullanılabilir.
const openFile = async () => {
return new Promise((resolve) => {
const input = document.createElement('input');
input.type = 'file';
input.addEventListener('change', () => {
resolve(input.files[0]);
});
input.click();
});
};
Dizinleri açma
Klasörleri (veya dizinleri) açmak için <input webkitdirectory> özelliğini ayarlayabilirsiniz.
Bunun dışında, diğer her şey yukarıdaki gibi çalışır.
Sağlayıcı ön ekiyle başlayan adına rağmen webkitdirectory yalnızca Chromium ve WebKit tarayıcılarında değil, eski EdgeHTML tabanlı Edge'de ve Firefox'ta da kullanılabilir.
Dosyaları kaydetme (doğrusu: indirme)
Dosya kaydetmek için geleneksel olarak indirme seçeneğiyle sınırlısınız. Bu seçenek, <a download> özelliği sayesinde kullanılabilir.
Bir Blob verildiğinde, ankrajın href özelliğini URL.createObjectURL() yönteminden alabileceğiniz bir blob: URL'sine ayarlayabilirsiniz.
const saveFile = async (blob) => {
const a = document.createElement('a');
a.download = 'my-file.txt';
a.href = URL.createObjectURL(blob);
a.addEventListener('click', (e) => {
setTimeout(() => URL.revokeObjectURL(a.href), 30 * 1000);
});
a.click();
};
Sorun
İndir yaklaşımının en büyük dezavantajı, klasik bir açma→düzenleme→kaydetme akışı oluşturamamasıdır. Yani orijinal dosyanın üzerinin silinmesi mümkün değildir. Bunun yerine, "kaydettiğimizde" işletim sisteminin varsayılan İndirilenler klasöründe orijinal dosyanın yeni bir kopyası oluşturulur.
File System Access API
File System Access API, hem açma hem de kaydetme işlemlerini çok daha basit hale getirir. Ayrıca gerçek kaydetme özelliğini de etkinleştirir. Yani dosyayı nereye kaydedeceğinizi seçmekle kalmaz, mevcut bir dosyanın üzerine de yazabilirsiniz.
Dosyaları açma
File System Access API ile dosya açma işlemi, window.showOpenFilePicker() yöntemine tek bir çağrıda bulunarak gerçekleştirilebilir.
Bu çağrı, getFile() yöntemi aracılığıyla gerçek File değerini alabileceğiniz bir dosya tutamaç döndürür.
const openFile = async () => {
try {
// Always returns an array.
const [handle] = await window.showOpenFilePicker();
return handle.getFile();
} catch (err) {
console.error(err.name, err.message);
}
};
Dizinleri açma
Dosya iletişim kutusunda dizinleri seçilebilir hale getiren window.showDirectoryPicker() işlevini çağırarak bir dizin açın.
Dosya kaydetme
Dosya kaydetme işlemi de benzer şekilde kolaydır.
Bir dosya tutamacından createWritable() aracılığıyla yazılabilir bir akış oluşturursunuz, ardından akışın write() yöntemini çağırarak Blob verilerini yazarsınız ve son olarak close() yöntemini çağırarak akışı kapatırsınız.
const saveFile = async (blob) => {
try {
const handle = await window.showSaveFilePicker({
types: [{
accept: {
// Omitted
},
}],
});
const writable = await handle.createWritable();
await writable.write(blob);
await writable.close();
return handle;
} catch (err) {
console.error(err.name, err.message);
}
};
browser-fs-access ile tanışın
File System Access API mükemmel bir API olsa da henüz yaygın olarak kullanılamamaktadır.
Bu nedenle, File System Access API'yi kademeli bir geliştirme olarak görüyorum. Bu nedenle, tarayıcı desteklediğinde bu yöntemi, desteklemediğinde ise geleneksel yaklaşımı kullanmak istiyorum. Bu süreçte, kullanıcıyı desteklenmeyen JavaScript kodlarının gereksiz indirmeleriyle cezalandırmak istemiyorum. browser-fs-access kitaplığı, bu soruna verdiğim yanıttır.
Tasarım felsefesi
File System Access API'nin gelecekte değişme olasılığı olduğundan browser-fs-access API bu API'ye göre modellenmemiştir.
Yani kütüphane bir polyfill değil, ponyfill'dir.
Uygulamanızı olabildiğince küçük tutmak için ihtiyacınız olan işlevleri yalnızca (statik veya dinamik olarak) içe aktarabilirsiniz.
Kullanılabilir yöntemler, fileOpen(), directoryOpen() ve fileSave() olarak adlandırılmıştır.
Kitaplık, File System Access API'nin desteklenip desteklenmediğini dahili olarak algılar ve ardından ilgili kod yolunu içe aktarır.
browser-fs-access kitaplığını kullanma
Bu üç yöntemin kullanımı kolaydır.
Uygulamanızın kabul edilen mimeTypes veya dosya extensions türünü belirtebilir ve birden fazla dosya veya dizin seçimine izin vermek ya da vermemek için bir multiple işareti ayarlayabilirsiniz.
Tüm ayrıntılar için browser-fs-access API belgelerine bakın.
Aşağıdaki kod örneğinde, resim dosyalarını nasıl açıp kaydedebileceğiniz gösterilmektedir.
// The imported methods will use the File
// System Access API or a fallback implementation.
import {
fileOpen,
directoryOpen,
fileSave,
} from 'https://unpkg.com/browser-fs-access';
(async () => {
// Open an image file.
const blob = await fileOpen({
mimeTypes: ['image/*'],
});
// Open multiple image files.
const blobs = await fileOpen({
mimeTypes: ['image/*'],
multiple: true,
});
// Open all files in a directory,
// recursively including subdirectories.
const blobsInDirectory = await directoryOpen({
recursive: true
});
// Save a file.
await fileSave(blob, {
fileName: 'Untitled.png',
});
})();
Demo
Yukarıdaki kodun işleyişini Glitch'teki demo'da görebilirsiniz. Kaynak kodu da buradan edinilebilir. Güvenlik nedeniyle kaynakta çapraz alt çerçevelerin dosya seçici göstermesine izin verilmediğinden demo bu makaleye yerleştirilemez.
Kullanımdaki browser-fs-access kitaplığı
Boş zamanlarımda, Excalidraw adlı yüklenebilir bir PWA'ya katkıda bulunuyorum. Bu beyaz tahta aracı, el çizimi hissi veren diyagramları kolayca çizmenize olanak tanır. Tamamen duyarlı olan bu tema, küçük cep telefonlarından büyük ekranlı bilgisayarlara kadar çeşitli cihazlarda sorunsuz şekilde çalışır. Bu nedenle, File System Access API'yi destekleyip desteklemediklerinden bağımsız olarak çeşitli platformlardaki dosyalarla ilgilenmesi gerekir. Bu, browser-fs-access kitaplığı için mükemmel bir aday yapar.
Örneğin, iPhone'umda bir çizim başlatabilir, çizimi iPhone'umun İndirilenler klasörüne kaydedebilir (teknik olarak: Safari, File System Access API'yi desteklemediğinden dosyayı indirebilir), dosyayı masaüstümde açabilir (telefonumdan aktardıktan sonra), dosyada değişiklik yapabilir ve değişikliklerimin üzerine yazabilir ya da dosyayı yeni bir dosya olarak kaydedebilirim.
Gerçek hayattan kod örneği
Aşağıda, Excalidraw'da kullanılan browser-fs-access izninin gerçek bir örneğini görebilirsiniz.
Bu alıntı /src/data/json.ts sitesinden alınmıştır.
saveAsJSON() yönteminin, browser-fs-access'in fileSave() yöntemine bir dosya mülkünü veya null değerini nasıl ilettiği özellikle ilgi çekicidir. Bu, bir mülk verildiğinde üzerine yazılmasına veya verilmediğinde yeni bir dosyaya kaydedilmesine neden olur.
export const saveAsJSON = async (
elements: readonly ExcalidrawElement[],
appState: AppState,
fileHandle: any,
) => {
const serialized = serializeAsJSON(elements, appState);
const blob = new Blob([serialized], {
type: "application/json",
});
const name = `${appState.name}.excalidraw`;
(window as any).handle = await fileSave(
blob,
{
fileName: name,
description: "Excalidraw file",
extensions: ["excalidraw"],
},
fileHandle || null,
);
};
export const loadFromJSON = async () => {
const blob = await fileOpen({
description: "Excalidraw files",
extensions: ["json", "excalidraw"],
mimeTypes: ["application/json"],
});
return loadFromBlob(blob);
};
Kullanıcı arayüzüyle ilgili dikkat edilmesi gereken noktalar
Excalidraw'da veya uygulamanızda kullanıcı arayüzü, tarayıcının destek durumuna göre uyarlanmalıdır.
File System Access API destekleniyorsa (if ('showOpenFilePicker' in window) {}) Kaydet düğmesine ek olarak Farklı Kaydet düğmesi de gösterebilirsiniz.
Aşağıdaki ekran görüntülerinde, Excalidraw'ın iPhone'daki ve Chrome masaüstündeki duyarlı ana uygulama araç çubuğu arasındaki fark gösterilmektedir.
iPhone'da Olarak Kaydet düğmesinin bulunmadığını unutmayın.
Sonuçlar
Sistem dosyalarıyla çalışmak teknik olarak tüm modern tarayıcılarda çalışır. File System Access API'yi destekleyen tarayıcılarda, dosyaların gerçek anlamda kaydedilmesine ve üzerine yazılmasına (yalnızca indirilmesine değil) izin vererek ve kullanıcılarınızın istedikleri yerde yeni dosya oluşturmasına izin vererek deneyimi iyileştirebilir, File System Access API'yi desteklemeyen tarayıcılarda ise işlevselliğini koruyabilirsiniz. browser-fs-access, aşamalı iyileştirmenin inceliklerini ele alarak ve kodunuzu olabildiğince basit hale getirerek hayatınızı kolaylaştırır.
Teşekkür ederiz
Bu makale Joe Medley ve Kayce Basques tarafından incelenmiştir. Projedeki çalışmaları ve çekme isteklerimizi incelemeleri için Excalidraw'a katkıda bulunanlara teşekkür ederiz. Unsplash'taki Ilya Pavlov tarafından oluşturulan lokomotif resim.