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

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

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

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

استخدام عقود "النشاط في Jetpack"

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

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

• PickVisualMedia لاختيار صورة واحدة أو فيديو واحد
• PickMultipleVisualMedia لاختيار عدة صور أو فيديوهات.

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

اختيار ملف وسائط واحد

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

// 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)))

// 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());

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

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

// 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))

// 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() ويتم تجاهل هذا الحد الأقصى على الأجهزة التي لا تتوفّر فيها "أداة اختيار الصور".

توفُّر جهاز

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

• أن يعمل بالإصدار 11 من نظام التشغيل Android (المستوى 30 من واجهة برمجة التطبيقات) أو إصدار أحدث
• تلقّي التغييرات على مكوّنات النظام المعيارية خلال تحديثات النظام من Google

الأجهزة الأقدم التي تعمل بالإصدار 4.4 من نظام التشغيل Android (المستوى 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() :

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

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