DocumentProvider — ما هو، إنشاء موفر والعمل مع الملفات

ما هو DocumentProvider؟

DocumentsProvider هي فئة أساسية في Android ترث ContentProvider، وتسمح للتطبيق بتوفير ملفاته للتطبيقات الأخرى من خلال واجهة SAF للنظام. ينشئ الموفر نظام ملفات افتراضي يراه المستخدم في مربع حوار اختيار المستندات.

ينظم كل موفر الملفات في جذور (roots) — نقاط دخول عالية المستوى. على سبيل المثال، Google Drive له جذور «قرصي» و «مشترك معي.» داخل الجذر، يعيد الموفر شجرة من المستندات، حيث كل مستند هو ملف أو دليل بنوع MIME وحجم وتواريخ محددة.

DocumentProvider هو جزء من حزمة android.provider ومتوفر بدءًا من Android 4.4 (API 19). يُستخدم الموفر من قبل الخدمات السحابية ومديري كلمات المرور وتطبيقات الملاحظات وأي برامج تخزن الملفات بتنسيقها الخاص.

كيفية إنشاء DocumentProvider مخصص

إنشاء DocumentProvider خاص بك يبدأ بتوسيع فئة DocumentsProvider وتنفيذ أربعة أساليب إلزامية. يحدد الموفر بنية الملفات التي تظهر في منتقي SAF للنظام عند اختيار الملفات.

الطريقة الأولى هي queryRoots، التي تعيد مؤشرًا بالأعمدة Root.COLUMN_ROOT_ID و Root.COLUMN_TITLE و Root.COLUMN_SUMMARY و Root.COLUMN_FLAGS. يمكن لكل جذر دعم الأعلام: FLAG_SUPPORTS_CREATE و FLAG_SUPPORTS_SEARCH و FLAG_SUPPORTS_IS_CHILD.

الطريقة الإلزامية الثانية هي queryChildDocuments، التي تعيد المستندات الفرعية لـ URI محدد. تُستدعى هذه الطريقة عندما يفتح المستخدم دليلاً في المنتقي. يحتوي كل مستند على الأعمدة: Document.COLUMN_DOCUMENT_ID و COLUMN_DISPLAY_NAME و COLUMN_MIME_TYPE و COLUMN_SIZE و COLUMN_LAST_MODIFIED.

الأساليب الإلزامية لـ DocumentsProvider

DocumentsProvider يتطلب تنفيذ أربعة أساليب تشكل بنية الملفات للمنتقي. بدونها، لن يعمل الموفر — لن يتمكن مربع حوار SAF للنظام من عرض الملفات.

• queryRoots — تعيد نقاط الدخول الجذرية للتخزين. كل جذر ممثل بصف في المؤشر مع معرف واسم وأيقونة.
• queryDocument — تعيد مستندًا واحدًا بمعرفه. يُستخدم للحصول على معلومات حول ملف معين.
• queryChildDocuments — تعيد المستندات الفرعية لـ URI الدليل الأب المحدد.
• openDocument — يفتح مستندًا بمعرفه ويعيد ParcelFileDescriptor للقراءة أو الكتابة.

بالإضافة إلى ذلك، يمكن تنفيذ createDocument لإنشاء ملفات جديدة و deleteDocument للحذف و renameDocument لإعادة التسمية. تتطلب هذه الأساليب العلم FLAG_SUPPORTS_CREATE في الجذر.

تسجيل الموفر في AndroidManifest

DocumentProvider يُسجل في AndroidManifest.xml كـ ContentProvider عادي مع مرشح intent وأعلام إضافية. يجب حماية الموفر من الوصول المباشر عبر الإذن — يُوصى باستخدام android:exported="true" مع إذن صريح.

<provider
    android:name=".provider.CustomDocumentProvider"
    android:authorities="com.example.app.documents"
    android:exported="true"
    android:grantUriPermissions="true"
    android:permission="android.permission.MANAGE_DOCUMENTS">
    <intent-filter>
        <action
            android:name="android.content.action.DOCUMENTS_PROVIDER" />
    </intent-filter>
    <meta-data
        android:name="android.content.documents.roots"
        android:resource="@xml/file_paths" />
</provider>

العلم grantUriPermissions يسمح لـ SAF بتفويض حقوق الوصول مؤقتًا للتطبيق المستدعي. يجب أن يكون سمة authorities فريدًا — عادةً ما يُستخدم اسم الحزمة مع اللاحقة .documents. يُوصى أيضًا بتحديد meta-data مع مورد XML لتكوين الجذور.

مثال كود: تنفيذ DocumentsProvider

تنفيذ DocumentsProvider يتطلب إرجاع ParcelFileDescriptor من طريقة openDocument. للملفات المحلية يُستخدم ParcelFileDescriptor.open، للملفات السحابية — ParcelFileDescriptor.open مع Pipe للتدفق. يجب أن يعالج الكود أخطاء الوصول والملفات المفقودة.

class CustomDocumentProvider : DocumentsProvider() {

    override fun queryRoots(): Cursor {
        val matrix = MatrixCursor(Root.COLUMNS)
        matrix.newRow().add(Root.COLUMN_ROOT_ID, "local")
            .add(Root.COLUMN_TITLE, "My Files")
            .add(Root.COLUMN_SUMMARY, "Local documents")
            .add(Root.COLUMN_FLAGS, Root.FLAG_SUPPORTS_CREATE)
        return matrix
    }

    override fun openDocument(
        documentId: String, flags: Int, cursor: CancellationSignal?
    ): ParcelFileDescriptor {
        val file = File(context.filesDir, documentId)
        val accessMode = ParcelFileDescriptor.parseMode(flags)
        return ParcelFileDescriptor.open(file, accessMode)
    }
}

معالجة المستندات الافتراضية

يمكن لـ DocumentProvider إرجاع ملفات افتراضية — مستندات لا توجد كملفات منفصلة على القرص. على سبيل المثال، يمكن تقديم ملاحظة من قاعدة البيانات كـ PDF افتراضي. يستخدم هذا نوع MIME مع العلم FLAG_VIRTUAL_DOCUMENT، ويقوم openDocument بتحويل البيانات إلى التنسيق المطلوب قبل الإرسال.

DocumentProvider في iOS: UIDocumentPickerViewController

iOS لديه آلية مماثلة — UIDocumentPickerViewController، الذي يوفر أيضًا واجهة موحدة لاختيار الملفات. ومع ذلك، في iOS يتم تنفيذ موفر المستندات من خلال UIDocumentPickerDelegate وملحقات التطبيقات (App Extensions) من نوع Document Provider.

على عكس Android DocumentsProvider، لا يتطلب iOS UIDocumentPickerViewController إنشاء موفر مخصص للملفات المحلية — منتقي النظام يدعم iCloud Drive والتخزين المحلي افتراضيًا. يتم تسجيل الخدمات السحابية الخارجية من خلال ملحق Document Provider بمفتاح Info.plist NSExtensionFileProviderDocumentInterface.

الفرق الرئيسي: في Android، يتم استدعاء DocumentProvider بنشاط عبر Intent SAF ويجب عليه تنفيذ التنقل بنفسه. في iOS، يستخدم UIDocumentPickerViewController متصفح ملفات نظام مدمج، وموفر الملحق مسؤول فقط عن توفير المحتوى عند الطلب.