تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

الوصول إلى ملفات الوسائط من مساحة التخزين المشتركة

لتوفير تجربة أكثر ثراءً للمستخدم، تتيح العديد من التطبيقات للمستخدمين المساهمة والوصول إلى الوسائط المتوفرة على وحدة تخزين خارجية. إطار العمل يوفّر فهرسًا محسَّنًا لمجموعات الوسائط، يُسمى متجر الوسائط، يتيح للمستخدمين استرداد ملفات الوسائط هذه وتعديلها بسهولة أكبر. وتظل هذه الملفات على جهاز المستخدم حتى بعد إلغاء تثبيت تطبيقك.

أداة اختيار الصور

كبديل لاستخدام متجر الوسائط، يمكن استخدام أداة "اختيار الصور" من Android توفّر طريقة آمنة ومدمجة للمستخدمين لاختيار ملفات الوسائط بدون الحاجة إلى لمنح تطبيقك إذن الوصول إلى مكتبة الوسائط بأكملها هذا الخيار متاح فقط. على الأجهزة المتوافقة. لمزيد من المعلومات، يُرجى الاطّلاع على دليل أداة اختيار الصور.

"متجر الوسائط"

للتفاعل مع التجريد في متجر الوسائط، استخدم ContentResolver العنصر الذي من سياق التطبيق:

KotlinJava

val projection = arrayOf(media-database-columns-to-retrieve)
val selection = sql-where-clause-with-placeholder-variables
val selectionArgs = values-of-placeholder-variables
val sortOrder = sql-order-by-clause

applicationContext.contentResolver.query(
    MediaStore.media-type.Media.EXTERNAL_CONTENT_URI,
    projection,
    selection,
    selectionArgs,
    sortOrder
)?.use { cursor ->
    while (cursor.moveToNext()) {
        // Use an ID column from the projection to get
        // a URI representing the media item itself.
    }
}

String[] projection = new String[] {
        media-database-columns-to-retrieve
};
String selection = sql-where-clause-with-placeholder-variables;
String[] selectionArgs = new String[] {
        values-of-placeholder-variables
};
String sortOrder = sql-order-by-clause;

Cursor cursor = getApplicationContext().getContentResolver().query(
    MediaStore.media-type.Media.EXTERNAL_CONTENT_URI,
    projection,
    selection,
    selectionArgs,
    sortOrder
);

while (cursor.moveToNext()) {
    // Use an ID column from the projection to get
    // a URI representing the media item itself.
}

يفحص النظام تلقائيًا وحدة تخزين خارجية ويضيف ملفات الوسائط إلى المجموعات المحدّدة جيدًا التالية:

الصور، بما في ذلك الصور الفوتوغرافية ولقطات الشاشة، التي يتم تخزينها في الدليلين DCIM/ وPictures/ يضيف النظام هذه الملفات إلى جدول MediaStore.Images.
الفيديوهات المخزَّنة في DCIM/ وMovies/ وPictures/ . يضيف النظام هذه الملفات إلى جدول MediaStore.Video.
الملفات الصوتية، التي يتم تخزينها في الدلائل Alarms/ وAudiobooks/ وMusic/ Notifications/ وPodcasts/ وRingtones/ بالإضافة إلى ذلك، يتعرّف النظام على قوائم التشغيل الصوتية في الدليلين Music/ أو Movies/ بالإضافة إلى التسجيلات الصوتية في الدليل Recordings/ . يضيف النظام هذه الملفات إلى جدول MediaStore.Audio. لا يتوفّر الدليل Recordings/ على الإصدار 11 من نظام التشغيل Android (المستوى 30 لواجهة برمجة التطبيقات) والإصدارات الأقدم.
الملفات التي تم تنزيلها، والتي يتم تخزينها في الدليل Download/ على الأجهزة التي تعمل بالإصدار 10 من Android (المستوى 29 لواجهة برمجة التطبيقات) والإصدارات الأحدث، يتم تخزين هذه الملفات في جدول MediaStore.Downloads . لا يتوفّر هذا الجدول على أجهزة Android 9 (المستوى 28 من واجهة برمجة التطبيقات) والإصدارات الأقدم.

يتضمّن متجر الوسائط أيضًا مجموعة باسم MediaStore.Files. محتوياته تعتمد على ما إذا كان تطبيقك يستخدم السمة نطاق مساحة التخزين، متوفّرة في التطبيقات التي تستهدف Android 10 أو إصدار أحدث

في حال تفعيل ميزة "مساحة التخزين المخصّصة"، لا تعرض المجموعة سوى الصور والفيديوهات والملفات الصوتية التي أنشأها تطبيقك. لا يحتاج معظم المطوّرين إلى استخدام MediaStore.Files لعرض ملفات الوسائط من تطبيقات أخرى، ولكن إذا كان لديك متطلبات محدّدة لاستخدام هذا الإذن، يمكنك الإفصاح عن إذن READ_EXTERNAL_STORAGE. ومع ذلك، ننصحك باستخدام MediaStore واجهات برمجة التطبيقات من أجل فتح الملفات التي لم ينشئها تطبيقك.
إذا لم يكن التخزين المحدود النطاق متاحًا أو لم يتم استخدامه، تعرض المجموعة جميع أنواع ملفات الوسائط.

طلب الأذونات اللازمة

قبل تنفيذ عمليات على ملفات الوسائط، تأكَّد من أنّ تطبيقك قد أعلن عن الأذونات التي يحتاجها للوصول إلى هذه الملفات. ومع ذلك، يجب عدم تقديم بيان بأذونات لا يحتاج إليها تطبيقك أو لا يستخدمها.

أذونات مساحة التخزين

تعتمد الحاجة إلى أذونات للوصول إلى مساحة التخزين في تطبيقك على ما إذا كان يُدخل تعديلات على ملفاته الخاصة أو الملفات التي أنشأتها تطبيقات أخرى فقط.

الوصول إلى ملفات الوسائط الخاصة بك

على الأجهزة التي تعمل بنظام التشغيل Android 10 أو الإصدارات الأحدث، لا تحتاج إلى أذونات متعلّقة بمساحة التخزين للوصول إلى ملفات الوسائط التي يملكها تطبيقك وتعديلها، بما في ذلك الملفات في مجموعة MediaStore.Downloads . على سبيل المثال، إذا كنت تُطوّر تطبيق كاميرا، لن تحتاج إلى طلب أذونات متعلّقة بمساحة التخزين للوصول إلى الصور التي يلتقطها، لأنّ تطبيقك يملك الصور التي تكتبها في "متجر الوسائط".

الوصول إلى التطبيقات الأخرى ملفات وسائط

للوصول إلى ملفات الوسائط التي تنشئها تطبيقات أخرى، عليك الإفصاح عن الأذونات المناسبة ذات الصلة بمساحة التخزين، ويجب أن تتواجد الملفات في إحدى مجموعات الوسائط التالية:

طالما أنّ الملف مرئي من طلبات البحث MediaStore.Images أو MediaStore.Video أو MediaStore.Audio، يمكن أيضًا عرضه باستخدام طلب البحث MediaStore.Files.

يوضح مقتطف الرمز التالي كيفية تحديد مساحة التخزين المناسبة. الأذونات:

<!-- Required only if your app needs to access images or photos
     that other apps created. -->
<uses-permission android:name="android.permission.READ_MEDIA_IMAGES" />

<!-- Required only if your app needs to access videos
     that other apps created. -->
<uses-permission android:name="android.permission.READ_MEDIA_VIDEO" />

<!-- Required only if your app needs to access audio files
     that other apps created. -->
<uses-permission android:name="android.permission.READ_MEDIA_AUDIO" />

<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/>

<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"
                 android:maxSdkVersion="29" />

يجب الحصول على أذونات إضافية للتطبيقات التي تعمل على الأجهزة القديمة

إذا كان تطبيقك يُستخدَم على جهاز يعمل بالإصدار 9 من نظام التشغيل Android أو إصدار أقدم، أو إذا كان تطبيقك قد أوقف مؤقتًا ميزة التخزين المحدود النطاق، عليك طلب READ_EXTERNAL_STORAGE إذن الوصول إلى أي ملف وسائط. إذا أردت تعديل ملفات الوسائط، يجب اطلب WRITE_EXTERNAL_STORAGE الإذن أيضًا.

يجب توفّر "إطار عمل الوصول إلى مساحة التخزين" للوصول إلى التطبيقات الأخرى. عمليات التنزيل

إذا كان تطبيقك يريد الوصول إلى ملف ضمن مجموعة MediaStore.Downloads لم ينشئه تطبيقك، يجب استخدام إطار عمل الوصول إلى مساحة التخزين. للتعلّم تعرّف على مزيد من المعلومات حول كيفية استخدام إطار العمل هذا، راجِع الوصول إلى المستندات والملفات الأخرى من مساحة تخزين مشتركة.

إذن الوصول إلى الموقع الجغرافي للوسائط

إذا كان تطبيقك يستهدف الإصدار 10 من نظام التشغيل Android (المستوى 29 لواجهة برمجة التطبيقات) أو إصدارًا أحدث ويحتاج إلى استرداد البيانات الوصفية غير المحذوفة من تنسيق EXIF من الصور، عليك الإفصاح عن إذن ACCESS_MEDIA_LOCATION في ملف بيان تطبيقك، ثم طلب هذا الإذن أثناء التشغيل.

البحث عن تحديثات في متجر الوسائط

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

أكمِل عملية التحقّق هذه في وقت بدء تشغيل عملية التطبيق. ليست هناك حاجة إلى التحقق من كل مرة تستعلم فيها من مخزن الوسائط.

ولا تفترض أي تفاصيل تنفيذية في ما يتعلق برقم الإصدار.

طلب مجموعة وسائط

للعثور على الوسائط التي تستوفي مجموعة معيّنة من الشروط، مثل مدة تبلغ 5 دقائق أو أكثر، استخدِم عبارة اختيار مشابهة لعبارة SQL مثل العبارة التي تظهر في مقتطف الرمز التالي:

KotlinJava

// Need the READ_EXTERNAL_STORAGE permission if accessing video files that your
// app didn't create.

// Container for information about each video.
data class Video(val uri: Uri,
    val name: String,
    val duration: Int,
    val size: Int
)
val videoList = mutableListOf<Video>()

val collection =
    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
        MediaStore.Video.Media.getContentUri(
            MediaStore.VOLUME_EXTERNAL
        )
    } else {
        MediaStore.Video.Media.EXTERNAL_CONTENT_URI
    }

val projection = arrayOf(
    MediaStore.Video.Media._ID,
    MediaStore.Video.Media.DISPLAY_NAME,
    MediaStore.Video.Media.DURATION,
    MediaStore.Video.Media.SIZE
)

// Show only videos that are at least 5 minutes in duration.
val selection = "${MediaStore.Video.Media.DURATION} >= ?"
val selectionArgs = arrayOf(
    TimeUnit.MILLISECONDS.convert(5, TimeUnit.MINUTES).toString()
)

// Display videos in alphabetical order based on their display name.
val sortOrder = "${MediaStore.Video.Media.DISPLAY_NAME} ASC"

val query = ContentResolver.query(
    collection,
    projection,
    selection,
    selectionArgs,
    sortOrder
)
query?.use { cursor ->
    // Cache column indices.
    val idColumn = cursor.getColumnIndexOrThrow(MediaStore.Video.Media._ID)
    val nameColumn =
            cursor.getColumnIndexOrThrow(MediaStore.Video.Media.DISPLAY_NAME)
    val durationColumn =
            cursor.getColumnIndexOrThrow(MediaStore.Video.Media.DURATION)
    val sizeColumn = cursor.getColumnIndexOrThrow(MediaStore.Video.Media.SIZE)

    while (cursor.moveToNext()) {
        // Get values of columns for a given video.
        val id = cursor.getLong(idColumn)
        val name = cursor.getString(nameColumn)
        val duration = cursor.getInt(durationColumn)
        val size = cursor.getInt(sizeColumn)

        val contentUri: Uri = ContentUris.withAppendedId(
            MediaStore.Video.Media.EXTERNAL_CONTENT_URI,
            id
        )

        // Stores column values and the contentUri in a local object
        // that represents the media file.
        videoList += Video(contentUri, name, duration, size)
    }
}

// Need the READ_EXTERNAL_STORAGE permission if accessing video files that your
// app didn't create.

// Container for information about each video.
class Video {
    private final Uri uri;
    private final String name;
    private final int duration;
    private final int size;

    public Video(Uri uri, String name, int duration, int size) {
        this.uri = uri;
        this.name = name;
        this.duration = duration;
        this.size = size;
    }
}
List<Video> videoList = new ArrayList<Video>();

Uri collection;
if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
    collection = MediaStore.Video.Media.getContentUri(MediaStore.VOLUME_EXTERNAL);
} else {
    collection = MediaStore.Video.Media.EXTERNAL_CONTENT_URI;
}

String[] projection = new String[] {
    MediaStore.Video.Media._ID,
    MediaStore.Video.Media.DISPLAY_NAME,
    MediaStore.Video.Media.DURATION,
    MediaStore.Video.Media.SIZE
};
String selection = MediaStore.Video.Media.DURATION +
        " >= ?";
String[] selectionArgs = new String[] {
    String.valueOf(TimeUnit.MILLISECONDS.convert(5, TimeUnit.MINUTES));
};
String sortOrder = MediaStore.Video.Media.DISPLAY_NAME + " ASC";

try (Cursor cursor = getApplicationContext().getContentResolver().query(
    collection,
    projection,
    selection,
    selectionArgs,
    sortOrder
)) {
    // Cache column indices.
    int idColumn = cursor.getColumnIndexOrThrow(MediaStore.Video.Media._ID);
    int nameColumn =
            cursor.getColumnIndexOrThrow(MediaStore.Video.Media.DISPLAY_NAME);
    int durationColumn =
            cursor.getColumnIndexOrThrow(MediaStore.Video.Media.DURATION);
    int sizeColumn = cursor.getColumnIndexOrThrow(MediaStore.Video.Media.SIZE);

    while (cursor.moveToNext()) {
        // Get values of columns for a given video.
        long id = cursor.getLong(idColumn);
        String name = cursor.getString(nameColumn);
        int duration = cursor.getInt(durationColumn);
        int size = cursor.getInt(sizeColumn);

        Uri contentUri = ContentUris.withAppendedId(
                MediaStore.Video.Media.EXTERNAL_CONTENT_URI, id);

        // Stores column values and the contentUri in a local object
        // that represents the media file.
        videoList.add(new Video(contentUri, name, duration, size));
    }
}

عند إجراء طلب بحث مماثل في تطبيقك، يجب مراعاة ما يلي:

استخدِم الطريقة query() في سلسلة مهام عامل.
يمكنك تخزين مؤشرات الأعمدة في ذاكرة التخزين المؤقت حتى لا تحتاج إلى استدعاء getColumnIndexOrThrow() في كل مرة تعالج فيها صفًا من نتيجة طلب البحث.
أضِف المعرّف إلى معرّف الموارد المنتظم (URI) للمحتوى كما هو موضّح في هذا المثال.
تتطلّب الأجهزة التي تعمل بالإصدار 10 من نظام التشغيل Android والإصدارات الأحدث أسماء عمود محدّدة في واجهة برمجة التطبيقات MediaStore. إذا كانت هناك مكتبة تابعة داخل تطبيقك تتوقع ظهور عمود يستخدم اسمًا غير معرَّف في واجهة برمجة التطبيقات، مثل "MimeType"، CursorWrapper للانتقال ديناميكيًا لترجمة اسم العمود في عملية تطبيقك.

تحميل الصور المصغّرة للملفات

إذا كان تطبيقك يعرض عدة ملفات وسائط ويطلب من المستخدم اختيار أحدها من هذه الملفات، يصبح تحميل معاينة النُسخ أو الصور المصغّرة من الملفات بدلاً من الملفات نفسها.

لتحميل الصورة المصغّرة لملف وسائط معيّن، استخدِم loadThumbnail() وأدخِل حجم الصورة المصغّرة التي تريد تحميلها، كما هو موضّح في مقتطف الرمز البرمجي التالي:

KotlinJava

// Load thumbnail of a specific media item.
val thumbnail: Bitmap =
        applicationContext.contentResolver.loadThumbnail(
        content-uri, Size(640, 480), null)

// Load thumbnail of a specific media item.
Bitmap thumbnail =
        getApplicationContext().getContentResolver().loadThumbnail(
        content-uri, new Size(640, 480), null);

فتح ملف وسائط

يعتمد المنطق المحدد الذي تستخدمه لفتح ملف وسائط على ما إذا كان وأفضل تمثيل لمحتوى الوسائط هو واصف ملف أو تدفق ملف أو مسار الملف المباشر.

واصِف الملف

لفتح ملف وسائط باستخدام وصف ملف، استخدِم منطقًا مشابهًا لما هو موضّح في مقتطف الرمز البرمجي التالي:

KotlinJava

// Open a specific media item using ParcelFileDescriptor.
val resolver = applicationContext.contentResolver

// "rw" for read-and-write.
// "rwt" for truncating or overwriting existing file contents.
val readOnlyMode = "r"
resolver.openFileDescriptor(content-uri, readOnlyMode).use { pfd ->
    // Perform operations on "pfd".
}

// Open a specific media item using ParcelFileDescriptor.
ContentResolver resolver = getApplicationContext()
        .getContentResolver();

// "rw" for read-and-write.
// "rwt" for truncating or overwriting existing file contents.
String readOnlyMode = "r";
try (ParcelFileDescriptor pfd =
        resolver.openFileDescriptor(content-uri, readOnlyMode)) {
    // Perform operations on "pfd".
} catch (IOException e) {
    e.printStackTrace();
}

الوصول المباشر إلى الملفات

لفتح ملف وسائط باستخدام بث ملف، استخدِم منطقًا مشابهًا لما هو موضّح في مقتطف الرمز البرمجي التالي:

KotlinJava

// Open a specific media item using InputStream.
val resolver = applicationContext.contentResolver
resolver.openInputStream(content-uri).use { stream ->
    // Perform operations on "stream".
}

// Open a specific media item using InputStream.
ContentResolver resolver = getApplicationContext()
        .getContentResolver();
try (InputStream stream = resolver.openInputStream(content-uri)) {
    // Perform operations on "stream".
}

مسارات الملفات المباشرة

لمساعدة تطبيقك على العمل بسلاسة أكبر مع مكتبات الوسائط التابعة لجهات خارجية، يتيح لك الإصدار 11 من Android (المستوى 30 لواجهة برمجة التطبيقات) والإصدارات الأحدث استخدام واجهات برمجة تطبيقات أخرى غير واجهة برمجة التطبيقات MediaStore للوصول إلى ملفات الوسائط من مساحة التخزين المشتركة. يمكنك بدلاً من ذلك الوصول إلى ملفات الوسائط مباشرةً. باستخدام أي من واجهات برمجة التطبيقات التالية:

واجهة برمجة تطبيقات File
المكتبات الأصلية، مثل fopen()

إذا لم يكن لديك أي أذونات متعلّقة بمساحة التخزين، يمكنك الوصول إلى الملفات في الدليل الخاص بالتطبيق بالإضافة إلى ملفّات الوسائط المنسوبة إلى تطبيقك باستخدام واجهة برمجة التطبيقات File.

إذا حاول تطبيقك الوصول إلى ملف باستخدام واجهة برمجة التطبيقات File ولم يكن لديه الأذونات اللازمة، يحدث FileNotFoundException.

للوصول إلى الملفات الأخرى في مساحة التخزين المشتركة على جهاز يعمل بنظام التشغيل Android 10 (المستوى 29 من واجهة برمجة التطبيقات)، ننصحك بإيقاف ميزة التخزين المحدود مؤقتًا من خلال ضبط القيمة requestLegacyExternalStorage على true في ملف بيان تطبيقك. للوصول إلى ملفات الوسائط باستخدام methodsملفّات أصلية على نظام التشغيل Android 10، يجب أيضًا طلب إذن READ_EXTERNAL_STORAGE .

الاعتبارات الواجب مراعاتها عند الوصول إلى محتوى الوسائط

عند الوصول إلى محتوى وسائط، يرجى أخذ الاعتبارات التي تمت مناقشتها في الأقسام التالية.

البيانات المؤقتة

إذا كان تطبيقك يخزِّن معرّفات الموارد المنتظمة (URI) أو البيانات من متجر الوسائط، فابحث بشكل دوري عن تحديثات إلى متجر الوسائط. يتيح لك هذا التحقّق إبقاء البيانات المخزّنة مؤقتًا على جانب التطبيق متزامنة مع بيانات مقدّم الخدمة على جانب النظام.

الأداء

عند تنفيذ عمليات قراءة متسلسلة لملفات الوسائط باستخدام مسارات الملفات المباشرة، يكون الأداء مماثلاً لأداء واجهة برمجة التطبيقات MediaStore.

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

عمود DATA

عند الوصول إلى ملف وسائط حالي، يمكنك استخدام قيمة عمود DATA في منطقك. يرجع ذلك إلى أنّ هذه القيمة لها مسار ملف صالح. ومع ذلك، لا تفعل أن الملف متاح دائمًا. يجب أن تكون مستعدًا للتعامل مع أي أخطاء في القراءة/الكتابة المستندة إلى الملفات.

لإنشاء ملف وسائط أو تحديثه، لا تستخدم قيمة عمود "DATA". وبدلاً من ذلك، استخدِم قيم DISPLAY_NAME أو RELATIVE_PATH والأعمدة.

أحجام التخزين

يمكن للتطبيقات التي تستهدف الإصدار 10 من نظام التشغيل Android أو الإصدارات الأحدث الوصول إلى الاسم الفريد الذي يحدّده النظام لكل وحدة تخزين خارجية. نظام التسمية هذا في تنظيم المحتوى وفهرسته بكفاءة، والتحكم في حيث يتم تخزين ملفات الوسائط الجديدة.

تُعد المجلدات التالية من المفيد وضعها في الاعتبار على وجه الخصوص:

تشير رسالة الأشكال البيانية VOLUME_EXTERNAL يتيح مستوى الصوت عرض كل وحدات التخزين المشتركة على الجهاز. يمكنك قراءة محتوى هذا الجزء الاصطناعي، ولكن لا يمكنك تعديله.
يمثّل رمز المساحة التخزينية VOLUME_EXTERNAL_PRIMARY مساحة التخزين المشتركة الأساسية على الجهاز. يمكنك قراءة محتوى هذا المجلد وتعديله.

يمكنك استكشاف مجلدات أخرى من خلال الاتصال MediaStore.getExternalVolumeNames():

KotlinJava

val volumeNames: Set<String> = MediaStore.getExternalVolumeNames(context)
val firstVolumeName = volumeNames.iterator().next()

Set<String> volumeNames = MediaStore.getExternalVolumeNames(context);
String firstVolumeName = volumeNames.iterator().next();

الموقع الجغرافي الذي تم فيه التقاط الوسائط

تحتوي بعض الصور والفيديوهات على معلومات الموقع الجغرافي في البيانات الوصفية التي تعرض المكان الذي تم فيه التقاط صورة أو تسجيل فيديو.

تعتمد طريقة الوصول إلى معلومات الموقع الجغرافي هذه في تطبيقك على ما إذا كان عليك الوصول إلى معلومات الموقع الجغرافي لصورة أو فيديو.

صور فوتوغرافية

إذا كان تطبيقك يستخدم مساحة تخزين ذات نطاق واسع، سيتم تفعيل يخفي النظام معلومات الموقع تلقائيًا. للوصول إلى هذه المعلومات، عليك إكمال الخطوات التالية:

اطلب إذن ACCESS_MEDIA_LOCATION في ملف بيان تطبيقك.

من عنصر MediaStore، يمكنك الحصول على البايتات الدقيقة للصورة من خلال استدعاء setRequireOriginal() وإدخال معرّف الموارد المنتظم للصورة، كما هو موضّح في مقتطف الرمز التالي:

KotlinJava

val photoUri: Uri = Uri.withAppendedPath(
        MediaStore.Images.Media.EXTERNAL_CONTENT_URI,
        cursor.getString(idColumnIndex)
)

// Get location data using the Exifinterface library.
// Exception occurs if ACCESS_MEDIA_LOCATION permission isn't granted.
photoUri = MediaStore.setRequireOriginal(photoUri)
contentResolver.openInputStream(photoUri)?.use { stream ->
    ExifInterface(stream).run {
        // If lat/long is null, fall back to the coordinates (0, 0).
        val latLong = latLong ?: doubleArrayOf(0.0, 0.0)
    }
}

Uri photoUri = Uri.withAppendedPath(
        MediaStore.Images.Media.EXTERNAL_CONTENT_URI,
        cursor.getString(idColumnIndex));

final double[] latLong;

// Get location data using the Exifinterface library.
// Exception occurs if ACCESS_MEDIA_LOCATION permission isn't granted.
photoUri = MediaStore.setRequireOriginal(photoUri);
InputStream stream = getContentResolver().openInputStream(photoUri);
if (stream != null) {
    ExifInterface exifInterface = new ExifInterface(stream);
    double[] returnedLatLong = exifInterface.getLatLong();

    // If lat/long is null, fall back to the coordinates (0, 0).
    latLong = returnedLatLong != null ? returnedLatLong : new double[2];

    // Don't reuse the stream associated with
    // the instance of "ExifInterface".
    stream.close();
} else {
    // Failed to load the stream, so return the coordinates (0, 0).
    latLong = new double[2];
}

الفيديوهات

للوصول إلى معلومات الموقع الجغرافي ضمن البيانات الوصفية للفيديو، استخدِم فئة MediaMetadataRetriever ، كما هو موضّح في مقتطف الرمز التالي. لا يحتاج تطبيقك إلى طلب أي أذونات إضافية لاستخدام هذه الفئة.

KotlinJava

val retriever = MediaMetadataRetriever()
val context = applicationContext

// Find the videos that are stored on a device by querying the video collection.
val query = ContentResolver.query(
    collection,
    projection,
    selection,
    selectionArgs,
    sortOrder
)
query?.use { cursor ->
    val idColumn = cursor.getColumnIndexOrThrow(MediaStore.Video.Media._ID)
    while (cursor.moveToNext()) {
        val id = cursor.getLong(idColumn)
        val videoUri: Uri = ContentUris.withAppendedId(
            MediaStore.Video.Media.EXTERNAL_CONTENT_URI,
            id
        )
        extractVideoLocationInfo(videoUri)
    }
}

private fun extractVideoLocationInfo(videoUri: Uri) {
    try {
        retriever.setDataSource(context, videoUri)
    } catch (e: RuntimeException) {
        Log.e(APP_TAG, "Cannot retrieve video file", e)
    }
    // Metadata uses a standardized format.
    val locationMetadata: String? =
            retriever.extractMetadata(MediaMetadataRetriever.METADATA_KEY_LOCATION)
}

MediaMetadataRetriever retriever = new MediaMetadataRetriever();
Context context = getApplicationContext();

// Find the videos that are stored on a device by querying the video collection.
try (Cursor cursor = context.getContentResolver().query(
    collection,
    projection,
    selection,
    selectionArgs,
    sortOrder
)) {
    int idColumn = cursor.getColumnIndexOrThrow(MediaStore.Video.Media._ID);
    while (cursor.moveToNext()) {
        long id = cursor.getLong(idColumn);
        Uri videoUri = ContentUris.withAppendedId(
                MediaStore.Video.Media.EXTERNAL_CONTENT_URI, id);
        extractVideoLocationInfo(videoUri);
    }
}

private void extractVideoLocationInfo(Uri videoUri) {
    try {
        retriever.setDataSource(context, videoUri);
    } catch (RuntimeException e) {
        Log.e(APP_TAG, "Cannot retrieve video file", e);
    }
    // Metadata uses a standardized format.
    String locationMetadata = retriever.extractMetadata(
            MediaMetadataRetriever.METADATA_KEY_LOCATION);
}

تتيح بعض التطبيقات للمستخدمين مشاركة ملفات الوسائط مع بعضهم البعض. على سبيل المثال، يمكن التواصل تطبيقات الوسائط للمستخدمين مشاركة الصور والفيديوهات مع الأصدقاء.

لمشاركة ملفات الوسائط، استخدِم معرّف الموارد المنتظم content://، كما هو مقترَح في دليل إنشاء مزوّد محتوى.

إحالة ملفات الوسائط إلى التطبيق

عند تفعيل ميزة مساحة التخزين ذات النطاق المحدّد لتطبيق يستهدف الإصدار 10 من نظام التشغيل Android أو الإصدارات الأحدث، يربط النظام التطبيق بكل ملف وسائط، ما يحدّد الملفات التي يمكن لتطبيقك الوصول إليها عندما لا يطلب أي أذونات تخزين. يمكن أن يُنسَب كل ملف إلى تطبيق واحد فقط. لذلك، إذا أنشأ تطبيقك ملف وسائط تم تخزينه في مجموعة الوسائط التي تتضمّن الصور أو الفيديوهات أو الملفات الصوتية، يمكن لتطبيقك الوصول إلى الملف.

ومع ذلك، إذا ألغى المستخدم تثبيت تطبيقك وأعاد تثبيته، عليك طلب ذلك. READ_EXTERNAL_STORAGE للوصول إلى الملفات التي أنشأها تطبيقك في الأصل. إنّ طلب الإذن هذا مطلوب لأنّ النظام يعتبر أنّ الملف ينتمي إلى الإصدار المثبَّت سابقًا من التطبيق، وليس إلى الإصدار المثبَّت حديثًا.

إضافة عنصر

لإضافة عنصر وسائط إلى مجموعة حالية، استخدِم رمزًا مشابهًا للرمز التالي: تُستخدَم هذه المقتطفات من الرموز البرمجية للوصول إلى مستوى VOLUME_EXTERNAL_PRIMARY الصوت على الأجهزة التي تعمل بنظام التشغيل Android 10 أو إصدار أحدث. وهذا لأنه على هذه الأجهزة، يمكن فقط تعديل محتوى أي وحدة تخزين إذا كان مستوى الصوت الأساسي، كما هو موضَّح في قسم أحجام مساحة التخزين.

KotlinJava

// Add a specific media item.
val resolver = applicationContext.contentResolver

// Find all audio files on the primary external storage device.
val audioCollection =
    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
        MediaStore.Audio.Media.getContentUri(
            MediaStore.VOLUME_EXTERNAL_PRIMARY
        )
    } else {
        MediaStore.Audio.Media.EXTERNAL_CONTENT_URI
    }

// Publish a new song.
val newSongDetails = ContentValues().apply {
    put(MediaStore.Audio.Media.DISPLAY_NAME, "My Song.mp3")
}

// Keep a handle to the new song's URI in case you need to modify it
// later.
val myFavoriteSongUri = resolver
        .insert(audioCollection, newSongDetails)

// Add a specific media item.
ContentResolver resolver = getApplicationContext()
        .getContentResolver();

// Find all audio files on the primary external storage device.
Uri audioCollection;
if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
    audioCollection = MediaStore.Audio.Media
            .getContentUri(MediaStore.VOLUME_EXTERNAL_PRIMARY);
} else {
    audioCollection = MediaStore.Audio.Media.EXTERNAL_CONTENT_URI;
}

// Publish a new song.
ContentValues newSongDetails = new ContentValues();
newSongDetails.put(MediaStore.Audio.Media.DISPLAY_NAME,
        "My Song.mp3");

// Keep a handle to the new song's URI in case you need to modify it
// later.
Uri myFavoriteSongUri = resolver
        .insert(audioCollection, newSongDetails);

تبديل حالة "معلّق" لملفات الوسائط

إذا كان تطبيقك يُجري عمليات قد تستغرق وقتًا طويلاً، مثل الكتابة فيملفّات الوسائط، من المفيد الحصول على إذن وصول حصري إلى الملف أثناء معالجته. على الأجهزة التي تعمل بنظام التشغيل Android 10 أو إصدار أحدث، يمكن لتطبيقك الحصول على هذا الإذن الحصري من خلال ضبط قيمة العلامة IS_PENDING على 1. يمكن لتطبيقك فقط عرض الملف إلى أن يغيّر التطبيق قيمة IS_PENDING رجوع إلى 0.

يستند مقتطف الرمز البرمجي التالي إلى مقتطف الرمز البرمجي السابق. هذا النمط مقتطف يوضح كيفية استخدام علامة IS_PENDING عند تخزين أغنية طويلة في الدليل المقابل لمجموعة MediaStore.Audio:

KotlinJava

// Add a media item that other apps don't see until the item is
// fully written to the media store.
val resolver = applicationContext.contentResolver

// Find all audio files on the primary external storage device.
val audioCollection =
    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
        MediaStore.Audio.Media.getContentUri(
            MediaStore.VOLUME_EXTERNAL_PRIMARY
        )
    } else {
        MediaStore.Audio.Media.EXTERNAL_CONTENT_URI
    }

val songDetails = ContentValues().apply {
    put(MediaStore.Audio.Media.DISPLAY_NAME, "My Workout Playlist.mp3")
    put(MediaStore.Audio.Media.IS_PENDING, 1)
}

val songContentUri = resolver.insert(audioCollection, songDetails)

// "w" for write.
resolver.openFileDescriptor(songContentUri, "w", null).use { pfd ->
    // Write data into the pending audio file.
}

// Now that you're finished, release the "pending" status and let other apps
// play the audio track.
songDetails.clear()
songDetails.put(MediaStore.Audio.Media.IS_PENDING, 0)
resolver.update(songContentUri, songDetails, null, null)

// Add a media item that other apps don't see until the item is
// fully written to the media store.
ContentResolver resolver = getApplicationContext()
        .getContentResolver();

// Find all audio files on the primary external storage device.
Uri audioCollection;
if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
    audioCollection = MediaStore.Audio.Media
            .getContentUri(MediaStore.VOLUME_EXTERNAL_PRIMARY);
} else {
    audioCollection = MediaStore.Audio.Media.EXTERNAL_CONTENT_URI;
}

ContentValues songDetails = new ContentValues();
songDetails.put(MediaStore.Audio.Media.DISPLAY_NAME,
        "My Workout Playlist.mp3");
songDetails.put(MediaStore.Audio.Media.IS_PENDING, 1);

Uri songContentUri = resolver
        .insert(audioCollection, songDetails);

// "w" for write.
try (ParcelFileDescriptor pfd =
        resolver.openFileDescriptor(songContentUri, "w", null)) {
    // Write data into the pending audio file.
}

// Now that you're finished, release the "pending" status and let other apps
// play the audio track.
songDetails.clear();
songDetails.put(MediaStore.Audio.Media.IS_PENDING, 0);
resolver.update(songContentUri, songDetails, null, null);

تقديم تلميح لموقع الملف

عندما يخزِّن تطبيقك الوسائط على جهاز يعمل بنظام التشغيل Android 10، يتم تلقائيًا تنظيم الوسائط استنادًا إلى نوعها. على سبيل المثال، قد يتم استخدام يتم وضع ملفات الصور في Environment.DIRECTORY_PICTURES الذي يتجاوب مع دليل مجموعة MediaStore.Images

إذا كان تطبيقك على دراية بموقع معيّن يمكن تخزين الملفات فيه، مثل ألبوم صور باسم Pictures/MyVacationPictures، يمكنك ضبط MediaColumns.RELATIVE_PATH لإعلام النظام بمكان تخزين الملفات التي تم كتابتها حديثًا.

تعديل عنصر

لتعديل ملف وسائط يملكه تطبيقك، استخدِم رمزًا برمجيًا مشابهًا لما يلي:

KotlinJava

// Updates an existing media item.
val mediaId = // MediaStore.Audio.Media._ID of item to update.
val resolver = applicationContext.contentResolver

// When performing a single item update, prefer using the ID.
val selection = "${MediaStore.Audio.Media._ID} = ?"

// By using selection + args you protect against improper escaping of // values.
val selectionArgs = arrayOf(mediaId.toString())

// Update an existing song.
val updatedSongDetails = ContentValues().apply {
    put(MediaStore.Audio.Media.DISPLAY_NAME, "My Favorite Song.mp3")
}

// Use the individual song's URI to represent the collection that's
// updated.
val numSongsUpdated = resolver.update(
        myFavoriteSongUri,
        updatedSongDetails,
        selection,
        selectionArgs)

// Updates an existing media item.
long mediaId = // MediaStore.Audio.Media._ID of item to update.
ContentResolver resolver = getApplicationContext()
        .getContentResolver();

// When performing a single item update, prefer using the ID.
String selection = MediaStore.Audio.Media._ID + " = ?";

// By using selection + args you protect against improper escaping of
// values. Here, "song" is an in-memory object that caches the song's
// information.
String[] selectionArgs = new String[] { getId().toString() };

// Update an existing song.
ContentValues updatedSongDetails = new ContentValues();
updatedSongDetails.put(MediaStore.Audio.Media.DISPLAY_NAME,
        "My Favorite Song.mp3");

// Use the individual song's URI to represent the collection that's
// updated.
int numSongsUpdated = resolver.update(
        myFavoriteSongUri,
        updatedSongDetails,
        selection,
        selectionArgs);

إذا كانت مساحة التخزين غير متاحة أو غير مفعّلة، تظهر العملية في يعمل مقتطف الرمز السابق أيضًا مع الملفات التي لا يمتلكها تطبيقك.

تعديل الرمز البرمجي الأصلي

إذا كنت بحاجة إلى كتابة ملفات وسائط باستخدام مكتبات برمجية أصلية، عليك تمرير وصف الملف المرتبط بالملف من الرمز البرمجي المستنِد إلى Java أو Kotlin إلى الرمز البرمجي الأصلي.

يعرض مقتطف الرمز التالي كيفية تمرير واصف ملف كائن الوسائط في الرمز الأصلي لتطبيقك:

KotlinJava

val contentUri: Uri = ContentUris.withAppendedId(
        MediaStore.Audio.Media.EXTERNAL_CONTENT_URI,
        cursor.getLong(BaseColumns._ID))
val fileOpenMode = "r"
val parcelFd = resolver.openFileDescriptor(contentUri, fileOpenMode)
val fd = parcelFd?.detachFd()
// Pass the integer value "fd" into your native code. Remember to call
// close(2) on the file descriptor when you're done using it.

Uri contentUri = ContentUris.withAppendedId(
        MediaStore.Audio.Media.EXTERNAL_CONTENT_URI,
        cursor.getLong(Integer.parseInt(BaseColumns._ID)));
String fileOpenMode = "r";
ParcelFileDescriptor parcelFd =
        resolver.openFileDescriptor(contentUri, fileOpenMode);
if (parcelFd != null) {
    int fd = parcelFd.detachFd();
    // Pass the integer value "fd" into your native code. Remember to call
    // close(2) on the file descriptor when you're done using it.
}

تعديل ملفات الوسائط في التطبيقات الأخرى

إذا كان تطبيقك يستخدم مساحة تخزين محددة النطاق، لن يتمكّن عادةً من تعديل ملف وسائط ساهم تطبيق آخر في تخزينه في ملف التخزين المخصّص للوسائط.

يمكنك الحصول على موافقة المستخدم لتعديل الملف من خلال رصد RecoverableSecurityException الخطأ الذي تُرسِله المنصة. يمكنك بعد ذلك أن تطلب من المستخدم منح تطبيقك إذن الوصول للكتابة إلى هذا العنصر المحدّد، كما هو موضّح في مقتطف الرمز التالي:

KotlinJava

// Apply a grayscale filter to the image at the given content URI.
try {
    // "w" for write.
    contentResolver.openFileDescriptor(image-content-uri, "w")?.use {
        setGrayscaleFilter(it)
    }
} catch (securityException: SecurityException) {
    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
        val recoverableSecurityException = securityException as?
            RecoverableSecurityException ?:
            throw RuntimeException(securityException.message, securityException)

        val intentSender =
            recoverableSecurityException.userAction.actionIntent.intentSender
        intentSender?.let {
            startIntentSenderForResult(intentSender, image-request-code,
                    null, 0, 0, 0, null)
        }
    } else {
        throw RuntimeException(securityException.message, securityException)
    }
}

try {
    // "w" for write.
    ParcelFileDescriptor imageFd = getContentResolver()
            .openFileDescriptor(image-content-uri, "w");
    setGrayscaleFilter(imageFd);
} catch (SecurityException securityException) {
    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {
        RecoverableSecurityException recoverableSecurityException;
        if (securityException instanceof RecoverableSecurityException) {
            recoverableSecurityException =
                    (RecoverableSecurityException)securityException;
        } else {
            throw new RuntimeException(
                    securityException.getMessage(), securityException);
        }
        IntentSender intentSender =recoverableSecurityException.getUserAction()
                .getActionIntent().getIntentSender();
        startIntentSenderForResult(intentSender, image-request-code,
                null, 0, 0, 0, null);
    } else {
        throw new RuntimeException(
                securityException.getMessage(), securityException);
    }
}

يجب إكمال هذه العملية في كل مرة يحتاج فيها تطبيقك إلى تعديل ملف وسائط لم ينشئوه.

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

إذا كان تطبيقك يتضمّن حالة استخدام أخرى لا تندرج ضمن نطاق "مساحة التخزين المخصّصة"، يمكنك تقديم طلب لإضافة ميزة وإيقاف "مساحة التخزين المخصّصة" مؤقتًا.

إزالة عنصر

لإزالة عنصر لم يعُد تطبيقك بحاجة إليه من متجر الوسائط، استخدِم منطقًا مشابهًا لما هو موضَّح في المقتطف التالي من الرمز البرمجي:

KotlinJava

// Remove a specific media item.
val resolver = applicationContext.contentResolver

// URI of the image to remove.
val imageUri = "..."

// WHERE clause.
val selection = "..."
val selectionArgs = "..."

// Perform the actual removal.
val numImagesRemoved = resolver.delete(
        imageUri,
        selection,
        selectionArgs)

// Remove a specific media item.
ContentResolver resolver = getApplicationContext()
        getContentResolver();

// URI of the image to remove.
Uri imageUri = "...";

// WHERE clause.
String selection = "...";
String[] selectionArgs = "...";

// Perform the actual removal.
int numImagesRemoved = resolver.delete(
        imageUri,
        selection,
        selectionArgs);

إذا كانت مساحة التخزين غير متاحة أو غير مفعّلة، يمكنك استخدام الأقسام السابقة مقتطف الرمز لإزالة الملفات التي تمتلكها التطبيقات الأخرى. في حال تفعيل ميزة "مساحة التخزين المستندة إلى النطاق"، عليك الحصول على RecoverableSecurityException لكل ملف يريده تطبيقك إزالته، كما هو موضّح في القسم حول تعديل ملفّات الوسائط .

إذا كان تطبيقك يعمل بنظام التشغيل Android 11 أو إصدار أحدث، يمكنك السماح للمستخدمين اختَر مجموعة من ملفات الوسائط لإزالتها استخدِم createTrashRequest() الطريقة أو createDeleteRequest() الطريقة، كما هو موضّح في القسم حول كيفية إدارة مجموعاتملفّات الوسائط .

رصد التحديثات على ملفات الوسائط

قد يحتاج تطبيقك إلى تحديد وحدات التخزين التي تحتوي على ملفات الوسائط التي تستخدمها هذه التطبيقات. مضافة أو معدلة، مقارنة بأي نقطة زمنية سابقة. لرصد هذه التغييرات بأكبر قدر من الموثوقية، عليك تمرير مساحة التخزين التي تهمّك إلى getGeneration(). طالما أنّ إصدار متجر الوسائط لم يتغيّر، تزداد القيمة المعروضة من هذه الطريقة بشكلٍ منتظم بمرور الوقت.

على وجه الخصوص، يكون العمود getGeneration() أكثر دقة من الأعمدة التي تتضمّن تواريخ، مثل DATE_ADDED وDATE_MODIFIED. وذلك لأن قيم أعمدة الوسائط هذه يمكن أن تتغير عندما يستدعي التطبيق setLastModified() أو متى يغير المستخدم ساعة النظام.

إدارة مجموعات ملفات الوسائط

في نظام التشغيل Android 11 والإصدارات الأحدث، يمكنك أن تطلب من المستخدم اختيار مجموعة من ملفات الوسائط، ثم تعديل ملفات الوسائط هذه في عملية واحدة. توفّر هذه الخطوات اتساقًا أفضل على جميع الأجهزة، كما تسهّل على المستخدمين إدارة مجموعات الوسائط الخاصة بهم.

الطرق التي توفر هذا "التحديث المجمَّع" الوظائف التالي:

createWriteRequest(): اطلب من المستخدم منح تطبيقك إذنًا بالكتابة في المجموعة المحدّدة من ملفات الوسائط.
createFavoriteRequest(): يُرجى طلب من المستخدم وضع علامة على ملفات الوسائط المحدّدة على أنّها من الوسائط "المفضّلة" على الجهاز. يمكن لأي تطبيق لديه إذن وصول للقراءة إلى هذا الملف ومعرفة أنّ المستخدم وضع علامة "مفضّل" على الملف.
createTrashRequest(): اطلب من المستخدم وضع ملفات الوسائط المحدّدة في مهملات الجهاز. يتم حذف العناصر نهائيًا من المهملات بعد وقت يحدّده النظام. الفترة.

ملاحظة: إذا كان تطبيقك هو تطبيق معرض الصور المثبَّت مسبقًا للمصنّع الأصلي للجهاز، يمكنك وضع من الملفات في المهملات بدون إظهار مربع حوار. للقيام بذلك، قم بتعيين IS_TRASHED إلى 1 مباشرةً.
createDeleteRequest(): طلب أن يحذف المستخدم ملفات الوسائط المحدَّدة نهائيًا فورًا، دون وضعها في المهملات مسبقًا.

بعد استدعاء أيّ من هذه الطرق، ينشئ النظام عنصرًا PendingIntent. بعد تثبيت التطبيق يستدعي هذا الغرض، سيظهر للمستخدمين مربع حوار يطلب موافقتهم على تطبيقك لتعديل ملفات الوسائط المحدّدة أو حذفها

على سبيل المثال، إليك كيفية صياغة دعوة إلى createWriteRequest():

KotlinJava

val urisToModify = /* A collection of content URIs to modify. */
val editPendingIntent = MediaStore.createWriteRequest(contentResolver,
        urisToModify)

// Launch a system prompt requesting user permission for the operation.
startIntentSenderForResult(editPendingIntent.intentSender, EDIT_REQUEST_CODE,
    null, 0, 0, 0)

List<Uri> urisToModify = /* A collection of content URIs to modify. */
PendingIntent editPendingIntent = MediaStore.createWriteRequest(contentResolver,
                  urisToModify);

// Launch a system prompt requesting user permission for the operation.
startIntentSenderForResult(editPendingIntent.getIntentSender(),
    EDIT_REQUEST_CODE, null, 0, 0, 0);

تقييم ردّ المستخدم إذا قدّم المستخدم موافقته، يمكنك تشغيل الوسائط. بخلاف ذلك، اشرح للمستخدم سبب احتياج تطبيقك إلى الإذن:

KotlinJava

override fun onActivityResult(requestCode: Int, resultCode: Int,
                 data: Intent?) {
    ...
    when (requestCode) {
        EDIT_REQUEST_CODE ->
            if (resultCode == Activity.RESULT_OK) {
                /* Edit request granted; proceed. */
            } else {
                /* Edit request not granted; explain to the user. */
            }
    }
}

@Override
protected void onActivityResult(int requestCode, int resultCode,
                   @Nullable Intent data) {
    ...
    if (requestCode == EDIT_REQUEST_CODE) {
        if (resultCode == Activity.RESULT_OK) {
            /* Edit request granted; proceed. */
        } else {
            /* Edit request not granted; explain to the user. */
        }
    }
}

يمكنك استخدام هذا النمط العام نفسه مع createFavoriteRequest()، createTrashRequest()، و createDeleteRequest().

إذن إدارة الوسائط

قد يثق المستخدمون في تطبيق معيّن لإدارة الوسائط، مثل إنشاء إجراء تعديلات متكررة على ملفات الوسائط إذا كان تطبيقك يستهدف الإصدار Android 11 أو إصدارًا أحدث ولم يكن تطبيق معرض الصور التلقائي على الجهاز، يجب عرض مربّع حوار تأكيد للمستخدم في كل مرة يحاول فيها تطبيقك تعديل ملف أو حذفه.

إذا كان تطبيقك يستهدف الإصدار 12 من نظام التشغيل Android (المستوى 31) أو إصدارًا أحدث، يمكنك طلب يمنح المستخدمون تطبيقك إذن الوصول الخاص إلى إدارة الوسائط. يتيح هذا الإذن لتطبيقك تنفيذ كلّ ممّا يلي بدون الحاجة إلى طلب المستخدم تنفيذ كلّ عملية على الملف:

تعديل الملفات باستخدام createWriteRequest()
نقل الملفات إلى المهملات وخارجها باستخدام رمز createTrashRequest()
حذف الملفات، باستخدام createDeleteRequest()

للقيام بذلك، أكمل الخطوات التالية:

يجب الإفصاح عن إذن MANAGE_MEDIA وإذن READ_EXTERNAL_STORAGE في ملف بيان تطبيقك.

للاتصال بالرقم createWriteRequest() بدون عرض مربع حوار confirmation ، يجب أيضًا الإفصاح عن إذن ACCESS_MEDIA_LOCATION .
عرض واجهة مستخدم في تطبيقك لتوضيح سبب رغبته في منح إدارة الوسائط في تطبيقك
استخدِم الإجراء ACTION_REQUEST_MANAGE_MEDIA intent. ينقل ذلك المستخدمين إلى شاشة تطبيقات إدارة الوسائط في إعدادات النظام. من هنا، يمكن للمستخدمين منح إذن الوصول إلى التطبيق الخاص.

حالات الاستخدام التي تتطلّب بديلاً لمتجر الوسائط

إذا كان تطبيقك يؤدي أحد الأدوار التالية بشكل أساسي، ننصحك باستخدام بديل لواجهات برمجة تطبيقات MediaStore.

العمل مع أنواع أخرى من الملفات

إذا كان تطبيقك يعمل مع المستندات والملفات التي لا تحتوي حصريًا على محتوى إعلام، مثل الملفات التي تستخدم امتداد ملف EPUB أو PDF، استخدِمACTION_OPEN_DOCUMENT إجراء النية كما هو موضّح في دليل تخزين المستندات وغيرها من الملفات والوصول إليها.

مشاركة الملفات في التطبيقات المصاحبة

في الحالات التي تقدّم فيها مجموعة من التطبيقات المصاحبة، مثل تطبيق مراسلة و تطبيق ملف شخصي، يمكنك إعداد ميزة مشاركة الملفات باستخدام معرّفات الموارد المنتظمة content://. ننصحك أيضًا باتّباع سير العمل هذا كأحد أفضل الممارسات المتعلّقة بال security .

مصادر إضافية

لمزيد من المعلومات حول كيفية تخزين الوسائط والوصول إليها، يُرجى الرجوع إلى المراجع التالية:

نماذج

MediaStore، متوفرة على GitHub

الفيديوهات

الاستعداد للتخزين الفرعي (مؤتمر Android Dev Summit) عام 2019)

الوصول إلى ملفات الوسائط من مساحة التخزين المشتركة

أداة اختيار الصور

"متجر الوسائط"

طلب الأذونات اللازمة

أذونات مساحة التخزين

الوصول إلى ملفات الوسائط الخاصة بك

الوصول إلى التطبيقات الأخرى ملفات وسائط

يجب الحصول على أذونات إضافية للتطبيقات التي تعمل على الأجهزة القديمة

يجب توفّر "إطار عمل الوصول إلى مساحة التخزين" للوصول إلى التطبيقات الأخرى. عمليات التنزيل

إذن الوصول إلى الموقع الجغرافي للوسائط

البحث عن تحديثات في متجر الوسائط

طلب مجموعة وسائط

تحميل الصور المصغّرة للملفات

فتح ملف وسائط

واصِف الملف

الوصول المباشر إلى الملفات

مسارات الملفات المباشرة

الاعتبارات الواجب مراعاتها عند الوصول إلى محتوى الوسائط

البيانات المؤقتة

الأداء

عمود DATA

أحجام التخزين

الموقع الجغرافي الذي تم فيه التقاط الوسائط

صور فوتوغرافية

الفيديوهات

المشاركة

إحالة ملفات الوسائط إلى التطبيق

إضافة عنصر

تبديل حالة "معلّق" لملفات الوسائط

تقديم تلميح لموقع الملف

تعديل عنصر

تعديل الرمز البرمجي الأصلي

تعديل ملفات الوسائط في التطبيقات الأخرى

إزالة عنصر

رصد التحديثات على ملفات الوسائط

إدارة مجموعات ملفات الوسائط

إذن إدارة الوسائط

حالات الاستخدام التي تتطلّب بديلاً لمتجر الوسائط

العمل مع أنواع أخرى من الملفات

مشاركة الملفات في التطبيقات المصاحبة

مصادر إضافية

نماذج

الفيديوهات