このページは Cloud Translation API によって翻訳されました。

埋め込み写真選択ツール

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

埋め込み写真選択ツールは、アプリのユーザーインターフェース内で直接操作できる、別の形式の写真選択エクスペリエンスです。従来のフォトピッカーよりも、統合とカスタマイズのオプションが強化されています。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（推奨）または View を使用して統合できます。

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 を使用して埋め込み写真選択ツールを追加するには、レイアウトファイルにエントリを追加します。

<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)