Documents Directory: ano ito, layunin at access sa mga file

Ano ang Documents Directory sa iOS?

Documents Directory — ay isang direktoryo sa loob ng sandbox ng iOS application, na nilalayon para sa pag-iimbak ng data ng gumagamit na dapat mapanatili sa pagitan ng mga paglunsad at ma-access ng gumagamit. Ang bawat application ay nakakakuha ng sarili nitong nakahiwalay na sandbox, at ang Documents ay isa sa mga pangunahing direktoryo kasama ng Caches, tmp, at Library.

Gumagamit ang iOS ng mahigpit na sandbox: ang application ay walang access sa file system ng iba pang mga application at system directory nang walang mga espesyal na pahintulot. Documents Directory — ang tanging direktoryo na ang nilalaman ay maaaring matingnan ng gumagamit sa pamamagitan ng iTunes File Sharing (kapag na-activate ang kaukulang key na UIFileSharingEnabled sa Info.plist).

Ayon sa datos ng Apple WWDC 2023, mahigit 85% ng mga application sa App Store ang gumagamit ng Documents Directory para mag-imbak ng kahit isang uri ng data ng gumagamit — mula sa mga na-export na PDF hanggang sa mga naka-save na file ng laro at mga na-export na larawan.

Dapat maunawaan ng developer: ang mga file sa Documents ay awtomatikong kasama sa backup ng iCloud at iTunes. Kung ang application ay nag-iimbak ng malaking dami ng data na maaaring maibalik sa Documents (halimbawa, cache ng mga larawan o pansamantalang file), ito ay hahantong sa hindi makatuwirang paggamit ng espasyo sa iCloud storage ng gumagamit.

Paano makuha ang path sa Documents Directory

Sa Swift, ang path sa Documents Directory ay makukuha sa pamamagitan ng FileManager. Inirerekomenda ng Apple ang paggamit ng URL-based API sa halip na string-based para sa mas mahusay na compatibility sa mga modernong kakayahan ng iOS.

import Foundation

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

// Gumawa ng file sa Documents
let fileURL = documentsURL.appendingPathComponent("report.pdf")
let data = Data("Hello, world!".utf8)
try data.write(to: fileURL)

Gumagamit ang Objective-C ng NSSearchPathForDirectoriesInDomains — isang mas luma ngunit suportado pa ring approach na nagbabalik ng string path sa halip na URL.

@import Foundation;

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

Ang mga modernong proyekto sa Swift ay dapat gumamit ng FileManager.urls dahil ang metodong ito ay nagbabalik ng URL, hindi string, na nagbabawas ng panganib ng mga error sa pag-encode ng path at ginagawang mas type-safe ang code.

Anong data ang iimbak sa Documents

Documents Directory ay nilalayon para sa data na nilikha ng gumagamit o kailangan ng gumagamit sa tahasang anyo. Itinatampok ng Apple ang ilang kategorya na angkop para sa direktoryong ito.

Mga dokumento at file ng gumagamit

Mga file na ginagawa o ini-import ng gumagamit — mga text document, PDF, larawan, na-export na ulat, backup file. Ang data na ito ay may direktang halaga para sa gumagamit, at ang pagkawala nito ay magiging kritikal.

Mga save ng laro at estado ng application

Mga save ng laro, mga file ng estado ng application, mga na-export na proyekto — lahat ng inaasahan ng gumagamit na maibalik pagkatapos muling i-install ang application. Gayunpaman, para sa kritikal na data, inirerekomenda ring gamitin ang iCloud Key-Value Storage o Core Data na may iCloud synchronization.

Ang pangunahing pamantayan: kung ang data ay maaaring maibalik mula sa network o muling likhain — ang lugar nito ay nasa Caches, hindi sa Documents. Bawat gigabyte sa Documents ay isang gigabyte sa iCloud backup ng gumagamit.

Backup at synchronization

iOS ay awtomatikong isinasama ang nilalaman ng Documents Directory sa backup kapag ang device ay konektado sa iTunes o kapag nag-sync sa iCloud. Ang pag-uugaling ito ay hindi maaaring i-off sa antas ng direktoryo — tanging file-por-file sa pamamagitan ng attribute na NSURLIsExcludedFromBackupKey.

Simula sa iOS 5.0, sinimulan ng Apple na tanggihan ang mga application na nag-iimbak ng malaking dami ng data na maaaring maibalik sa Documents. Rekomendasyon ng Apple: ang mga file na maaaring i-download muli ay dapat itago sa Caches Directory na may flag ng pagbubukod mula sa backup.

import Foundation

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

// Ibukod ang file mula sa iCloud backup
var resourceValues = URLResourceValues()
resourceValues.isExcludedFromBackup = true

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

Gumagana ang iCloud synchronization sa pamamagitan ng NSUbiquitousContainer kung ang application ay gumagamit ng iCloud Documents. Sa kasong ito, ang mga file mula sa Documents Directory ay awtomatikong nasi-sync sa pagitan ng mga device ng gumagamit. Para sa mga application na walang iCloud, ang synchronization ay limitado sa backup.

Documents Directory vs Caches Directory

Ang pagkakaiba sa pagitan ng Documents at Caches — isa sa mga pinakakaraniwang maling kuru-kuro sa mga baguhang iOS developer. Ang pangunahing pagkakaiba: ang system ay maaaring anumang oras na tanggalin ang mga file mula sa Caches upang magbakante ng espasyo, ngunit hindi kailanman ginagalaw ang Documents nang walang kaalaman ng gumagamit.

Ayon sa Apple Developer Documentation (2024), ang hindi wastong paggamit ng Documents Directory — isa sa mga karaniwang dahilan ng pagtanggi ng application sa review: kung ang application ay nag-iimbak ng higit sa ilang megabyte ng data na maaaring maibalik sa Documents, inirerekomenda ng Apple na ilipat ang mga ito sa Caches o ilapat ang NSURLIsExcludedFromBackupKey.

Praktikal na tuntunin: kung ang gumagamit ay malulungkot sa pagkawala ng file — itago sa Documents. Kung ang file ay maaaring i-download muli o likhain — itago sa Caches.

Pinakamahuhusay na kasanayan sa pagtatrabaho sa Documents

Ang mga bihasang iOS developer ay bumuo ng ilang mga patakaran na tumutulong upang maiwasan ang mga problema sa Documents Directory sa lahat ng yugto ng lifecycle ng application — mula sa pag-develop hanggang sa pag-publish sa App Store.

Pagsubaybay sa laki ng direktoryo

Regular na suriin ang laki ng Documents Directory sa pamamagitan ng FileManager.enumerator(at:includingPropertiesForKeys:). Kung ang laki ay lumampas sa 100 MB para sa data na hindi data ng gumagamit — ito ay dahilan upang muling isaalang-alang ang arkitektura ng imbakan.

Pagbubukod ng mga nababawing file mula sa backup

Para sa lahat ng file na maaaring i-download muli mula sa network, itakda ang isExcludedFromBackup = true. Binabawasan nito ang karga sa iCloud storage ng gumagamit at binabawasan ang panganib ng pagtanggi ng application ng App Review.

Paglipat sa pag-update

Kapag binabago ang format ng data sa Documents, maglaan ng migration: huwag tanggalin ang mga lumang file hangga't hindi ka sigurado na ang mga bago ay naayos nang tama. Gumamit ng mga subdirectory na tiyak sa bersyon.

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
)

Ang pagsunod sa mga kasanayang ito ay nagbabawas ng panganib ng pagkawala ng data ng gumagamit, nagpapaliit ng laki ng iCloud backup, at nagpapadali sa pagdaan sa review sa App Store.