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

يظهر مربع حوار "أداة اختيار الصور" مع ملفات الوسائط على جهازك. اختَر صورة لمشاركتها مع التطبيق.
الشكل 1. توفّر "أداة اختيار الصور" واجهة مستخدم سهلة لمشاركة الصور مع تطبيقك.

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

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

يتم تحديث الأداة تلقائيًا لتوفير وظائف موسعة لمستخدمي التطبيق بمرور الوقت بدون الحاجة إلى إجراء أي تغييرات على الرموز البرمجية.

استخدام عقود نشاط Jetpack

لتبسيط عملية دمج "أداة اختيار الصور"، يجب تضمين إصدار 1.7.0 أو الإصدارات الأحدث من مكتبة androidx.activity.

استخدِم عقود نتائج الأنشطة التالية لتشغيل "أداة اختيار الصور":

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

اختيار عنصر وسائط واحد

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

Kotlin

// Registers a photo picker activity launcher in single-select mode.
val pickMedia = registerForActivityResult(PickVisualMedia()) { uri ->
    // Callback is invoked after the user selects a media item or closes the
    // photo picker.
    if (uri != null) {
        Log.d("PhotoPicker", "Selected URI: $uri")
    } else {
        Log.d("PhotoPicker", "No media selected")
    }
}

// Include only one of the following calls to launch(), depending on the types
// of media that you want to let the user choose from.

// Launch the photo picker and let the user choose images and videos.
pickMedia.launch(PickVisualMediaRequest(PickVisualMedia.ImageAndVideo))

// Launch the photo picker and let the user choose only images.
pickMedia.launch(PickVisualMediaRequest(PickVisualMedia.ImageOnly))

// Launch the photo picker and let the user choose only videos.
pickMedia.launch(PickVisualMediaRequest(PickVisualMedia.VideoOnly))

// Launch the photo picker and let the user choose only images/videos of a
// specific MIME type, such as GIFs.
val mimeType = "image/gif"
pickMedia.launch(PickVisualMediaRequest(PickVisualMedia.SingleMimeType(mimeType)))

Java

// Registers a photo picker activity launcher in single-select mode.
ActivityResultLauncher<PickVisualMediaRequest> pickMedia =
        registerForActivityResult(new PickVisualMedia(), uri -> {
    // Callback is invoked after the user selects a media item or closes the
    // photo picker.
    if (uri != null) {
        Log.d("PhotoPicker", "Selected URI: " + uri);
    } else {
        Log.d("PhotoPicker", "No media selected");
    }
});

// Include only one of the following calls to launch(), depending on the types
// of media that you want to let the user choose from.

// Launch the photo picker and let the user choose images and videos.
pickMedia.launch(new PickVisualMediaRequest.Builder()
        .setMediaType(PickVisualMedia.ImageAndVideo.INSTANCE)
        .build());

// Launch the photo picker and let the user choose only images.
pickMedia.launch(new PickVisualMediaRequest.Builder()
        .setMediaType(PickVisualMedia.ImageOnly.INSTANCE)
        .build());

// Launch the photo picker and let the user choose only videos.
pickMedia.launch(new PickVisualMediaRequest.Builder()
        .setMediaType(PickVisualMedia.VideoOnly.INSTANCE)
        .build());

// Launch the photo picker and let the user choose only images/videos of a
// specific MIME type, such as GIFs.
String mimeType = "image/gif";
pickMedia.launch(new PickVisualMediaRequest.Builder()
        .setMediaType(new PickVisualMedia.SingleMimeType(mimeType))
        .build());

اختيار وسائط متعددة

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

Kotlin

// Registers a photo picker activity launcher in multi-select mode.
// In this example, the app lets the user select up to 5 media files.
val pickMultipleMedia =
        registerForActivityResult(PickMultipleVisualMedia(5)) { uris ->
    // Callback is invoked after the user selects media items or closes the
    // photo picker.
    if (uris.isNotEmpty()) {
        Log.d("PhotoPicker", "Number of items selected: ${uris.size}")
    } else {
        Log.d("PhotoPicker", "No media selected")
    }
}

// For this example, launch the photo picker and let the user choose images
// and videos. If you want the user to select a specific type of media file,
// use the overloaded versions of launch(), as shown in the section about how
// to select a single media item.
pickMultipleMedia.launch(PickVisualMediaRequest(PickVisualMedia.ImageAndVideo))

Java

// Registers a photo picker activity launcher in multi-select mode.
// In this example, the app lets the user select up to 5 media files.
ActivityResultLauncher<PickVisualMediaRequest> pickMultipleMedia =
        registerForActivityResult(new PickMultipleVisualMedia(5), uris -> {
    // Callback is invoked after the user selects media items or closes the
    // photo picker.
    if (!uris.isEmpty()) {
        Log.d("PhotoPicker", "Number of items selected: " + uris.size());
    } else {
        Log.d("PhotoPicker", "No media selected");
    }
});

// For this example, launch the photo picker and let the user choose images
// and videos. If you want the user to select a specific type of media file,
// use the overloaded versions of launch(), as shown in the section about how
// to select a single media item.
pickMultipleMedia.launch(new PickVisualMediaRequest.Builder()
        .setMediaType(PickVisualMedia.ImageAndVideo.INSTANCE)
        .build());

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

توفر الجهاز

تتوفّر "أداة اختيار الصور" على الأجهزة التي تستوفي المعايير التالية:

الأجهزة القديمة التي تعمل بنظامَي التشغيل Android 4.4 (المستوى 19 لواجهة برمجة التطبيقات) وحتى Android 10 (المستوى 29 لواجهة برمجة التطبيقات) وأجهزة Android Go التي تعمل بالإصدار 11 أو 12 من نظام التشغيل Android المتوافقة يمكن لـ "خدمات Google Play" تثبيت إصدار في الإصدارات السابقة من "أداة اختيار الصور". لتفعيل التثبيت التلقائي لوحدة "أداة اختيار الصور" التي تمت إعادتها من خلال "خدمات Google Play"، أضِف الإدخال التالي إلى علامة <application> في ملف البيان الخاص بتطبيقك:

<!-- Trigger Google Play services to install the backported photo picker module. -->
<service android:name="com.google.android.gms.metadata.ModuleDependencies"
         android:enabled="false"
         android:exported="false"
         tools:ignore="MissingClass">
    <intent-filter>
        <action android:name="com.google.android.gms.metadata.MODULE_DEPENDENCIES" />
    </intent-filter>
    <meta-data android:name="photopicker_activity:0:required" android:value="" />
</service>

مواصلة الوصول إلى ملف الوسائط

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

Kotlin

val flag = Intent.FLAG_GRANT_READ_URI_PERMISSION
context.contentResolver.takePersistableUriPermission(uri, flag)

Java

int flag = Intent.FLAG_GRANT_READ_URI_PERMISSION;
context.contentResolver.takePersistableUriPermission(uri, flag);