Mobil tətbiqdə sənədlər kataloqu — bu nədir, məqsədi və saxlamağı necə təşkil etmək olar

Tətbiqin sənədlər kataloqu nədir?

Sənədlər kataloqu — tətbiqin sandbox daxilində istifadəçi fayllarının daimi saxlanması üçün nəzərdə tutulmuş xüsusi yerdir. Keşdən fərqli olaraq, bu kataloqda olan fayllar istifadəçi üçün vacib sayılır: yer çatışmazlığı zamanı sistem tərəfindən silinmir, tətbiq yeniləmə zamanı qorunur və cihaz sinxronizasiyası zamanı ehtiyat nüsxəsi götürülür. iOS-da Documents kataloqu Sandbox konteynerinin bir hissəsidir və avtomatik olaraq iCloud ehtiyat nüsxəsinə daxil edilir. Android-də birbaşa analoqu yoxdur — ekvivalenti daimi fayllar üçün nəzərdə tutulmuş context.filesDir-dir, lakin daxili ehtiyat nüsxə mexanizmi yoxdur.

Sənədlər kataloqu ilə Android-də daxili yaddaş (Internal Storage) arasındakı fərq minimaldır: hər ikisi tətbiqin sandboxında yerləşir, hər ikisi deinstalyasiya zamanı silinir, hər ikisi digər tətbiqlər üçün əlçatmazdır. Əsas fərq semantikdir: Documents Directory faylların istifadəçi tərəfindən yaradıldığını və ya idxal edildiyini nəzərdə tutur, Internal Storage isə tətbiqin daxili fayllarını (verilənlər bazaları, konfiqurasiyalar) ehtiva edə bilər. iOS-da fərq daha əhəmiyyətlidir: Documents avtomatik ehtiyat nüsxəsi götürülür, Library/Application Support isə yox. Bu, saxlama strategiyasına təsir edir: Documents-də yalnız istifadəçinin yeni cihazda bərpa etmək istədiyi şeyləri, Application Support-da isə tətbiqin yenidən yarada biləcəyi daxili məlumatları yerləşdirin.

Sandbox arxitekturası digər tətbiqlərin sizin tətbiqinizin sənədlər kataloquna girişi olmadığına zəmanət verir. iOS-da jailbreak olmadan digər tətbiqlərin Documents-ə girişi mümkün deyil. Android-də root girişi istənilən tətbiqin filesDir-ni oxumağa imkan verir, buna görə də məxfi məlumatlar (tokenlər, şifrələmə açarları) AndroidX Security kitabxanasından EncryptedSharedPreferences və ya EncryptedFile ilə əlavə qorunmalıdır.

Sənədlər kataloqunda hansı məlumatlar saxlanılır

Sənədlər kataloqunda istifadəçi üçün dəyərli olan və tətbiq yenidən başladıldıqdan və ya cihaz bərpa edildikdən sonra əlçatan olmalı olan məlumatlar yerləşdirilməlidir. Bütün fayllar bu kataloqda saxlamaq üçün uyğun deyil — seçim məlumat növündən və istifadə ssenarisindən asılıdır.

İstifadəçi sənədləri və faylları

İstifadəçi faylları — sənədlər kataloqunun əsas məzmunudur. Bunlar redaktorda yaradılmış mətn sənədləri, tətbiqin kamerası ilə çəkilmiş şəkillər, ixrac edilmiş PDF hesabatlar, audio yazılar, qeydlər ola bilər. Hər bir belə fayl istifadəçi tərəfindən və ya onun istəyi ilə yaradılıb və istənilən anda əlçatan olmalıdır. iOS-da Documents-dən fayllar sistemin Files tətbiqində göstərilir ki, bu da istifadəçiyə standart fayl meneceri vasitəsilə onları idarə etməyə imkan verir. Android-də oxşar göstərim yoxdur — tətbiq özü saxlanılmış faylları görmək üçün interfeys təmin etməlidir.

Verilənlər bazaları və tətbiq parametrləri

SQLite verilənlər bazaları və parametr faylları adətən sənədlər kataloqunun yanında, lakin onun özündə deyil saxlanılır. iOS-da verilənlər bazaları Library/Application Support-da yerləşdirilir, çünki onlar Files tətbiqində göstərilməməli və ayrıca ehtiyat nüsxəsi götürülməməlidir. Android-də verilənlər bazaları defolt olaraq Room və ya SQLiteOpenHelper vasitəsilə /data/data/<package>/databases/ ünvanında yaradılır. Verilənlər bazası istifadəçi məzmununu (qeydlər, gündəlik, maliyyə qeydləri) ehtiva edərsə, sistem vasitəsilə ehtiyat nüsxəni təmin etmək üçün onu filesDir-də yerləşdirmək olar. Room RoomDatabase.Builder callback-i vasitəsilə verilənlər bazasının saxlanması üçün xüsusi kataloq təyin etməyə imkan verir.

val dbFile = File(context.filesDir, "user_database.db")

val db = Room.databaseBuilder<AppDatabase>(
    context,
    dbFile.absolutePath
).build()

İxrac və idxal edilmiş məlumatlar

İstifadəçinin digər tətbiqlərdən idxal etdiyi və ya tətbiqinizdən ixrac etdiyi fayllar da sənədlər kataloqunda saxlanmalıdır. iOS-da UIDocumentPickerViewController vasitəsilə idxal asCopy: true parametrindən istifadə edərkən avtomatik olaraq faylın surətini Documents-də yerləşdirir. Android-də SAF dialoqu vasitəsilə idxal da tətbiqin sandboxında faylın surətini yaradır. Məlumat ixrac edərkən (məsələn, kontaktlarla CSV faylı yaratmaq) faylı əvvəlcə Documents/filesDir-də saxlayın, sonra istifadəçiyə Share Sheet vasitəsilə paylaşmağı təklif edin. Bu, istifadəçi göndərmədən sonra faylı yadda saxlamağı unutsa belə, surətin sonradan istifadə üçün tətbiqdə qalmasına zəmanət verir.

Android-də sənədlər kataloqu ilə necə işləmək olar

Android-də sənədlər kataloqu funksiyalarını context.filesDir yerinə yetirir. Əlavə olaraq SD kartda context.externalFilesDir kataloqu mövcuddur, lakin o məlumatların qorunmasına zəmanət vermir. Bu kataloqlarla işin əsas üsullarını nəzərdən keçirək.

filesDir vasitəsilə fayllara giriş və idarəetmə

filesDir — Android-də tətbiqin daimi faylları üçün əsas kataloq. O tətbiqin sandboxında yerləşir və deinstalyasiya zamanı tamamilə silinir. File nümunəsi əldə etmək üçün /data/data/<package>/files/ kataloquna yol qaytaran context.filesDir-dən istifadə edin. Faylları yaratmaq və oxumaq üçün standart Java/Kotlin File əməliyyatlarından və ya fayl adını qəbul edən və FileInputStream/FileOutputStream qaytaran Context metodlarından openFileInput() və openFileOutput() istifadə edin. openFileOutput() metodu fayl hələ mövcud deyilsə avtomatik olaraq filesDir-də yaradır və giriş rejimini təyin etməyə imkan verir: MODE_PRIVATE (yalnız cari tətbiq), MODE_APPEND (əlavə etmə) və ya MODE_WORLD_READABLE (köhnəlmiş, API 24+ ilə istifadə edilmir).

val fileName = "report.pdf"
val content = "PDF content".toByteArray()

context.openFileOutput(fileName, Context.MODE_PRIVATE).use { stream ->
    stream.write(content)
}

val bytes = context.openFileInput(fileName).use { stream ->
    stream.readBytes()
}

Android 10+-da saxlama xüsusiyyətləri

Android 10+-da Scoped Storage modeli filesDir-ə təsir etmir — tətbiqin öz sandboxına giriş tam olaraq qalır. filesDir daxilində bütün oxuma və yazma əməliyyatları əlavə icazələr tələb etmir. Lakin filesDir vasitəsilə başqa tətbiqin fayllarına daxil olmağa cəhd etdikdə istisna alacaqsınız. Fayl mübadiləsi üçün faylı başqa tətbiqə ötürmək üçün müvəqqəti content URI yaradan FileProvider-dən istifadə edin. FileProvider AndroidManifest.xml-də <provider> teqi vasitəsilə elan edilir və yol XML faylında konfiqurasiya edilir. Bu, tətbiqlər arasında fayl ötürmək üçün standart mexanizmdir, məsələn, ACTION_SEND ilə Intent vasitəsilə şəkil göndərərkən istifadə olunur.

iOS-də sənədlər kataloqu ilə necə işləmək olar

iOS-da Documents Directory xüsusi statuslu tətbiqin Sandbox konteynerinin bir hissəsidir. Bu kataloqdan olan fayllar avtomatik olaraq iCloud ehtiyat nüsxəsinə daxil edilir, Files tətbiqində göstərilir və App Store vasitəsilə tətbiq yeniləmə zamanı qorunur.

Documents Directory və ehtiyat nüsxə

Avtomatik ehtiyat nüsxə Documents — iOS-un əsas üstünlüyüdür. İstifadəçi cihazı iTunes-a qoşduqda və ya iCloud Backup-ı aktivləşdirdikdə, Documents/ fayllarının hamısı ehtiyat nüsxəyə kopyalanır. Yeni cihazda bərpa edərkən istifadəçi bütün fayllarını əlavə tədbirlər olmadan alır. Lakin bu üstünlük çatışmazlığa çevrilir, əgər tətbiq Documents-də böyük həcmdə məlumat saxlayırsa: ehtiyat nüsxə vaxtı artır və iCloud yaddaşı tez bitə bilər. Buna görə də Documents-də yalnız istifadəçiyə bərpa zamanı həqiqətən lazım olan faylları saxlamaq lazımdır. Müvəqqəti fayllar, keş və yenidən yaradıla bilən məlumatlar Caches və ya Library/Application Support-da olmalıdır. Apple, isExcludedFromBackup atributu vasitəsilə internetdən yenidən endirilə bilən faylları ehtiyat nüsxədən çıxarmağı tövsiyə edir.

let fm = FileManager.default
let docsURL = fm.urls(
    for: .documentDirectory,
    in: .userDomainMask
).first!

let fileURL = docsURL.appendingPathComponent("notes.txt")
let text = "Qeydin məzmunu"
try text.write(to: fileURL, atomically: true, encoding: .utf8)

iCloud Drive və cihazlar arasında sinxronizasiya

iCloud Drive eyni istifadəçinin cihazları arasında Documents-dən faylları sinxronizasiya etməyə imkan verir. Sinxronizasiyanı aktivləşdirmək üçün tətbiq versiyalama və konfliktlərin həllini avtomatik idarə edən NSDocument və ya UIDocument API-lərindən istifadə etməlidir. Alternativ yanaşma — sinxronizasiya üzərində daha çevik nəzarət təmin edən, lakin CloudKit Dashboard-da konfiqurasiya tələb edən CloudKit ilə iCloud-dan istifadə etməkdir. iCloud Drive-dan istifadə edərkən redaktə konfliktlərini (merge və ya last-write-wins) düzgün idarə etdiyinizə və tətbiq interfeysi vasitəsilə istifadəçini sinxronizasiya vəziyyəti barədə məlumatlandırdığınıza əmin olun. iCloud ani sinxronizasiyaya zəmanət vermir — gecikmə fayl ölçüsündən və əlaqə keyfiyyətindən asılı olaraq bir neçə saniyədən bir neçə dəqiqəyə qədər ola bilər. Kritik vacib məlumatlar üçün tranzaksiya yazısı və versiyalamadan istifadə edin ki, konflikt zamanı faylın əvvəlki versiyasını bərpa etmək mümkün olsun.

Cache Directory-dən fərqlər və ən yaxşı təcrübələr

Düzgün seçim Documents Directory ilə Cache Directory arasında istifadəçi məlumatlarının saxlanmasının etibarlılığını müəyyən edir. Seçimdə səhv ya məlumat itkisinə (vacib fayllar keşdə saxlanılırsa), ya da ehtiyat nüsxənin daşmasına (müvəqqəti fayllar Documents-də saxlanılırsa) gətirib çıxarır.

Ən yaxşı təcrübələr sənədlər kataloqundan istifadə bir neçə əsas qaydanı əhatə edir. Birincisi, bu kataloqdan faylları silməzdən əvvəl həmişə istifadəçidən təsdiq istəyin. Keşdən fərqli olaraq, sənədin silinməsi istifadəçi məzmununun geri qaytarılmayan itkisinə səbəb ola bilər. İkincisi, fayl versiyalamasını tətbiq edin: mövcud faylın üzərinə yazarkən əvvəlki versiyanı _backup suffiksi ilə saxlayın və ya Snapshot mexanizmlərindən istifadə edin. Üçüncüsü, istifadəçiyə sənədlər kataloqundan faylları görmək, adını dəyişmək, silmək və ixrac etmək üçün interfeys təqdim edin. iOS-da Documents-dən fayllar avtomatik olaraq Files-də göstərilir, Android-də isə öz fayl menecerinizi tətbiq etməli və ya üçüncü tərəf kitabxanalarından istifadə etməlisiniz.

Tətbiq yeniləmə zamanı məlumat miqrasiyasına xüsusi diqqət yetirin. Əgər yeni versiya fayl saxlama strukturunu dəyişirsə (məsələn, məlumatları bir alt kataloqdan digərinə köçürür və ya fayl formatını dəyişir), yeniləmədən sonra ilk işə salınma zamanı birdəfəlik miqrasiyanı tətbiq edin. Məlumat sxeminin versiya nömrəsini SharedPreferences-da saxlayın və uyğunsuzluq olduqda miqrasiyanı işə salın. Miqrasiya tamamlanana qədər köhnə faylları silməyin — nasazlıq halında istifadəçi məlumatlarını itirməməlidir. Miqrasiya format çevrilməsini əhatə edirsə (məsələn, JSON-dan SQLite-ə keçid), orijinal faylları miqrasiya tarixi ilə ayrıca kataloqda ehtiyat nüsxə kimi saxlayın. İstifadəçi Apple Human Interface Guidelines-in tövsiyə etdiyi kimi, yeniləmədən sonra ilk 30 gün ərzində tətbiq parametrləri vasitəsilə dəyişiklikləri geri qaytara bilməlidir.