Documents Directory: bu nədir, məqsədi və fayllara giriş

iOS-da Documents Directory nədir?

Documents Directory — iOS tətbiqinin sandbox daxilində, istifadəçi məlumatlarını saxlamaq üçün nəzərdə tutulmuş kataloq. Hər tətbiq öz izolə edilmiş sandbox alır və Documents Caches, tmp və Library ilə yanaşı əsas kataloqlardan biridir.

iOS ciddi sandbox istifadə edir: tətbiq xüsusi icazələr olmadan digər tətbiqlərin fayl sisteminə və sistem kataloqlarına çıxış əldə edə bilməz. Documents Directory — məzmunu istifadəçinin iTunes File Sharing vasitəsilə görə biləcəyi yeganə kataloq (Info.plist-də müvafiq UIFileSharingEnabled açarı aktiv edildikdə).

Apple WWDC 2023 məlumatlarına görə, App Store-dakı tətbiqlərin 85%-dən çoxu ən azı bir növ istifadəçi məlumatını saxlamaq üçün Documents Directory-dən istifadə edir — ixrac edilmiş PDF-lərdən tutmuş oyun fayllarına və ixrac edilmiş şəkillərə qədər.

Tərtibatçı başa düşməlidir: Documents-dəki fayllar iCloud və iTunes ehtiyat nüsxəsına avtomatik olaraıç daxil edilir. Tətbiq Documents-də böyük həcmdə bərpa oluna bilən məlumatları (məsələn, şəkil keşişi və ya müvəqqəti fayllar) saxlayırsa, bu, istifadəçinin iCloud yaddaşında əsaslandırılmamış yer sərfiyyatına səbəb olacaq.

Documents Directory yolunu necə əldə etmək

Swift-də Documents Directory yolu FileManager vasitəsilə əldə edilir. Apple, iOS-un müasir imkanları ilə daha yaxşı uyğunluq üçün string-based əvəzinə URL-based API-dən istifadə etməyi tövsiyə edir.

import Foundation

let fileManager = FileManager.default
guard let documentsURL = fileManager.urls(
    for: .documentDirectory,
    in: .userDomainMask
).first else { return }

// Documents-də fayl yarat
let fileURL = documentsURL.appendingPathComponent("report.pdf")
let data = Data("Hello, world!".utf8)
try data.write(to: fileURL)

Objective-C NSSearchPathForDirectoriesInDomains — URL əvəzinə sətir yolu qaytaran köhnə, lakin hələ dəstəklənən yanaşmanı istifadə edir.

@import Foundation;

NSArray *paths = NSSearchPathForDirectoriesInDomains(
    NSDocumentDirectory,
    NSUserDomainMask,
    YES
);
NSString *documentsPath = paths.firstObject;
NSString *filePath = [documentsPath stringByAppendingPathComponent:@"report.pdf"];

Swift-də müasir layihələr FileManager.urls istifadə etməlidir, çünki bu metod URL qaytarır, sətir yox, bu da yol kodlaşdırması ilə bağlı səhvlər riskini azaldır və kodu daha töküm təhlükəsiz edir.

Documents-də hansı məlumatları saxlamaq

Documents Directory istifadəçi tərəfindən yaradılan və ya istifadəçiyə açıq şəkildə lazım olan məlumatlar üçün nəzərdə tutulmuşdur. Apple bu kataloqda yerləşdirilə biləcək bir neçə kateqoriyanı ayırır.

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

istifadəçinin yaratdığı və ya idxal etdiyi fayllar — mətn sənədləri, PDF, şəkillər, ixrac edilmiş hesabatlar, ehtiyat nüsxə faylları. Bu məlumatlar istifadəçi üçün birbaşa dəyərə malikdir və onların itirilməsi kritik olardı.

Oyun yaddaşları və tətbiq vəziyyəti

Oyun yaddaşları, tətbiq vəziyyəti faylları, ixrac edilmiş layihələr — istifadəçinin tətbiqi yenidən yüklədikdən sonra bərpa etməyi gözlədiyi hər şey. Bununla belə, kritik məlumatlar üçün əlavə olaraıç iCloud Key-Value Storage və ya iCloud sinxronizasiyası ilə Core Data istifadə etmək tövsiyə olunur.

Əsas meyar: məlumatlar şəbəkədən bərpa oluna bilirsə və ya yenidən yaradıla bilərsə, onların yeri Caches-dədir, Documents-də yox. Documents-dəki hər giqabayt istifadəçinin iCloud ehtiyat nüsxəsində bir giqabaytdır.

Ehtiyat nüsxə və sinxronizasiya

iOS cihaz iTunes-a qoşulduqda və ya iCloud ilə sinxronizasiya zamanı Documents Directory-nin məzmununu avtomatik olaraıç ehtiyat nüsxəyə daxil edir. Bu davranışı kataloq səviyyəsində söndürmək mümkün deyil — yalnız fayl üzrə NSURLIsExcludedFromBackupKey atributu vasitəsilə.

iOS 5.0-dan başlayaraıç, Apple Documents-də böyük həcmdə bərpa oluna bilən məlumatlar saxlayan tətbiqləri rədd etməyə başladı. Apple tövsiyəsi: yenidən yüklənə bilən fayllar ehtiyat nüsxəsindən xaric etmə bayrağı ilə Caches Directory-də saxlanmalıdır.

import Foundation

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

// Faylı iCloud ehtiyat nüsxəsindən xaric et
var resourceValues = URLResourceValues()
resourceValues.isExcludedFromBackup = true

var fileURL = documentsURL.appendingPathComponent("cached_data.json")
try fileURL.setResourceValues(resourceValues)

iCloud sinxronizasiyası, tətbiq iCloud Documents istifadə edirsə, NSUbiquitousContainer vasitəsilə işləyir. Bu halda Documents Directory-dən fayllar avtomatik olaraıç istifadəçinin cihazları arasında sinxronlaşdırılır. iCloud olmayan tətbiqlər üçün sinxronizasiya ehtiyat nüsxə ilə məhdudlaşır.

Documents Directory vs Caches Directory

Documents və Caches arasındakı fərq yeni başlayan iOS tərtibatçıları arasında ən çox yayılmış yanlış anlayışlardan biridir. Əsas fərq: sistem yer boşaltmaq üçün istənilən an Caches-dən faylları silə bilər, lakin istifadəçinin xəbəri olmadan Documents-ə heç vaxt toxunmur.

Apple Developer Documentation (2024) məlumatlarına görə, Documents Directory-nin səhv istifadəsi tətbiqlərin rəy zamanı rədd edilməsinin tez-tez səbəblərindən biridir: tətbiq Documents-də bərpa oluna bilən bir neçə meqabaytdan çox məlumat saxlayırsa, Apple onların Caches-ə köçürülməsini və ya NSURLIsExcludedFromBackupKey tətbiq edilməsini tövsiyə edir.

Praktik qayda: istifadəçi faylın itirilməsindən üzüləcəksə — Documents-də saxla. Faylı yenidən yükləmək və ya yaratmaq olarsa — Caches-də saxla.

Documents ilə işləmək üçün ən yaxşı təcrübələr

Təcrübəli iOS tərtibatçıları tətbiqin həyat dövriyyəsinin bütün mərhələlərində Documents Directory ilə bağlı problemlərdən qaçmağa kömək edən bir neçə qayda hazırlamışlar.

Kataloq ölçüsünün monitorinqi

Müzəmmədən FileManager.enumerator(at:includingPropertiesForKeys:) vasitəsilə Documents Directory ölçüsünü yoxlayın. Əgər ölçü istifadəçi məlumatları olmayan məlumatlar üçün 100 MB-ı keçərsə, bu, anbar arxitekturasını yenidən nəzərdən keçirmək üçün səbəbdir.

Bərpa oluna bilən faylların ehtiyat nüsxəsindən xaric edilməsi

Şəbəkədən yenidən yüklənə bilən bütün fayllar üçün isExcludedFromBackup = true təyin edin. Bu, istifadəçinin iCloud yaddaşına yükü azaldır və tətbiqin App Review tərəfindən rədd edilmə riskini azaldır.

Yeniləmə zamanı miqrasiya

Documents-də məlumat formatı dəyişdirilərkən miqrasiyanı nəzərdə tutun: yeni faylların düzgün yaradıldığına əmin olana qədər köhnə faylları silməyin. Versiyaya xas alt kataloqlardan istifadə edin.

import Foundation

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

let versionDir = documentsURL.appendingPathComponent("v2")
try FileManager.default.createDirectory(
    at: versionDir,
    withIntermediateDirectories: true
)

Bu təcrübələrə riayət etmək istifadəçi məlumatlarının itirilməsi riskini azaldır, iCloud ehtiyat nüsxəsinin ölçüsünü kiçildir və App Store-da rəy keçmək prosesini asanlaşdırır.