انتخابگر عکس

گفتگوی انتخابگر عکس با فایل های رسانه ای در دستگاه شما ظاهر می شود. عکسی را برای اشتراک گذاری با برنامه انتخاب کنید.
شکل 1. انتخابگر عکس یک رابط کاربری بصری برای اشتراک گذاری عکس ها با برنامه شما فراهم می کند.

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

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

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

از قراردادهای Jetpack Activity استفاده کنید

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

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

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

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

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

دستگاه‌های قدیمی‌تر که از Android 4.4 (سطح API 19) تا Android 10 (سطح API 29) استفاده می‌کنند و دستگاه‌های Android Go دارای Android 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() را فراخوانی کنید:

کاتلین

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 با رمزگذاری

اندروید 13 (API 33) قابلیت فیلم برداری با محدوده دینامیکی بالا (HDR) را معرفی کرد. در حالی که HDR تجربه بصری غنی‌تری ارائه می‌دهد، ممکن است برخی از برنامه‌های قدیمی‌تر برای مدیریت این فرمت‌های جدیدتر مجهز نباشند، که منجر به مشکلاتی مانند نمایش رنگ غیرطبیعی در حین پخش (مانند چهره‌های سبز رنگ) می‌شود. برای رفع این شکاف سازگاری، انتخابگر عکس یک ویژگی رمزگذاری ارائه می‌کند که می‌تواند ویدیوهای HDR را قبل از ارائه به برنامه درخواست‌کننده به‌طور خودکار به فرمت استاندارد محدوده دینامیک (SDR) تبدیل کند.

هدف اصلی ترانکودینگ انتخابگر عکس، اطمینان از یک تجربه رسانه ای منسجم و دقیق از نظر بصری در طیف وسیع تری از برنامه ها است، حتی آنهایی که هنوز از پشتیبانی صریح HDR برخوردار نیستند. هدف انتخابگر عکس با تبدیل ویدیوی HDR به SDR بهبود سازگاری برنامه و ارائه یک تجربه کاربری یکپارچه است.

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

کدگذاری HDR انتخابگر عکس به طور پیش‌فرض فعال نیست. برای فعال کردن این ویژگی، برنامه شما باید به صراحت قابلیت های مدیریت قالب رسانه خود را هنگام راه اندازی انتخابگر عکس اعلام کند.

برنامه شما قابلیت های پردازش رسانه خود را در اختیار انتخابگر عکس قرار می دهد. این کار هنگام راه‌اندازی انتخابگر عکس با استفاده از کتابخانه AndroidX Activity با افزودن mediaCapabilities به PickVisualMediaRequest.Builder انجام می‌شود. یک API جدید، setMediaCapabilitiesForTranscoding(capabilities: MediaCapabilities?) به PickVisualMediaRequest.Builder اضافه شده است تا این کار را تسهیل کند.

با استفاده از کلاس MediaCapabilities می توانید رفتار رمزگذاری HDR را کنترل کنید. یک شی MediaCapabilities ارائه دهید که دقیقاً مشخص می کند برنامه شما از کدام نوع HDR پشتیبانی می کند (به عنوان مثال، TYPE_HLG10 ، TYPE_HDR10 ، TYPE_HDR10_PLUS ، TYPE_DOLBY_VISION ).

برای غیرفعال کردن کامل رمزگذاری، null برای MediaCapabilities ارسال کنید. هر نوع HDR که به صراحت در قابلیت های ارائه شده شما ذکر نشده باشد ، پشتیبانی نشده در نظر گرفته می شود. این API در Android 13 (سطح API 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

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