埋め込み写真選択ツール

連続写真選択ツールの選択プロセスを示すアニメーション

埋め込み型の写真選択ツールは、アプリのユーザーインターフェース内で直接操作できる、別の形式の写真選択エクスペリエンスです。従来の写真選択ツールと比較して、統合とカスタマイズのオプションが強化されています。setChildSurfacePackage メソッドを使用して SurfaceView にレンダリングされるため、埋め込み型でないバージョンと同じセキュリティ機能とプライバシー機能が維持されます。

埋め込み型の写真選択ツールを使用すると、クライアントアプリのフォーカスを失うことなく、デバイスとクラウドフォトライブラリの両方から写真や動画を継続的に選択できます。クライアントアプリはアクティブな状態を維持し、アクティビティは再開状態になるため、ユーザーの選択にリアルタイムで対応できます。

埋め込み型の写真選択ツールは、特別な SurfaceView にレンダリングされるため、標準の写真選択ツールと同じセキュリティ機能とプライバシー機能を維持しながら、よりシームレスな UI 統合を実現します。

利用可能なデバイス

埋め込み型の写真選択ツールは、SDK Extensions バージョン 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 （推奨）または Views を使用して統合できます。

Jetpack Compose との統合

EmbeddedPhotoPicker コンポーズ可能な関数は、埋め込み型の写真選択ツール UI を Jetpack Compose 画面に直接含めるメカニズムを提供します。このコンポーザブルは、埋め込み型の写真選択ツール 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 マテリアルガイドラインに基づいて設定されます。選択ツールのアクセントカラーをカスタマイズするには、EmbeddedPhotoPickerFeatureInfo オプションを定義します。

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

EmbeddedPhotoPicker(
    embeddedPhotoPickerFeatureInfo = info,
    ...
)

アクセントカラーを設定しない場合	アクセントカラーを設定する場合（ピーク）	アクセントカラーを設定する場合（展開）

アクセントカラーは完全に不透明にする必要があります。アルファ値（透明度）は無視されます。輝度（明るさ）の値が 0.05 ～ 0.9 の色のみが許可されます。

サイズ

デフォルトでは、埋め込み型の選択ツールのサイズに制限はありませんが、修飾子を指定して制限できます。

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

制限なし（展開）	500 dp の制限あり（展開）

Views との統合

Views を使用して埋め込み型の写真選択ツールを追加するには、レイアウトファイルにエントリを追加します。

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

次に、アクティビティの onCreate メソッドで写真選択ツールを初期化します。手順は次のとおりです。

レイアウトから EmbeddedPhotoPickerView への参照を取得します。
EmbeddedPhotoPickerStateChangeListener を追加して選択イベントを処理します。
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)

埋め込み写真選択ツール コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。