Direktoryo ng mga Dokumento sa Mobile App — ano ito, layunin at paano ayusin ang pag-iimbak

Ano ang direktoryo ng mga dokumento ng app?

Ang direktoryo ng mga dokumento — isang espesyalisadong imbakan sa loob ng sandbox ng app, na idinisenyo para sa permanenteng pag-iimbak ng mga file ng user. Hindi tulad ng cache, ang mga file sa direktoryong ito ay itinuturing na mahalaga para sa user: hindi tinatanggal ng system kapag kulang ang espasyo, napananatili sa pag-update ng app, at naba-backup sa pag-sync ng device. Sa iOS, ang direktoryo ng Documents ay bahagi ng container ng Sandbox at awtomatikong kasama sa pagba-backup ng iCloud. Sa Android walang direktang katumbas — ang katumbas ay context.filesDir, na idinisenyo din para sa mga permanenteng file, ngunit walang built-in na mekanismo ng pagba-backup.

Ang pagkakaiba sa pagitan ng direktoryo ng mga dokumento at panloob na imbakan (Internal Storage) sa Android ay minimal: pareho nasa sandbox ng app, pareho tinatanggal sa pag-uninstall, pareho hindi maa-access ng ibang apps. Ang pangunahing pagkakaiba ay semantiko: Ipinapalagay ng Documents Directory na ang mga file ay nilikha o ini-import ng user, habang ang Internal Storage ay maaaring maglaman ng panloob na mga file ng app (mga database, configuration). Sa iOS ang pagkakaiba ay mas makabuluhan: Ang Documents ay awtomatikong naba-backup, ngunit ang Library/Application Support ay hindi. Nakakaapekto ito sa estratehiya ng pag-iimbak: sa Documents ilagay lamang ang gusto ng user na ibalik sa isang bagong device, at sa Application Support — panloob na data na maaaring muling likhain ng app.

Ang arkitektura ng sandbox ay nagsisiguro na ang ibang mga app ay walang access sa direktoryo ng mga dokumento ng iyong app. Sa iOS, ang access sa Documents ng ibang apps ay imposible nang walang jailbreak. Sa Android, ang root access ay nagpapahintulot sa pagbabasa ng filesDir ng anumang app, kaya ang kumpidensyal na data (mga token, encryption key) ay dapat na karagdagang protektahan gamit ang EncryptedSharedPreferences o EncryptedFile mula sa AndroidX Security library.

Anong data ang iniimbak sa direktoryo ng mga dokumento

Sa direktoryo ng mga dokumento dapat ilagay ang data na mahalaga para sa user at dapat available pagkatapos ng pag-restart ng app o pagpapanumbalik ng device. Hindi lahat ng file ay angkop para sa pag-iimbak sa direktoryong ito — ang pagpili ay depende sa uri ng data at senaryo ng paggamit.

Mga dokumento at file ng user

Ang mga file ng user — pangunahing nilalaman ng direktoryo ng mga dokumento. Maaaring ito ay mga text document na ginawa sa editor, mga larawang kuha ng camera ng app, mga na-export na PDF report, audio recording, mga tala. Bawat naturang file ay ginawa ng user o sa kanyang kahilingan at dapat available sa anumang oras. Sa iOS, ang mga file mula sa Documents ay ipinapakita sa system app na Files, na nagpapahintulot sa user na pamahalaan ang mga ito sa pamamagitan ng standard file manager. Sa Android ay walang katulad na pagpapakita — ang app ay dapat magbigay mismo ng interface para sa pagtingin ng mga naka-save na file.

Mga database at setting ng app

Ang mga SQLite database at mga file ng setting ay karaniwang iniimbak sa tabi ng direktoryo ng mga dokumento, ngunit hindi sa loob nito. Sa iOS, ang mga database ay inilalagay sa Library/Application Support, dahil hindi dapat ipakita sa Files app at i-backup nang hiwalay. Sa Android, ang mga database ay default na nilikha sa /data/data/<package>/databases/ sa pamamagitan ng Room o SQLiteOpenHelper. Kung ang database ay naglalaman ng nilalaman ng user (mga tala, diary, financial record), maaari itong ilagay sa filesDir upang matiyak ang pagba-backup sa pamamagitan ng system. Pinapayagan ng Room na tukuyin ang custom na direktoryo para sa pag-iimbak ng database sa pamamagitan ng callback na RoomDatabase.Builder.

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

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

Na-export at na-import na data

Ang mga file na ini-import ng user mula sa ibang apps o ina-export mula sa iyong app, ay dapat ding i-save sa direktoryo ng mga dokumento. Sa iOS, ang pag-import sa pamamagitan ng UIDocumentPickerViewController ay awtomatikong naglalagay ng kopya ng file sa Documents kapag ginagamit ang parameter na asCopy: true. Sa Android, ang pag-import sa pamamagitan ng SAF dialog ay gumagawa din ng kopya ng file sa sandbox ng app. Sa pag-export ng data (halimbawa, paggawa ng CSV file na may mga contact), i-save muna ang file sa Documents/filesDir, pagkatapos ay alukin ang user na ibahagi ito sa pamamagitan ng Share Sheet. Tinitiyak nito na kahit nakalimutan ng user na i-save ang file pagkatapos ipadala, mananatili ang kopya sa app para sa susunod na paggamit.

Paano magtrabaho sa direktoryo ng mga dokumento sa Android

Sa Android, ang mga function ng direktoryo ng mga dokumento ay ginagampanan ng context.filesDir. Bilang karagdagan, ang direktoryo na context.externalFilesDir ay available sa SD card, ngunit hindi nito ginagarantiyahan ang pagpapanatili ng data. Suriin natin ang mga pangunahing paraan ng pagtatrabaho sa mga direktoryong ito.

Access at pamamahala ng mga file sa pamamagitan ng filesDir

filesDir — ang pangunahing direktoryo para sa mga permanenteng file ng app sa Android. Ito ay nasa sandbox ng app at ganap na tinatanggal sa pag-uninstall. Upang makakuha ng instance ng File, gamitin ang context.filesDir, na nagbabalik ng landas sa direktoryong /data/data/<package>/files/. Para sa paglikha at pagbabasa ng mga file, gamitin ang standard na File operations sa Java/Kotlin o Context methods na openFileInput() at openFileOutput(), na tumatanggap ng pangalan ng file at nagbabalik ng FileInputStream/FileOutputStream. Ang paraang openFileOutput() ay awtomatikong lumilikha ng file sa filesDir kung wala pa ito at pinapayagang tukuyin ang mode ng access: MODE_PRIVATE (kasalukuyang app lamang), MODE_APPEND (pagdaragdag) o MODE_WORLD_READABLE (luma na, hindi ginagamit mula noong API 24+).

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()
}

Mga katangian ng pag-iimbak sa Android 10+

Sa Android 10+, ang modelong Scoped Storage ay hindi nakakaapekto sa filesDir — ang access sa sariling sandbox ng app ay nananatiling buo. Lahat ng operasyon ng pagbasa at pagsulat sa loob ng filesDir ay hindi nangangailangan ng karagdagang pahintulot. Gayunpaman, sa pagtatangkang i-access ang mga file ng ibang app sa pamamagitan ng filesDir, makakatanggap ka ng exception. Para sa pagpapalitan ng file, gamitin ang FileProvider, na lumilikha ng pansamantalang content URI para sa pagpapadala ng file sa ibang app. Ang FileProvider ay idineklara sa AndroidManifest.xml sa pamamagitan ng tag na <provider> at kino-configure sa XML file ng mga landas. Ito ang standard na mekanismo para sa paglipat ng file sa pagitan ng mga app, na ginagamit halimbawa sa pagpapadala ng larawan sa pamamagitan ng Intent na may ACTION_SEND.

Paano magtrabaho sa direktoryo ng mga dokumento sa iOS

Sa iOS, ang Documents Directory ay bahagi ng Sandbox container ng app na may espesyal na katayuan. Ang mga file mula sa direktoryong ito ay awtomatikong kasama sa pagba-backup ng iCloud, ipinapakita sa Files app, at napananatili sa pag-update ng app sa pamamagitan ng App Store.

Documents Directory at pagba-backup

Awtomatikong pagba-backup ng Documents — pangunahing bentahe ng iOS. Kapag ikinonekta ng user ang device sa iTunes o i-on ang iCloud Backup, lahat ng file mula sa Documents/ ay kinokopya sa backup. Sa pagpapanumbalik sa isang bagong device, natatanggap ng user ang lahat ng kanyang mga file nang walang karagdagang aksyon. Gayunpaman, ang bentaheng ito ay nagiging disadvantage kung ang app ay nag-iimbak ng malaking dami ng data sa Documents: tumataas ang oras ng pagba-backup at ang espasyo sa iCloud ay maaaring mabilis na maubos. Kaya sa Documents dapat lamang i-save ang mga file na talagang kailangan ng user sa pagpapanumbalik. Ang mga pansamantalang file, cache, at data na maaaring muling likhain ay dapat nasa Caches o Library/Application Support. Inirerekomenda ng Apple na ibukod mula sa pagba-backup ang mga file na maaaring i-download muli mula sa internet, sa pamamagitan ng attribute na isExcludedFromBackup.

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

let fileURL = docsURL.appendingPathComponent("notes.txt")
let text = "Nilalaman ng tala"
try text.write(to: fileURL, atomically: true, encoding: .utf8)

iCloud Drive at pag-sync sa pagitan ng mga device

iCloud Drive ay nagpapahintulot sa pag-sync ng mga file mula sa Documents sa pagitan ng mga device ng parehong user. Para i-activate ang pag-sync, dapat gamitin ng app ang API na NSDocument o UIDocument, na awtomatikong namamahala ng pag-version at paglutas ng conflict. Alternatibong approach — paggamit ng iCloud sa CloudKit, na nagbibigay ng mas flexible na kontrol sa pag-sync, ngunit nangangailangan ng configuration sa CloudKit Dashboard. Sa paggamit ng iCloud Drive, siguraduhing tama mong pinangangasiwaan ang mga conflict sa pag-edit (merge o last-write-wins) at ipaalam sa user ang tungkol sa status ng pag-sync sa pamamagitan ng interface ng app. Hindi ginagarantiyahan ng iCloud ang instant na pag-sync — ang pagkaantala ay maaaring mula sa ilang segundo hanggang ilang minuto depende sa laki ng file at kalidad ng koneksyon. Para sa kritikal na mahalagang data, gumamit ng transaksyonal na pagsulat at pag-version, upang sa conflict ay maibalik ang dating bersyon ng file.

Mga Pagkakaiba mula sa Cache Directory at pinakamahuhusay na kasanayan

Ang tamang pagpili sa pagitan ng Documents Directory at Cache Directory ay tumutukoy sa pagiging maaasahan ng pag-iimbak ng data ng user. Ang pagkakamali sa pagpili ay humahantong sa pagkawala ng data (kung ang mahahalagang file ay iniimbak sa cache) o sa pag-apaw ng backup (kung ang pansamantalang file ay iniimbak sa Documents).

Pinakamahuhusay na kasanayan sa paggamit ng direktoryo ng mga dokumento ay may kasamang ilang pangunahing tuntunin. Una, palaging humingi ng kumpirmasyon ng user bago tanggalin ang mga file mula sa direktoryong ito. Hindi tulad ng cache, ang pagtanggal ng dokumento ay maaaring humantong sa hindi na mababawi na pagkawala ng nilalaman ng user. Pangalawa, ipatupad ang pag-version ng file: sa pag-overwrite ng umiiral na file, panatilihin ang dating bersyon na may suffix na _backup o gumamit ng Snapshot mechanisms. Pangatlo, bigyan ang user ng interface para sa pagtingin, pagpapalit ng pangalan, pagtanggal, at pag-export ng mga file mula sa direktoryo ng mga dokumento. Sa iOS, ang mga file mula sa Documents ay awtomatikong ipinapakita sa Files, sa Android kailangan mong ipatupad ang sarili mong file manager o gumamit ng third-party na library.

Bigyang-pansin ang pag-migrate ng data sa pag-update ng app. Kung ang bagong bersyon ay nagbabago ng istruktura ng pag-iimbak ng file (halimbawa, naglilipat ng data mula sa isang subdirectory patungo sa isa pa o nagbabago ng format ng file), ipatupad ang isang beses na migration sa unang paglunsad pagkatapos ng pag-update. Itago ang numero ng bersyon ng schema ng data sa SharedPreferences at sa hindi pagkakatugma, simulan ang migration. Huwag tanggalin ang mga lumang file hanggang sa makumpleto ang migration — sa kaso ng pagkasira, hindi dapat mawalan ng data ang user. Kung ang migration ay may kasamang conversion ng format (halimbawa, paglipat mula JSON patungong SQLite), panatilihin ang orihinal na mga file bilang backup sa isang hiwalay na direktoryo na may petsa ng migration. Ang user ay dapat magkaroon ng kakayahang i-undo ang mga pagbabago sa pamamagitan ng mga setting ng app sa unang 30 araw pagkatapos ng pag-update, gaya ng inirerekomenda ng Apple Human Interface Guidelines.