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

انتخاب‌گر عکس جاسازی‌شده شکل متفاوتی از تجربه انتخاب عکس است، که امکان تعامل مستقیم در میانای کاربر برنامه‌ها را فراهم می‌کند. این میانای برنامه‌سازی کاربردی درمقایسه با انتخاب‌گر عکس کلاسیک، گزینه‌های سفارشی‌سازی و ادغام بهبودیافته‌ای ارائه می‌دهد. ازآنجایی‌که این ویژگی بااستفاده از روش setChildSurfacePackage در SurfaceView ارائه می‌شود، همان ویژگی‌های امنیتی و حریم خصوصی نسخه جاسازی‌نشده را حفظ می‌کند.

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

انتخاب‌گر عکس جاسازی‌شده ادغام واسط کاربر یکپارچه‌تری ارائه می‌دهد اما همان ویژگی‌های امنیتی و حریم خصوصی انتخاب‌گر عکس استاندارد را حفظ می‌کند زیرا در SurfaceView خاصی ارائه می‌شود.

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

انتخاب‌گر عکس جاسازی‌شده در دستگاه‌های دارای Android 14 (سطح API‏ ۳۴) با «افزونه‌های کیت توسعه نرم‌افزار» نسخه ۱۵ یا بالاتر پشتیبانی می‌شود.

دستگاه‌هایی که با این قابلیت‌ها مطابقت ندارند می‌توانند بااستفاده از خدمات Google Play به انتخاب‌گر عکس کلاسیک یا نسخه سازگار با نسخه‌های قدیمی‌تر متکی باشند.

وابستگی کتابخانه Jetpack

کتابخانه انتخاب‌گر عکس Jetpack را به‌عنوان وابستگی اضافه کنید:

// For apps using Jetpack Compose
implementation("androidx.photopicker:photopicker-compose:1.0.0-alpha01")

// For apps using Views
implementation("androidx.photopicker:photopicker:1.0.0-alpha01")

می‌توانید انتخاب‌گر عکس جاسازی‌شده را بااستفاده از Jetpack Compose (توصیه‌شده) یا Views ادغام کنید.

ادغام Jetpack Compose

تابع ترکیب‌پذیر EmbeddedPhotoPicker مکانیزمی برای گنجاندن میانای کاربری انتخاب‌گر عکس جاسازی‌شده مستقیماً در صفحه Jetpack Compose ارائه می‌دهد. این composable یک SurfaceView ایجاد می‌کند که میزبان میانای کاربری انتخاب‌گر عکس جاسازی‌شده است. این اتصال به سرویس EmbeddedPhotoPicker را مدیریت می‌کند، تعاملات کاربر را اداره می‌کند، و URIهای رسانه انتخاب‌شده را با چند پارامتر برای کار کردن به برنامه تماس‌گیرنده منتقل می‌کند:

val coroutineScope = rememberCoroutineScope()
val pickerState = rememberEmbeddedPhotoPickerState()

EmbeddedPhotoPicker(
    state = pickerState,
    onUriPermissionGranted = { uris ->
        _attachments.value += uris
    },
    onUriPermissionRevoked = { uris ->
        _attachments.value -= uris
    },
    onSelectionComplete = {
        // Hide the embedded photo picker as the user is done with the
        // photo/video selection
    },
)

انتخاب پیوسته

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

بااستفاده از روش deselectUri یا deselectUris، انتخاب Uri را لغو کنیدpickerState تا به انتخابگر جاسازی‌شده اطلاع داده شود که کاربر انتخاب موردی را از واسط کاربر برنامه لغو کرده است. به‌روزرسانی دستی وضعیت واسط کاربر برنامه خودتان ضروری است، زیرا فراخوانی این روش‌ها برنامه شما را از شناسه‌های URI جدیداً لغوشده ازطریق فراخوانی برگشتی onUriPermissionRevoked مطلع نمی‌کند.

coroutineScope.launch {
    // Signal unselected media to the picker
    pickerState.deselectUris(uris)
    // Remove them from the list of selected media to be reflected in the app's UI
    _attachments.value -= uris
}

شخصی‌سازی کردن انتخاب‌گر عکس

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

رنگ تأکیدی

به‌طور پیش‌فرض، انتخاب‌گر عکس جاسازی‌شده به رنگ‌های پویای ارائه‌شده توسط سیستم متکی است که کاربر می‌تواند در گزینه‌های زمینه‌سازی دستگاه در سراسر برنامه‌ها تنظیم کند. از رنگ تأکیدی برای عناصر اصلی مختلف در انتخاب‌گر عکس استفاده خواهد شد. همه رنگ‌های دیگر براساس دستورالعمل‌های طراحی متریال Android تنظیم خواهد شد. برای شخصی‌سازی رنگ ثانویه انتخاب‌گر، گزینه EmbeddedPhotoPickerFeatureInfo را تعریف کنید:

val info = EmbeddedPhotoPickerFeatureInfo.Builder().setAccentColor(0xFF0000).build()

EmbeddedPhotoPicker(
    embeddedPhotoPickerFeatureInfo = info,
    ...
)

بدون تنظیم رنگ ثانویه	با رنگ ثانویه (اوج)	با رنگ ثانویه (ازهم بازشده)

رنگ ثانویه باید کاملاً مات باشد. مقدار آلفا (شفافیت) نادیده گرفته می‌شود. فقط رنگ‌هایی که مقدار درخشندگی (روشنایی) آن‌ها بین ۰٫۰۵ و ۰٫۹ باشد مجاز هستند.

ابعاد

به‌طور پیش‌فرض، اندازه انتخاب‌گر جاسازی‌شده محدود نیست اما می‌توانید اصلاح‌کننده‌ای برای محدود کردن آن مشخص کنید:

EmbeddedPhotoPicker(
    modifier = Modifier.height(500.dp),
    ...
)

بدون محدودیت (گسترش‌یافته)	با محدودیت ۵۰۰ dp (گسترش‌یافته)

یکپارچه‌سازی Views

برای افزودن انتخاب‌گر عکس جاسازی‌شده بااستفاده از Views، ورودی‌ای به فایل چیدمانتان اضافه کنید:

<view class="androidx.photopicker.EmbeddedPhotoPickerView"
    android:id="@+id/photopicker"
    android:layout_width="match_parent"
    android:layout_height="match_parent" />

سپس، انتخاب‌گر عکس را در روش onCreate فعالیتتان با انجام دادن کارهای زیر مقداردهی اولیه کنید:

1. مرجعی برای EmbeddedPhotoPickerView از چیدمان دریافت کنید
2. EmbeddedPhotoPickerStateChangeListener را برای مدیریت رویدادهای انتخاب اضافه کنید
3. انتخاب‌گر عکس را با EmbeddedPhotoPickerFeatureInfo پیکربندی کنید، ازجمله هرگونه تنظیمات سفارشی مانند رنگ ثانویه

// Keep track of the selected media
private val _attachments = MutableStateFlow(emptyList<Uri>())
val attachments = _attachments.asStateFlow()

private lateinit var picker: EmbeddedPhotoPickerView
private var openSession: EmbeddedPhotoPickerSession? = null

val pickerListener = object : EmbeddedPhotoPickerStateChangeListener {
    override fun onSessionOpened(newSession: EmbeddedPhotoPickerSession) {
        // Keep reference to the session to notify the embedded picker of user
        // interactions on the calling app
        openSession = newSession
    }

    override fun onSessionError(throwable: Throwable) {}

    override fun onUriPermissionGranted(uris: List<Uri>) {
        // Add newly selected media to our tracked list
        _attachments += uris
    }

    override fun onUriPermissionRevoked(uris: List<Uri>) {
        // Remove newly unselected media from our tracked list
        _attachments -= uris
    }

    override fun onSelectionComplete() {
        // Hide the embedded photo picker as the user is done with the
        // photo/video selection
    }
}

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)

    setContentView(R.layout.main_view)
    picker = findViewById(R.id.photopicker)

    // Attach the embedded picker event listener to update the app's UI
    picker.addEmbeddedPhotoPickerStateChangeListener(pickerListener)

    // Customize embedded picker's features: accent color, max selectable items,
    // pre-selected URIs, filter out mime types
    picker.setEmbeddedPhotoPickerFeatureInfo(
        // Set a custom accent color
        EmbeddedPhotoPickerFeatureInfo.Builder().setAccentColor(0xFF0000).build()
    )
}

می‌توانید با روش‌های مختلف EmbeddedPhotoPickerSession تماس بگیرید تا با انتخابگر جاسازی‌شده تعامل داشته باشید:

// Notify the embedded picker of a configuration change
openSession.notifyConfigurationChanged(newConfig)

// Update the embedded picker to expand following a user interaction
openSession.notifyPhotoPickerExpanded(/* expanded: */ true)

// Resize the embedded picker
openSession.notifyResized(/* width: */ 512, /* height: */ 256)

// Show/hide the embedded picker (after a form has been submitted)
openSession.notifyVisibilityChanged(/* visible: */ false)

// Remove unselected media from the embedded picker after they have been
// unselected from the host app's UI
openSession.requestRevokeUriPermission(removedUris)