เครื่องมือเลือกรูปภาพที่ฝัง

เครื่องมือเลือกรูปภาพที่ฝังเป็นประสบการณ์การเลือกรูปภาพอีกรูปแบบหนึ่ง ซึ่งช่วยให้โต้ตอบได้โดยตรงภายในอินเทอร์เฟซผู้ใช้ของแอป โดยมีตัวเลือกการผสานรวมและการปรับแต่งที่ดียิ่งขึ้นเมื่อเทียบกับเครื่องมือเลือกรูปภาพแบบคลาสสิก เนื่องจากแสดงใน SurfaceView โดยใช้เมธอด setChildSurfacePackage จึงมีฟีเจอร์ด้านความปลอดภัยและความเป็นส่วนตัวเช่นเดียวกับเวอร์ชันที่ไม่ได้ฝัง

เครื่องมือเลือกรูปภาพแบบฝังช่วยให้ผู้ใช้เลือกรูปภาพและวิดีโอจากทั้งอุปกรณ์และคลังรูปภาพในระบบคลาวด์ได้อย่างต่อเนื่องโดยไม่เสียสมาธิในแอปไคลเอ็นต์ แอปไคลเอ็นต์จะยังคงทำงานอยู่ กิจกรรมของแอปจะอยู่ในสถานะกลับมาทำงานต่อ และตอบสนองต่อการเลือกของผู้ใช้ได้แบบเรียลไทม์

เครื่องมือเลือกรูปภาพแบบฝังมีการผสานรวม UI ที่ราบรื่นยิ่งขึ้น แต่ยังคงมีฟีเจอร์ด้านความปลอดภัยและความเป็นส่วนตัวเช่นเดียวกับเครื่องมือเลือกรูปภาพมาตรฐาน เนื่องจากมีการแสดงผลใน SurfaceView พิเศษ

อุปกรณ์ที่พร้อมจำหน่าย

เครื่องมือเลือกรูปภาพแบบฝังใช้ได้ในอุปกรณ์ที่ใช้ Android 14 (API ระดับ 34) ที่มี SDK Extensions เวอร์ชัน 15 ขึ้นไป

อุปกรณ์ที่ไม่ตรงกับความสามารถเหล่านี้จะใช้เครื่องมือเลือกรูปภาพแบบคลาสสิกหรือเวอร์ชันที่พอร์ตไปยังเวอร์ชันเก่าโดยใช้บริการ Google Play ได้

ทรัพยากร Dependency ของไลบรารี Jetpack

รวมไลบรารีเครื่องมือเลือกรูปภาพ Jetpack เป็นทรัพยากร Dependency โดยทำดังนี้

// 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ฟังก์ชันที่ใช้ร่วมกันได้มีกลไกในการรวม UI ของเครื่องมือเลือกรูปภาพที่ฝังไว้ภายในหน้าจอ Jetpack Compose โดยตรง Composable นี้จะสร้าง SurfaceView ซึ่งโฮสต์ UI ของเครื่องมือเลือกรูปภาพแบบฝัง โดยจะ จัดการการเชื่อมต่อกับ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
    },
)

การเลือกอย่างต่อเนื่อง

เครื่องมือเลือกรูปภาพที่ฝังไว้ช่วยให้ผู้ใช้เลือกและยกเลิกการเลือกรายการจากคลังรูปภาพได้อย่างต่อเนื่องโดยไม่ต้องปิดเครื่องมือเลือก ระบบจะซิงค์รายการที่เลือกและยกเลิกการเลือกใน UI ของแอปกับเครื่องมือเลือกรูปภาพ เพื่อมอบประสบการณ์การใช้งานที่ราบรื่นให้แก่ผู้ใช้

ยกเลิกการเลือกUriโดยใช้วิธีdeselectUriหรือdeselectUrisจาก pickerState เพื่อแจ้งให้เครื่องมือเลือกที่ฝังทราบว่าผู้ใช้ได้ยกเลิกการเลือกรายการ จาก UI ของแอป คุณต้องอัปเดตสถานะ UI ของแอปด้วยตนเอง เนื่องจาก การเรียกใช้เมธอดเหล่านี้จะไม่แจ้งให้แอปทราบถึง 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
}

ปรับเปลี่ยนเครื่องมือเลือกรูปภาพในแบบของคุณ

เครื่องมือเลือกรูปภาพแบบฝังมีตัวเลือกสำหรับการปรับเปลี่ยนในแบบของคุณ ซึ่งช่วยให้คุณ ปรับแต่งลักษณะที่ปรากฏและลักษณะการทำงานของเครื่องมือให้ผสานรวมกับการออกแบบแอป และประสบการณ์ของผู้ใช้ได้ดียิ่งขึ้น

สีเฉพาะจุด

โดยค่าเริ่มต้น เครื่องมือเลือกรูปภาพที่ฝังจะอิงตามสีแบบไดนามิกที่ระบบระบุซึ่งผู้ใช้สามารถตั้งค่าในแอปต่างๆ ในตัวเลือกการจัดธีมของอุปกรณ์ ระบบจะใช้สีเน้นสำหรับองค์ประกอบหลักต่างๆ ในเครื่องมือเลือกรูปภาพ ระบบจะกำหนดสีอื่นๆ ทั้งหมดตามหลักเกณฑ์ของ Material Design ใน Android หากต้องการปรับเปลี่ยนสีเน้นของเครื่องมือเลือก ให้กำหนด EmbeddedPhotoPickerFeatureInfo option ดังนี้

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)