‫Google برای ترجمه محتوا به زبان ترجیحی شما از فناوری هوشواره استفاده می‌کند. ترجمه‌های هوشواره‌ای ممکن است اشتباه داشته باشند.

انتخاب‌گر عکس

انتخاب‌گر عکس میانای قابل‌مروری ارائه می‌دهد که کتابخانه رسانه‌ای کاربر را به‌ترتیب تاریخ از جدیدترین به قدیمی‌ترین به او نشان می‌دهد. همان‌طور که در codelab روال‌های مطلوب حریم خصوصی نشان داده شده است، انتخاب‌گر عکس روشی ایمن و داخلی برای کاربران فراهم می‌کند تا به برنامه شما اجازه دسترسی به فقط تصاویر و ویدیوهای انتخاب‌شده را بدهند، نه کل کتابخانه رسانه‌ای‌شان.

کاربرانی که ارائه‌دهندگان رسانه ابری واجدشرایط در دستگاهشان دارند نیز می‌توانند از عکس‌ها و ویدیوهای ذخیره‌شده ازراه‌دور انتخاب کنند. درباره ارائه‌دهندگان رسانه ابری بیشتر بدانید.

این ابزار به‌طور خودکار به‌روز می‌شود و با گذشت زمان، بدون نیاز به تغییر کد، عملکرد گسترده‌تری را به کاربران برنامه‌تان ارائه می‌دهد.

استفاده از قراردادهای فعالیت Jetpack

برای ساده کردن ادغام انتخاب‌گر عکس، نسخه ۱.۷.۰ یا بالاتر کتابخانه androidx.activity را اضافه کنید.

از قراردادهای نتیجه فعالیت زیر برای راه‌اندازی انتخاب‌گر عکس استفاده کنید:

PickVisualMedia برای انتخاب یک تصویر یا ویدیو.
PickMultipleVisualMedia را برای انتخاب چند تصویر یا ویدیو انتخاب کنید.

اگر انتخاب‌گر عکس در دستگاهی دردسترس نباشد، کتابخانه به‌طور خودکار کنش هدف ACTION_OPEN_DOCUMENT را به‌جای آن فراخوانی می‌کند. این هدف در دستگاه‌هایی که Android نسخه ۴.۴ (سطح میانای برنامه‌سازی کاربردی ۱۹) یا بالاتر دارند پشتیبانی می‌شود. با فراخوانی 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() تماس بگیرید. در دستگاه‌هایی که از انتخاب‌گر عکس پشتیبانی نمی‌کنند، این محدودیت نادیده گرفته می‌شود.

دردسترس بودن دستگاه

انتخاب‌گر عکس در دستگاه‌هایی که معیارهای زیر را داشته باشند دردسترس است:

‫Android 11 (سطح میانای برنامه‌سازی کاربردی ۳۰) یا بالاتر را اجرا کند
دریافت تغییرات اجزای سیستم مدولار ازطریق به‌روزرسانی‌های سیستم Google

دستگاه‌های قدیمی‌تر که Android 4.4 (سطح میانای برنامه‌سازی کاربردی ۱۹) تا Android 10 (سطح میانای برنامه‌سازی کاربردی ۲۹) را اجرا می‌کنند و دستگاه‌های Android Go که Android 11 یا ۱۲ را اجرا می‌کنند و از خدمات 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);

مدیریت ویدیو HDR با تراتبدیل

Android 13 (میانای برنامه‌سازی کاربردی سطح ۳۳) قابلیت ضبط ویدیوهای دامنه پویای بالا (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 که به‌طور صریح در قابلیت‌های ارائه‌شده شما فهرست نشده باشد، به‌عنوان پشتیبانی‌نشده درنظر گرفته خواهد شد. این میانای برنامه‌سازی کاربردی در Android 13 (سطح میانای برنامه‌سازی کاربردی ۳۳) و بالاتر پشتیبانی می‌شود و با @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())
}

تراتبدیل توسط انتخاب‌گر عکس براساس قابلیت‌های رسانه‌ای برنامه و ویدیو انتخاب‌شده انجام می‌شود. اگر تراتبدیل انجام شود، شناسه منبع یکسان برای ویدیو تراتبدیل‌شده برگردانده می‌شود.

ملاحظات مهم برای تراتبدیل HDR

عملکرد و فضای ذخیره‌سازی: تراتبدیل زمان پردازش می‌برد و فایل جدیدی ایجاد می‌کند که فضای ذخیره‌سازی را مصرف می‌کند.
محدودیت طول ویدیو: برای ایجاد تعادل بین تجربه کاربری و محدودیت‌های فضای ذخیره‌سازی، محدودیت ۱ دقیقه‌ای برای طول ویدیو وجود دارد.
مدیریت فایل‌های ذخیره‌شده در حافظه نهان: فایل‌های تراتبدیل‌شده ذخیره‌شده در حافظه نهان به‌طور دوره‌ای درطول تعمیرات در زمان عدم استفاده پاک می‌شوند تا از مصرف بیش‌ازحد فضای ذخیره‌سازی جلوگیری شود.
دردسترس بودن دستگاه: تراتبدیل انتخاب‌گر عکس در Android 13 (سطح میانای برنامه‌سازی کاربردی ۳۳) و نسخه‌های جدیدتر پشتیبانی می‌شود.
ادغام فعالیت AndroidX: مطمئن شوید که از نسخه 1.11.0-alpha01 یا نسخه آلفا/بتا/RC/پایدار جدیدتر کتابخانه AndroidX Activity استفاده می‌کنید، زیرا این نسخه شامل setMediaCapabilitiesForTranscoding API لازم است.

انتخاب‌گر عکس با مجموعه‌ها، منظم بمانید ذخیره و طبقه‌بندی محتوا براساس اولویت‌های شما.

استفاده از قراردادهای فعالیت Jetpack

یک فایل رسانه‌ای را انتخاب کنید

بازدیدها

بازدیدها

نوشتن

انتخاب کردن چند فایل رسانه‌ای

بازدیدها

بازدیدها

نوشتن

دردسترس بودن دستگاه

دسترسی به فایل رسانه را حفظ کنید

کاتلین

جاوا

مدیریت ویدیو HDR با تراتبدیل

نحوه عملکرد تراتبدیل انتخاب‌گر عکس

ملاحظات مهم برای تراتبدیل HDR

انتخاب‌گر عکس