삽입된 사진 선택 도구

삽입된 사진 선택 도구는 앱의 사용자 인터페이스 내에서 직접 상호작용할 수 있는 다른 형태의 사진 선택 환경입니다. 기존 사진 선택기보다 향상된 통합 및 맞춤설정 옵션을 제공합니다. setChildSurfacePackage 메서드를 사용하여 SurfaceView에 렌더링되므로 비삽입 버전과 동일한 보안 및 개인 정보 보호 기능을 유지합니다.

삽입된 사진 선택 도구를 사용하면 사용자가 클라이언트 앱에서 포커스를 잃지 않고 기기와 클라우드 사진 라이브러리에서 사진과 동영상을 계속 선택할 수 있습니다. 클라이언트 앱은 활성 상태로 유지되고 활동은 재개된 상태이며 사용자 선택에 실시간으로 응답할 수 있습니다.

삽입된 사진 선택 도구는 더 원활한 UI 통합을 제공하지만 특수 SurfaceView에서 렌더링되므로 표준 사진 선택 도구와 동일한 보안 및 개인 정보 보호 기능을 유지합니다.

기기 사용가능 여부

삽입된 사진 선택기는 SDK 확장 프로그램 버전 15 이상이 적용된 Android 14 (API 수준 34)를 실행하는 기기에서 지원됩니다.

이러한 기능과 일치하지 않는 기기는 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(권장) 또는 뷰를 사용하여 삽입된 사진 선택기를 통합할 수 있습니다.

Jetpack Compose 통합

EmbeddedPhotoPicker 컴포저블 함수는 Jetpack Compose 화면 내에 삽입된 사진 선택 도구 UI를 직접 포함하는 메커니즘을 제공합니다. 이 컴포저블은 삽입된 사진 선택 도구 UI를 호스팅하는 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
    },
)

연속 선택

삽입된 사진 선택 도구를 사용하면 선택 도구를 닫지 않고도 사진 라이브러리에서 항목을 계속 선택하고 선택 해제할 수 있습니다. 앱의 UI에서 선택 및 선택 해제된 항목이 사진 선택기와 동기화되어 원활한 사용자 환경을 제공합니다.

pickerState에서 deselectUri 또는 deselectUris 메서드를 사용하여 Uri를 선택 해제하여 사용자 앱의 UI에서 항목을 선택 해제했음을 삽입된 선택기에 알립니다. 이러한 메서드를 호출해도 onUriPermissionRevoked 콜백을 통해 새로 취소된 URI가 앱에 알림으로 전송되지 않으므로 앱 UI 상태를 직접 업데이트해야 합니다.

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 Material 가이드라인에 따라 설정됩니다. 선택 도구의 강조 색상을 맞춤설정하려면 EmbeddedPhotoPickerFeatureInfo 옵션을 정의하세요.

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

EmbeddedPhotoPicker(
    embeddedPhotoPickerFeatureInfo = info,
    ...
)

강조 색상을 설정하지 않음	강조 색상 사용 (최대)	강조 색상 사용 (확장됨)

강조색은 완전히 불투명해야 합니다. 알파 (투명도) 값은 무시됩니다. 휘도 (밝기) 값이 0.05~0.9인 색상만 허용됩니다.

크기

기본적으로 삽입된 선택기의 크기는 제한되지 않지만 수정자를 지정하여 제한할 수 있습니다.

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

제한 없음 (확장됨)	500dp 제한 (확장)

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)