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

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

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

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

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

انتخابگر عکس جاسازی شده در دستگاه‌های دارای Android 14 (سطح API 34) با برنامه‌های افزودنی SDK نسخه 15 یا بالاتر پشتیبانی می‌شود.

دستگاه‌هایی که با این قابلیت‌ها مطابقت ندارند، می‌توانند به انتخابگر عکس کلاسیک یا نسخه پشتیبان‌شده با استفاده از خدمات 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 شما قرار دهد. این قابل ترکیب یک 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
    },
)

انتخاب مستمر

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

Uri با استفاده از روش deselectUri یا deselectUris از 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
}

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

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

رنگ تاکیدی

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

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

EmbeddedPhotoPicker(
    embeddedPhotoPickerFeatureInfo = info,
    ...
)

بدون تنظیم رنگ تاکیدی	با رنگ تاکیدی (اوج)	با رنگ تاکیدی (بسط یافته)

رنگ تاکیدی باید کاملاً مات باشد. مقدار آلفا (شفافیت) نادیده گرفته می شود. فقط رنگ هایی با مقدار روشنایی (روشنایی) بین 0.05 تا 0.9 مجاز هستند.

ابعاد

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

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

بدون محدودیت (بسط یافته)	با محدودیت 500 dp (بسط یافته)

ادغام نماها

برای افزودن انتخابگر عکس جاسازی شده با استفاده از 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)