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

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

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

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

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

استخدام عقود 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

ويمكن تثبيت إصدار محمَّل عكسيًا من الأداة على الأجهزة القديمة التي تعمل بالإصدار 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 لتسهيل ذلك.

يمكنك التحكّم في سلوك تحويل ترميز النطاق العالي الديناميكية باستخدام الفئة 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

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

أداة اختيار الصور تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

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

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

المشاهدات

المشاهدات

إنشاء

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

المشاهدات

المشاهدات

إنشاء

توفر الجهاز

الاحتفاظ بإذن الوصول إلى ملفات الوسائط

Kotlin

Java

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

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

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

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