إعداد مشاركة الملفات

لتقديم ملف بأمان من تطبيقك إلى تطبيق آخر، يجب إعداد تطبيقك لتوفير اسم معرِّف آمن للملف، في شكل معرّف موارد منتظم (URI) للمحتوى. ينشئ المكوِّن FileProvider لنظام التشغيل Android معرّفات موارد منتظمة (URI) للمحتوى للملفات، بناءً على المواصفات التي تقدّمها في ملف XML. يوضّح لك هذا الدرس طريقة إضافة آلية تنفيذ FileProvider التلقائية إلى تطبيقك، وطريقة تحديد الملفات التي تريد عرضها للتطبيقات الأخرى.

ملاحظة: يشكّل الصف FileProvider جزءًا من مكتبة AndroidX الأساسية. للحصول على معلومات حول تضمين هذه المكتبة في تطبيقك، راجِع تعريف التبعيات.

تحديد FileProvider

يتطلب تحديد FileProvider لتطبيقك إدخالاً في البيان. يحدّد هذا الإدخال الصلاحية التي يجب استخدامها في إنشاء معرّفات الموارد المنتظمة للمحتوى، بالإضافة إلى اسم ملف XML الذي يحدِّد الأدلة التي يمكن لتطبيقك مشاركتها.

يوضّح المقتطف التالي كيفية إضافة العنصر <provider> الذي يحدد الفئة FileProvider والمرجع واسم ملف XML إلى البيان:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.example.myapp">
    <application
        ...>
        <provider
            android:name="androidx.core.content.FileProvider"
            android:authorities="com.example.myapp.fileprovider"
            android:grantUriPermissions="true"
            android:exported="false">
            <meta-data
                android:name="android.support.FILE_PROVIDER_PATHS"
                android:resource="@xml/filepaths" />
        </provider>
        ...
    </application>
</manifest>

في هذا المثال، تحدد السمة android:authorities مرجع معرّف الموارد المنتظم (URI) الذي تريد استخدامه لمعرّفات الموارد المنتظمة (URI) للمحتوى التي يتم إنشاؤها بواسطة FileProvider. في المثال، المرجع هو com.example.myapp.fileprovider. بالنسبة إلى تطبيقك الخاص، يجب تحديد مرجع مؤلف من القيمة android:package للتطبيق مع إلحاق السلسلة "fileprovider" به. لمزيد من المعلومات حول قيمة المرجع، راجِع الموضوع معرّفات الموارد المنتظمة (URI) للمحتوى ومستندات السمة android:authorities.

ويشير العنصر الفرعي <meta-data> في <provider> إلى ملف XML يحدّد الأدلة التي تريد مشاركتها. السمة android:resource هي مسار الملف واسمه، بدون الامتداد .xml.ويتم وصف محتوى هذا الملف في القسم التالي.

تحديد الأدلة القابلة للمشاركة

بعد إضافة FileProvider إلى بيان التطبيق، عليك تحديد الأدلة التي تحتوي على الملفات التي تريد مشاركتها. لتحديد الأدلة، ابدأ بإنشاء الملف filepaths.xml في الدليل الفرعي res/xml/ لمشروعك. في هذا الملف، حدِّد الأدلة من خلال إضافة عنصر XML لكل دليل. يعرض المقتطف التالي مثالاً على محتوى res/xml/filepaths.xml. يوضِّح المقتطف أيضًا طريقة مشاركة دليل فرعي من الدليل files/ في منطقة وحدة التخزين الداخلية:

<paths>
    <files-path path="images/" name="myimages" />
</paths>

في هذا المثال، تشارك العلامة <files-path> الأدلة في دليل files/ على وحدة التخزين الداخلية لتطبيقك. تشارك السمة path الدليل الفرعي images/ الخاص بـ files/. وتطلب السمة name من FileProvider إضافة مقطع المسار myimages إلى معرّفات الموارد المنتظمة (URI) للمحتوى للملفات في الدليل الفرعي files/images/.

يمكن أن يحتوي العنصر <paths> على عدة عناصر ثانوية يحدّد كل منها دليلاً مختلفًا لمشاركته. بالإضافة إلى العنصر <files-path>، يمكنك استخدام العنصر <external-path> لمشاركة الأدلة في مساحة تخزين خارجية، والعنصر <cache-path> لمشاركة الأدلة في دليل ذاكرة التخزين المؤقت الداخلي. لمعرفة المزيد من المعلومات عن العناصر الثانوية التي تحدّد الأدلة المشتركة، راجِع المستندات المرجعية FileProvider.

ملاحظة: ملف XML هو الطريقة الوحيدة التي يمكنك من خلالها تحديد الأدلة التي تريد مشاركتها، ولا يمكنك إضافة دليل بشكل آلي.

لديك الآن المواصفات الكاملة لـ FileProvider الذي ينشئ معرّفات الموارد المنتظمة (URI) للمحتوى للملفات في دليل files/ على وحدة التخزين الداخلية لتطبيقك أو للملفات في الأدلة الفرعية لتطبيق files/. عندما ينشئ تطبيقك معرّف موارد منتظم (URI) للمحتوى لأحد الملفات، يتضمّن التطبيق المرجع المحدّد في العنصر <provider> (com.example.myapp.fileprovider) والمسار myimages/ واسم الملف.

على سبيل المثال، إذا حدّدت FileProvider وفقًا للمقتطفات الواردة في هذا الدرس، وطلبت معرّف موارد منتظم (URI) للمحتوى للملف default_image.jpg، ستعرض FileProvider معرّف الموارد المنتظم التالي:

content://com.example.myapp.fileprovider/myimages/default_image.jpg

للحصول على معلومات إضافية ذات صلة، راجع:

• خيارات مساحة التخزين
• حفظ الملفات