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

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

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

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

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

استخدام عقود Jetpack Activity

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

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

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

إذا لم تكن "أداة اختيار الصور" متاحة على أحد الأجهزة، ستستدعي المكتبة تلقائيًا إجراء الغرض ACTION_OPEN_DOCUMENT بدلاً من ذلك. تتوفّر هذه الغاية على الأجهزة التي تعمل بالإصدار 4.4 من نظام التشغيل Android (المستوى 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 single-select mode.
val pickMedia = rememberLauncherForActivityResult(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 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());

إنشاء

// 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 =
        rememberLauncherForActivityResult(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))

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

توفُّر جهاز

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

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

ويمكن تثبيت "أداة اختيار الصور" في إصدارات سابقة من Android على الأجهزة القديمة التي تعمل بالإصدار 4.4 (المستوى 19 من واجهة برمجة التطبيقات) إلى الإصدار 10 (المستوى 29 من واجهة برمجة التطبيقات) من نظام التشغيل Android وكذلك أجهزة Android Go التي تعمل بالإصدار 11 أو 12 من نظام التشغيل ذاته والمتوافقة مع "خدمات 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);

التعامل مع فيديوهات HDR باستخدام ميزة تحويل الترميز

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

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

آلية عمل تحويل الترميز في "أداة اختيار الصور"

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

يوفّر تطبيقك إمكانات معالجة الوسائط لأداة اختيار الصور. يتم ذلك عند تشغيل أداة اختيار الصور باستخدام مكتبة AndroidX Activity من خلال إضافة mediaCapabilities إلى PickVisualMediaRequest.Builder. تمت إضافة واجهة برمجة تطبيقات جديدة، setMediaCapabilitiesForTranscoding(capabilities: MediaCapabilities?)، إلى PickVisualMediaRequest.Builder لتسهيل ذلك.

يمكنك التحكّم في سلوك تحويل الترميز بتنسيق HDR باستخدام الفئة MediaCapabilities. قدِّم عنصر MediaCapabilities يحدّد أنواع HDR التي يتوافق معها تطبيقك (على سبيل المثال، TYPE_HLG10، TYPE_HDR10، TYPE_HDR10_PLUS، TYPE_DOLBY_VISION).

لإيقاف تحويل الترميز بالكامل، مرِّر القيمة null إلى MediaCapabilities. سيتم اعتبار أي نوع من أنواع HDR غير مدرَج صراحةً في الإمكانات التي تقدّمها غير متوافق. تتوفّر واجهة برمجة التطبيقات هذه على الإصدار 13 من نظام التشغيل Android (المستوى 33 لواجهة برمجة التطبيقات) والإصدارات الأحدث، ويتم وضع التعليق التوضيحي @RequiresApi(Build.VERSION_CODES.TIRAMISU) عليها.

import androidx.activity.result.PickVisualMediaRequest
import androidx.activity.result.contract.ActivityResultContracts.PickVisualMedia
import androidx.annotation.RequiresApi
import android.os.Build
import android.util.Log
import android.provider.MediaStore

// Registers a photo picker activity launcher.
val pickMedia = registerForActivityResult(PickVisualMedia()) { uri ->
    // Callback invoked after media selected or picker activity closed.
    if (uri != null) {
        Log.d("photo picker", "Selected URI: $uri")
    } else {
        Log.d("photo picker", "No media selected")
    }
}

@RequiresApi(Build.VERSION_CODES.TIRAMISU)
fun launchPhotoPickerWithTranscodingSupport() {
    val mediaCapabilities = MediaCapabilities.Builder()
        .addSupportedHdrType(MediaCapabilities.HdrType.TYPE_HLG10)
        .build()

    // Launch the photo picker and let the user choose only videos with
    // transcoding enabled.
    pickMedia.launch(PickVisualMediaRequest.Builder()
        .setMediaType(PickVisualMedia.VideoOnly)
        .setMediaCapabilitiesForTranscoding(mediaCapabilities)
        .build())
}

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

اعتبارات مهمة بشأن تحويل ترميز HDR

الأداء ومساحة التخزين: تستغرق عملية تحويل الترميز وقتًا وتؤدي إلى إنشاء ملف جديد يستهلك مساحة تخزين.
الحد الأقصى لمدة الفيديو: لتحقيق التوازن بين تجربة المستخدم وقيود مساحة التخزين، يبلغ الحد الأقصى لمدة الفيديو دقيقة واحدة.
إدارة الملفات المخزّنة مؤقتًا: يتم محو الملفات المخزّنة مؤقتًا والمحوّلة ترميزًا بشكل دوري أثناء الصيانة في وضع عدم النشاط لمنع الاستخدام المفرط لمساحة التخزين.
الأجهزة المتوافقة: تتوفّر ميزة تحويل الترميز في "أداة اختيار الصور" على Android 13 (المستوى 33 لواجهة برمجة التطبيقات) والإصدارات الأحدث.
دمج نشاط AndroidX: تأكَّد من استخدام الإصدار 1.11.0-alpha01 أو إصدار أحدث من الإصدارات التجريبية أو الإصدارات التجريبية الأولية أو إصدارات المرشّح للإصدار أو الإصدارات الثابتة من مكتبة AndroidX Activity، لأنّ ذلك يتضمّن واجهة برمجة التطبيقات setMediaCapabilitiesForTranscoding اللازمة.