アクティビティの埋め込み

アクティビティの埋め込みは、大画面デバイス上のアプリのタスクウィンドウを 2 つのアクティビティ、または同じアクティビティの 2 つのインスタンスに分割することでアプリを最適化する機能です。

大画面をサポートするために従来のコードベースを更新する作業には、多大な労力と時間がかかります。フラグメントを使用してアクティビティベースのアプリをマルチペインレイアウトに変換するには、大規模なリファクタリングが必要です。

アクティビティの埋め込みでは、アプリのリファクタリングはほとんど必要ありません。XML 構成ファイルを作成するか、Jetpack WindowManager API 呼び出しを行うことで、アプリがアクティビティを並べて表示するか重ねて表示するかを決定できます。

小画面のサポートは自動的に維持されます。アプリが小画面のデバイスにある場合、アクティビティは互いに重ねられます。大画面の場合、アクティビティは並べて表示されます。作成した構成に基づいてシステムで表示方法が判断されます。分岐ロジックは必要ありません。

アクティビティの埋め込みでは、デバイスの向きを変えられます。折りたたみ式デバイスでもシームレスに動作し、デバイスの折りたたみと展開に合わせて、アクティビティの積み重ねと積み重ねの解除が行われます。

最新の Android 開発では、フラグメント、ナビゲーションコンポーネント、SlidingPaneLayout のような多用途レイアウトマネージャーを備えた、単一アクティビティアーキテクチャが採用されています。

しかし、複数のアクティビティで構成されているアプリの場合、アクティビティの埋め込みを使用することで、タブレット、折りたたみ式デバイス、ChromeOS デバイスでのユーザーエクスペリエンスを簡単に向上させることができます。

アクティビティの埋め込みは、Android 12L（API レベル 32）以降でサポートされています。

分割タスクウィンドウ

アクティビティの埋め込みは、アプリのタスクウィンドウをプライマリとセカンダリという 2 つのコンテナに分割します。コンテナは、メインアクティビティから起動されたアクティビティ、またはコンテナ内にすでに存在する他のアクティビティから起動されたアクティビティを保持します。

アクティビティは、起動時にセカンダリコンテナ内で重ねられ、小画面ではセカンダリコンテナがプライマリコンテナの上に重ねられるため、アクティビティの積み重ねと「戻る」ナビゲーションは、アプリにすでに組み込まれているアクティビティの順序と一致します。

アクティビティの埋め込みを使用すると、さまざまな方法でアクティビティを表示できます。アプリは、2 つのアクティビティを同時に並べて起動することで、タスクウィンドウを分割できます。

また、タスクウィンドウ全体を占有するアクティビティは、新しいアクティビティを並べて起動することで、タスクウィンドウを分割できます。

すでに分割されてタスクウィンドウを共有しているアクティビティは、次の方法で他のアクティビティを起動できます。

横のアクティビティの上に重ねて起動:

図 4. アクティビティ A が、横のアクティビティ B の上にアクティビティ C を重ねて起動。
横に起動し、分割を横にシフトして以前のプライマリアクティビティを非表示にする:

図 5. アクティビティ B が、横にアクティビティ C を起動して分割を横にシフト。
アクティビティをその場所の一番上（つまり同じアクティビティスタック）に起動:

図 6. アクティビティ B が、追加のインテントフラグなしでアクティビティ C を起動。
アクティビティをそのタスクのフルウィンドウで起動:

図 7. アクティビティ A またはアクティビティ B が、タスクウィンドウいっぱいにアクティビティ C を起動。

「戻る」ナビゲーション

アクティビティ間の依存関係やユーザーが「戻る」イベントをトリガーする方法に応じて、分割タスクウィンドウ状態での「戻る」ナビゲーションのルールはアプリの種類によって異なる場合があります。次に例を示します。

一緒に: アクティビティ同士に関連性があり、一方のアクティビティを他方のアクティビティなしで表示すべきでない場合、両方を終了させるように「戻る」ナビゲーションを設定できます。
単独で: タスクウィンドウ内のアクティビティ同士が完全に独立している場合、一方のアクティビティの「戻る」ナビゲーションは、他方のアクティビティの状態に影響を与えません。

ボタンナビゲーションを使用する場合、「戻る」イベントは最後にフォーカスされたアクティビティに送信されます。ジェスチャーベースのナビゲーションの場合、「戻る」イベントはジェスチャーが行われたアクティビティに送信されます。

マルチペインレイアウト

Jetpack WindowManager 1.1.0 Alpha04 を使用すると、12L（API レベル 32）を搭載した大画面デバイスと、以前のバージョンのプラットフォームを搭載した一部のデバイスで、アクティビティを使ったマルチペインレイアウトを構築できます。フラグメントやビューベースのレイアウト（SlidingPaneLayout など）ではなく複数のアクティビティに基づく既存のアプリは、大幅なリファクタリングを必要とせずに、大画面のユーザーエクスペリエンスを向上させることができます。

一般的な例としては、リストと詳細の分割が挙げられます。質の高い表示を確保するために、システムはリストアクティビティを起動し、その後アプリは直ちに詳細アクティビティを起動します。遷移システムは、両方のアクティビティが描画されるまで待機してから、一緒に表示します。ユーザーにとっては、2 つのアクティビティが 1 つのものとして起動します。

**図 8.** マルチペインレイアウトで同時に起動した 2 つのアクティビティ。

分割比

アプリは、分割の設定の ratio 属性によって、タスクウィンドウの比率を指定できます（後述の分割の設定をご覧ください）。

プレースホルダ

プレースホルダアクティビティは、アクティビティ分割の領域を占有する空のセカンダリアクティビティです。最終的には、コンテンツを含む別のアクティビティに置き換えられます。たとえばプレースホルダアクティビティは、リストのアイテムが選択されるまで、リストと詳細のレイアウトでアクティビティ分割のセカンダリ側を占有します。選択された時点で、プレースホルダは選択されたリストアイテムの詳細情報を含むアクティビティに置き換えられます。

プレースホルダは、分割に十分なスペースがある場合にのみ表示されます。ディスプレイサイズがアクティビティ分割を表示できないほど小さな幅に変更されると自動的に終了しますが、スペースが許せば自動的に（再初期化した状態で）再起動します。

ウィンドウサイズの変更

デバイス構成の変更によってタスクウィンドウの幅が小さくなり、マルチペインレイアウトに十分な大きさでなくなった場合（大画面の折りたたみ式デバイスがタブレットサイズからスマートフォンサイズに折りたたまれた場合や、マルチウィンドウモードでアプリウィンドウがサイズ変更された場合など）、タスクウィンドウのセカンダリペインにあるプレースホルダ以外のアクティビティが、プライマリペインのアクティビティの上に重ねられます。

プレースホルダのアクティビティは、分割するために十分な表示幅がある場合にのみ表示されます。小画面では、プレースホルダは自動的に閉じられます。表示領域が再び十分な大きさになると、プレースホルダが再作成されます（前述のプレースホルダをご覧ください）。

アクティビティを重ねることができるのは、WindowManager がセカンダリペインのアクティビティをプライマリペインのアクティビティの上に Z オーダーで表示するためです。

セカンダリペインの複数のアクティビティ

アクティビティ B が追加のインテントフラグなしで、アクティビティ C を所定の位置で起動します。

アクティビティ C がアクティビティ B の上に重ねられた、アクティビティ A、B、C を含むアクティビティ分割。

その結果、同じタスクのアクティビティの Z オーダーは次のようになります。

アクティビティ B の上に重ねられたアクティビティ C を含むセカンダリアクティビティスタック。セカンダリスタックが、アクティビティ A を含むプライマリアクティビティスタックの上に重ねられています。

タスクウィンドウが小さくなるとアプリは 1 つのアクティビティに縮小され、アクティビティ C がスタックの一番上に重ねられます。

アクティビティ C のみを表示する小さいウィンドウ。

小さいウィンドウで「戻る」操作を行うと、重ねられた各アクティビティ間で移動します。

タスクウィンドウ構成を、複数のペインに対応できる大きなサイズに復元すると、アクティビティは再び並んで表示されます。

分割の積み重ね

アクティビティ B が、横にアクティビティ C を起動して分割を横にシフトします。

アクティビティ A と B が表示され、次にアクティビティ B と C が表示されるタスクウィンドウ。

その結果、同じタスクのアクティビティの Z オーダーは次のようになります。

1 つのスタック内にあるアクティビティ A、B、C。アクティビティは上から C、B、A の順に重ねられています。

アプリは、タスクウィンドウが小さくなると、アクティビティ C が一番上にある 1 つのアクティビティに縮小されます。

アクティビティ C のみを表示する小さいウィンドウ。

分割の設定

コンテナと分割は、分割ルールに基づいて WindowManager ライブラリで作成できます。分割ルールの設定手順は以下のとおりです。

最新の WindowManager ライブラリ依存関係を build.gradle ファイルに追加します。次に例を示します。

implementation 'androidx.window:window:1.1.0-alpha04'

次の処理を行うリソースファイルを作成します。

分割を共有するすべてのアクティビティの分割オプションを設定する
フィルタを使用して分割するアクティビティを定義する
分割に配置しないアクティビティを指定する

例:

<!-- main_split_config.xml -->

<!-- The split configuration for activities. -->
<resources
    xmlns:window="http://schemas.android.com/apk/res-auto">

    <!-- Define a split for the named activity pair. -->
    <SplitPairRule
        window:splitRatio="0.3"
        window:splitMinWidth="600dp"
        window:finishPrimaryWithSecondary="never"
        window:finishSecondaryWithPrimary="always">
        <SplitPairFilter
            window:primaryActivityName=".SplitActivityList"
            window:secondaryActivityName=".SplitActivityDetail"/>
    </SplitPairRule>

    <!-- Automatically launch a placeholder for the list activity. -->
    <SplitPlaceholderRule
        window:placeholderActivityName=".SplitActivityListPlaceholder"
        window:splitRatio="0.3"
        window:splitMinWidth="600dp">
        <ActivityFilter
            window:activityName=".SplitActivityList"/>
    </SplitPlaceholderRule>

    <!-- Define activities that should never enter a split. Note: Takes
         precedence over other split rules. -->
    <ActivityRule
        window:alwaysExpand="true">
        <ActivityFilter window:activityName=".FullscreenActivity"/>
    </ActivityRule>

</resources>

ルールの定義をライブラリに伝えます。

この例では、アプリの他のコンポーネントが読み込まれてアクティビティが起動する前に、Jetpack Startup ライブラリを使用して初期化を行います。この Startup の機能を有効にするには、アプリのビルドファイルにライブラリ依存関係を追加します。

implementation 'androidx.startup:startup-runtime:1.1.1'

アプリマニフェストに次のエントリを追加します。
```


<provider android:name="androidx.startup.InitializationProvider"
    android:authorities="${applicationId}.androidx-startup"
    android:exported="false"
    tools:node="merge">
    
    <meta-data  android:name="androidx.window.sample.embedding.ExampleWindowInitializer"
        android:value="androidx.startup" />
</provider>
```

最後に、Initializer クラスの実装を追加します。

ルールを設定するには、SplitController.initialize() に定義（main_split_config）を含む XML リソースファイルの ID を指定します。

Kotlin

class ExampleWindowInitializer : Initializer<SplitController> {
   override fun create(context: Context): SplitController {
       SplitController.initialize(context, R.xml.main_split_config)
       return SplitController.getInstance(context)
   }

   override fun dependencies(): List<Class<out Initializer<*>>> {
       return emptyList()
   }
}

Java

class ExampleWindowInitializer extends Initializer<SplitController> {
   @Override
   SplitController create(Context context) {
       SplitController.initialize(context, R.xml.main_split_config);
       return SplitController.getInstance(context);
   }

   @Override
   List<Class<? extends Initializer<?>>> dependencies() {
       return emptyList();
   }
}

分割の例

フルウィンドウからの分割

リファクタリングは必要ありません。分割の設定を静的に、またはランタイムに定義し、追加のパラメータなしで Context#startActivity() を呼び出すことができます。

<SplitPairRule>
    <SplitPairFilter
        window:primaryActivityName=".A"
        window:secondaryActivityName=".B"/>
</SplitPairRule>

デフォルトでの分割

アプリのランディングページが、大画面で 2 つのコンテナに分割されるように設計されている場合、両方のアクティビティを同時に作成して表示すると最良のユーザーエクスペリエンスが得られます。ただし、ユーザーがプライマリコンテナでアクティビティを操作する（ナビゲーションメニューからアイテムを選択するなど）まで、分割のセカンダリコンテナでコンテンツを利用できない場合があります。プレースホルダアクティビティは、分割のセカンダリコンテナにコンテンツを表示できるようになるまで、空白を埋めることができます（前述のプレースホルダをご覧ください）。

プレースホルダを伴う分割を作成するには、プレースホルダを作成し、プライマリアクティビティに関連付けます。

<SplitPlaceholderRule
    window:placeholderIntentName=".Placeholder">
    <ActivityFilter
        window:activityName=".Main"/>
</SplitPlaceholderRule>

ディープリンク分割

アプリがインテントを受け取ると、ターゲットアクティビティをアクティビティ分割のセカンダリ部分として表示できます（リストのアイテムに関する情報を詳細画面に表示するリクエストなど）。詳細は、小さいディスプレイではタスクウィンドウ全体に表示され、大きいデバイスではリストの横に表示されます。

**図 13.** ディープリンクの詳細アクティビティは、小画面では単独で表示され、大画面ではリストアクティビティとともに表示される。

起動リクエストはメインアクティビティにルーティングされ、ターゲットの詳細アクティビティは分割で起動する必要があります。SplitController は、利用可能な表示幅に基づいて、適切な表示方法（積み重ねまたは横並び）を自動的に選択します。

Kotlin

override fun onCreate(savedInstanceState Bundle?) {
    …
    splitController.registerRule(SplitPairRule(newFilters))
    startActivity(Intent(this, DetailActivity::class.java))
}

Java

@Override
protected void onCreate(@Nullable Bundle savedInstanceState) {
    …
    splitController.registerRule(new SplitPairRule(newFilters));
    startActivity(new Intent(this, DetailActivity.class));
}

「戻る」ナビゲーションスタックでユーザーが利用できるアクティビティが、ディープリンクのデスティネーションのみの場合があります。その場合も含めて、詳細アクティビティが閉じてメインアクティビティだけが残る、ということがないようにしてください。

リストアクティビティと詳細アクティビティを並べて表示した大きなディスプレイ。
「戻る」ナビゲーションで、詳細アクティビティを閉じてリストアクティビティを画面に残すことはできません。

詳細アクティビティのみの小さいディスプレイ。「戻る」ナビゲーションで、詳細アクティビティを閉じてリストアクティビティを表示することはできません。

代わりに、finishPrimaryWithSecondary 属性を使用することで両方のアクティビティを同時に終了できます。

<SplitPairRule
    window:finishPrimaryWithSecondary="always">
    <SplitPairFilter
        window:primaryActivityName=".List"
        window:secondaryActivityName=".Detail"/>
</SplitPairRule>

分割コンテナ内の複数のアクティビティ

分割コンテナに複数のアクティビティを重ねると、ユーザーは深いコンテンツにアクセスできます。たとえばリストと詳細の分割で、ユーザーがサブ詳細セクションに移動する必要がある場合でも、プライマリアクティビティはそのまま表示し続けます。

**図 14.** タスクウィンドウのセカンダリペインで所定の位置に開かれたアクティビティ。

Kotlin

class DetailActivity {
    …
    fun onOpenSubDetail() {
      startActivity(Intent(this, SubDetailActivity::class.java))
    }
}

Java

public class DetailActivity {
    …
    void onOpenSubDetail() {
        startActivity(new Intent(this, SubDetailActivity.class));
    }
}

サブ詳細アクティビティが、詳細アクティビティを隠すように、上に配置されます。

すると、ユーザーはスタック内をさかのぼって移動することで前の詳細レベルに戻ることができます。

同じセカンダリコンテナ内のアクティビティからアクティビティを起動すると、アクティビティは互いに重ねられます。これがデフォルトの動作です。アクティブな分割の中でプライマリコンテナから起動されたアクティビティも、アクティビティスタックの一番上にあるセカンダリコンテナに配置されます。

新しいタスクのアクティビティ

分割タスクウィンドウ内のアクティビティが新しいタスクのアクティビティを起動すると、新しいタスクは、分割を含むタスクとは別に、ウィンドウ全体に表示されます。履歴画面には 2 つのタスク（分割の中のタスクと新しいタスク）が表示されます。

**図 16.** アクティビティ B から新しいタスクでアクティビティ C を起動。

アクティビティの置き換え

セカンダリコンテナスタック内でアクティビティを置き換えることができます（プライマリアクティビティをトップレベルナビゲーションに使用し、セカンダリアクティビティが選択したデスティネーションである場合など）。トップレベルナビゲーションから選択されるたびに、セカンダリコンテナで新しいアクティビティが起動し、それまでそこにあったアクティビティは削除されます。

**図 17.** プライマリペインのトップレベルナビゲーションアクティビティが、セカンダリペインのデスティネーションアクティビティに置き換わる。

ナビゲーションの選択が変更されたときにアプリがセカンダリコンテナのアクティビティを終了しない場合、分割が閉じられた（デバイスが折りたたまれた）ときに「戻る」ナビゲーションがわかりにくくなる可能性があります。たとえば、プライマリペインにメニューがあり、セカンダリペインに画面 A と B が重ねられている場合、ユーザーがスマートフォンを折りたたむと、B が A の上になり、A がメニューの上になります。ユーザーが B から戻ると、メニューではなく A が表示されます。

このような場合は、画面 A をバックスタックから削除する必要があります。

既存の分割の上に新しいコンテナで横に起動する場合のデフォルト動作では、新しいセカンダリコンテナが上に配置され、古いコンテナがバックスタックに保持されます。clearTop で以前のセカンダリコンテナを消去して新しいアクティビティを通常どおり起動するように、分割を設定できます。

<SplitPairRule
    window:clearTop="true">
    <SplitPairFilter
        window:primaryActivityName=".Menu"
        window:secondaryActivityName=".ScreenA"/>
    <SplitPairFilter
        window:primaryActivityName=".Menu"
        window:secondaryActivityName=".ScreenB"/>
</SplitPairRule>

Kotlin

class MenuActivity {
    …
    fun onMenuItemSelected(selectedMenuItem: Int) {
        startActivity(Intent(this, classForItem(selectedMenuItem)))
    }
}

Java

public class MenuActivity {
    …
    void onMenuItemSelected(int selectedMenuItem) {
        startActivity(new Intent(this, classForItem(selectedMenuItem)));
    }
}

あるいは、同じセカンダリアクティビティを使用し、プライマリ（メニュー）アクティビティから、同じインスタンスに解決されてセカンダリコンテナで状態または UI の更新をトリガーする新しいインテントを送信します。

複数の分割

アプリは、追加のアクティビティを横に起動することで、多層の深いナビゲーションを提供できます。

セカンダリコンテナのアクティビティが新しいアクティビティを横に起動すると、既存の分割の上に新しい分割が作成されます。

バックスタックには以前開かれたアクティビティがすべて含まれているため、ユーザーは C を終了した後に A / B 分割に移動できます。

スタック内にあるアクティビティ A、B、C。アクティビティは上から C、B、A の順に重ねられています。

新しい分割を作成するには、既存のセカンダリコンテナから新しいアクティビティを横に起動します。A / B 分割と B / C 分割の両方の設定を宣言し、アクティビティ C を通常どおり B から起動します。

<SplitPairRule>
    <SplitPairFilter
        window:primaryActivityName=".A"
        window:secondaryActivityName=".B"/>
    <SplitPairFilter
        window:primaryActivityName=".B"
        window:secondaryActivityName=".C"/>
</SplitPairRule>

Kotlin

class B {
    fun onOpenC() {
        startActivity(Intent(this, C::class.java))
    }
}

Java

public class B {
    …
    void onOpenC() {
        startActivity(new Intent(this, C.class));
    }
}

分割状態の変更に対応する

アプリ内の異なるアクティビティに、同じ機能を果たす UI 要素が存在することがあります（アカウント設定を含むウィンドウを開くコントロールなど）。

分割の中に共通の UI 要素を持つ 2 つのアクティビティがある場合、その要素を両方のアクティビティに表示することは冗長であり、混乱を招くおそれがあります。

アクティビティが分割の中にあることを確認するには、分割状態の変更について SplitController でリスナーを登録します。次に、それに応じて UI を調整します。

Kotlin

override fun onCreate(savedInstanceState: Bundle?) {
    splitController
        .addSplitListener(this, mainThreadExecutor, SplitInfoChangeCallback())
}

inner class SplitInfoChangeCallback : Consumer<List<SplitInfo>> {
    override fun accept(splitInfoList: List<SplitInfo>) {
        findViewById<View>(R.id.infoButton).visibility =
            if (!splitInfoList.isEmpty()) View.GONE else View.VISIBLE
    }
}

Java

@Override
protected void onCreate(@Nullable Bundle savedInstanceState) {
    splitController
        .addSplitListener(this, mainThreadExecutor, SplitInfoChangeCallback());
}

class SplitInfoChangeCallback extends Consumer<List<SplitInfo>> {
    public void accept(List<SplitInfo> splitInfoList) {
        findViewById<View>(R.id.infoButton).visibility =
            !splitInfoList.isEmpty()) ? View.GONE : View.VISIBLE;
    }
}

コールバックは、アクティビティが停止している場合を含め、どのようなライフサイクル状態でも発生する可能性があります。リスナーは通常、onStart() で登録し、onStop() で登録を解除します。

フルウィンドウモーダル

ログイン画面、ポリシーの確認画面、エラーメッセージなど、アクティビティの中には、指定されたアクションが行われるまでユーザーがアプリを操作できないようにするものもあります。モーダルアクティビティは、分割に表示されないようにする必要があります。

Expand 設定を使用することで、アクティビティが常にタスクウィンドウ全体に表示されるよう強制できます。

<ActivityRule
    window:alwaysExpand="true">
    <ActivityFilter
        window:activityName=".FullWidthActivity"/>
</ActivityRule>

アクティビティを終了する

ディスプレイの端からスワイプすることで、分割のどちらかの側のアクティビティを終了できます。

デバイスがジェスチャーナビゲーションではなく [戻る] ボタンを使用するように設定されている場合、入力はフォーカスされているアクティビティ（最後にタップまたは起動されたアクティビティ）に送信されます。

分割のアクティビティを 1 つ終了した場合の結果は、分割の設定によって異なります。

デフォルト設定

分割のアクティビティを 1 つ終了すると、残りのアクティビティがウィンドウ全体を占有します。

<SplitPairRule>
    <SplitPairFilter
        window:primaryActivityName=".A"
        window:secondaryActivityName=".B"/>
</SplitPairRule>

アクティビティ A とアクティビティ B を含む分割。A が終了すると B がウィンドウ全体を占有します。

アクティビティ A とアクティビティ B を含む分割。B が終了すると A がウィンドウ全体を占有します。

アクティビティをまとめて終了する

セカンダリアクティビティが終了すると、プライマリアクティビティが自動的に終了します。

<SplitPairRule
    window:finishPrimaryWithSecondary="always">
    <SplitPairFilter
        window:primaryActivityName=".A"
        window:secondaryActivityName=".B"/>
</SplitPairRule>

アクティビティ A とアクティビティ B を含む分割。B が終了すると A も終了し、タスクウィンドウは空になります。

アクティビティ A とアクティビティ B を含む分割。A が終了すると B だけがタスクウィンドウに残ります。

プライマリアクティビティが終了すると、セカンダリアクティビティが自動的に終了します。

<SplitPairRule
    window:finishSecondaryWithPrimary="always">
    <SplitPairFilter
        window:primaryActivityName=".A"
        window:secondaryActivityName=".B"/>
</SplitPairRule>

アクティビティ A とアクティビティ B を含む分割。A が終了すると B も終了し、タスクウィンドウは空になります。

アクティビティ A とアクティビティ B を含む分割。B が終了すると A だけがタスクウィンドウに残ります。

プライマリまたはセカンダリが終了したときに、アクティビティをまとめて終了します。

<SplitPairRule
    window:finishPrimaryWithSecondary="always"
    window:finishSecondaryWithPrimary="always">
    <SplitPairFilter
        window:primaryActivityName=".A"
        window:secondaryActivityName=".B"/>
</SplitPairRule>

アクティビティ A とアクティビティ B を含む分割。A が終了すると B も終了し、タスクウィンドウは空になります。

アクティビティ A とアクティビティ B を含む分割。B が終了すると A も終了し、タスクウィンドウは空になります。

コンテナの複数のアクティビティを終了する

分割コンテナで複数のアクティビティが重なっている場合、その一番下にあるアクティビティが終了しても、上にあるアクティビティが自動的に終了することはありません。

たとえば、2 つのアクティビティがセカンダリコンテナにあり、B の上に C があるとします。

アクティビティ B の上に重ねられたアクティビティ C を含むセカンダリアクティビティスタックが、アクティビティ A を含むプライマリアクティビティスタックの上に重ねられています。

分割の設定はアクティビティ A とアクティビティ B の設定によって定義されます。

<SplitPairRule>
    <SplitPairFilter
        window:primaryActivityName=".A"
        window:secondaryActivityName=".B"/>
</SplitPairRule>

一番上のアクティビティを終了しても分割は保持されます。

プライマリコンテナにアクティビティ A、セカンダリコンテナにアクティビティ B と C を配置し、B の上に C を重ねた分割。C が終了すると、アクティビティ分割に A と B が残ります。

セカンダリコンテナの一番下（ルート）にあるアクティビティを終了しても、その上にあるアクティビティは削除されません。そのため、分割も保持されます。

プライマリコンテナにアクティビティ A、セカンダリコンテナにアクティビティ B と C を配置し、B の上に C を重ねた分割。B が終了すると、アクティビティ分割に A と C が残ります。

プライマリアクティビティとともにセカンダリアクティビティを終了するなど、アクティビティをまとめて終了するための追加のルールも実施されます。

<SplitPairRule
    window:finishSecondaryWithPrimary="always">
    <SplitPairFilter
        window:primaryActivityName=".A"
        window:secondaryActivityName=".B"/>
</SplitPairRule>

プライマリコンテナにアクティビティ A、セカンダリコンテナにアクティビティ B と C を配置し、B の上に C を重ねた分割。A が終了すると、B と C も終了します。

分割がプライマリとセカンダリをまとめて終了するように設定されている場合は次のようになります。

<SplitPairRule
    window:finishPrimaryWithSecondary="always"
    window:finishSecondaryWithPrimary="always">
    <SplitPairFilter
        window:primaryActivityName=".A"
        window:secondaryActivityName=".B"/>
</SplitPairRule>

ランタイムに分割プロパティを変更する

現在アクティブな、表示されている分割のプロパティは変更できません。分割ルールの変更は、追加のアクティビティ起動と新しいコンテナに影響しますが、既存のアクティブな分割には影響しません。

アクティブな分割のプロパティを変更するには、横のアクティビティまたは分割の中のアクティビティを終了し、新しい設定でアクティビティを再び横に起動します。

分割からアクティビティを抽出してフルウィンドウにする

横のアクティビティをフルウィンドウ表示する新しい設定を作成してから、同じインスタンスに解決されるインテントでそのアクティビティを再起動します。

ランタイムに分割のサポートを確認する

アクティビティの埋め込みは Android 12L（API レベル 32）の機能ですが、デバイスによっては、それより前のプラットフォームバージョンでも利用できます。この機能が利用可能かどうかをランタイムに確認するには、SplitController.isSplitSupported() メソッドを使用します。

Kotlin

val splitController = SplitController.Companion.getInstance()
if (splitController.isSplitSupported()) {
    // Device supports split activity features.
}

Java

SplitController splitController = SplitController.Companion.getInstance();
if (splitController.isSplitSupported()) {
  // Device supports split activity features.
}

分割がサポートされていない場合、（アクティビティの埋め込み以外のモデルに従って）アクティビティは一番上に起動されます。

システムのオーバーライドを禁止する

Android デバイスのメーカー（相手先ブランド製品製造企業、OEM）は、デバイスシステムの機能としてアクティビティの埋め込みを実装できます。システムは、アプリのウィンドウ処理動作をオーバーライドして、マルチアクティビティアプリの分割ルールを指定します。システムによるオーバーライドが行われると、マルチアクティビティアプリはシステム定義のアクティビティ埋め込みモードになります。

システムのアクティビティの埋め込みにより、アプリに変更を加えることなく、リスト詳細などのマルチペインレイアウトを使用してアプリの表示を改善できます。ただし、誤ったレイアウトでアプリが表示されたり、バグや、アプリ側で実装するアクティビティ埋め込みとの競合を引き起こしたりすることもあります。

システムのアクティビティの埋め込みを禁止または許可するには、アプリマニフェストファイルでプロパティを設定します。次に例を示します。

<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <application>
        <property
            android:name="android.window.PROPERTY_ACTIVITY_EMBEDDING_ALLOW_SYSTEM_OVERRIDE"
            android:value="true|false" />
    </application>
</manifest>

プロパティ名は Jetpack WindowManager WindowProperties オブジェクトで定義されます。アクティビティの埋め込みをアプリが実装する場合、またはシステムがアクティビティの埋め込みのルールをアプリに適用しないようにする場合は、値を false に設定します。値を true に設定すると、システムはシステム定義のアクティビティの埋め込みをアプリに適用できるようになります。

制約、制限、注意事項

タスク内の他のアクティビティを整理したり、埋め込んだりできるのは、タスクのホストアプリ（タスクのルートアクティビティのオーナーとして識別）に限られます。埋め込みと分割をサポートするアクティビティが、別のアプリに属するタスクで実行される場合、それらのアクティビティでは埋め込みと分割が機能しません。
アクティビティは 1 つのタスク内でのみ整理できます。新しいタスクでアクティビティを起動すると、常に既存の分割の外部で新しく開いたウィンドウに配置されます。
整理して分割に配置できるのは、同じプロセスのアクティビティに限られます。異なるプロセスのアクティビティを把握する方法がないため、SplitInfo コールバックは同じプロセスに属するアクティビティのみをレポートします。
各ペアまたは単一のアクティビティルールは、ルールが登録された後に発生するアクティビティ起動にしか適用されません。現在のところ、既存の分割やその視覚的なプロパティを更新する方法はありません。
分割ペアのフィルタ設定は、アクティビティを起動するときに使用するインテントと完全に一致する必要があります。この照合はアプリプロセスから新しいアクティビティが起動された時点で起こるため、暗黙的インテントを使用する場合、システムプロセスの後半で解決されるコンポーネント名が不明となることがあります。起動時にコンポーネント名が不明な場合は、代わりにワイルドカード（「*/*」）を使用し、インテントのアクションに基づいてフィルタリングを実施できます。
現在のところ、コンテナ間でアクティビティを移動する方法や、分割の作成後にその内外にアクティビティを移動する方法はありません。分割は、ルールが一致する新しいアクティビティが起動したときにのみ、WindowManager ライブラリによって作成され、分割コンテナ内の最後のアクティビティが終了したときに破棄されます。
アクティビティは構成変更に伴って再起動される場合があるため、分割が作成または削除されてアクティビティの境界が変化すると、それまでのインスタンスが完全に破棄され新たなインスタンスが再作成される可能性があります。そのため、アプリデベロッパーは、ライフサイクルコールバックから新しいアクティビティを起動するなどの処理に注意する必要があります。

アクティビティの埋め込み

分割タスク ウィンドウ

「戻る」ナビゲーション

マルチペイン レイアウト

分割比

プレースホルダ

ウィンドウ サイズの変更

セカンダリ ペインの複数のアクティビティ

分割の積み重ね

分割の設定

Kotlin

Java

分割の例

フルウィンドウからの分割

デフォルトでの分割

ディープリンク分割

Kotlin

Java

分割コンテナ内の複数のアクティビティ

Kotlin

Java

新しいタスクのアクティビティ

アクティビティの置き換え

Kotlin

Java

複数の分割

Kotlin

Java

分割状態の変更に対応する

Kotlin

Java

フルウィンドウ モーダル

アクティビティを終了する

デフォルト設定

アクティビティをまとめて終了する

コンテナの複数のアクティビティを終了する

ランタイムに分割プロパティを変更する

分割からアクティビティを抽出してフルウィンドウにする

ランタイムに分割のサポートを確認する

Kotlin

Java

システムのオーバーライドを禁止する

制約、制限、注意事項

参考情報

分割タスクウィンドウ

マルチペインレイアウト

ウィンドウサイズの変更

セカンダリペインの複数のアクティビティ

フルウィンドウモーダル