UISplitViewController 公式ドキュメントの和訳（iOS14 対応）

iOS14 になって Split View の UI が大きく変わり、真剣に理解するために和訳をしてみました。

原文：[UISplitViewController | Apple Developer Documentation](https://developer.apple.com/documentation/uikit/uisplitviewcontroller)

----

# UISplitViewController

階層的なインタフェースのコンテナビューコントローラ。

## 宣言（Declaration）

```swift
class UISplitViewController : UIViewController
```

## 概要（Overview）

Split view controller は階層的なインタフェースのためのビューコントローラで、その子のビューコントローラを管理するコンテナビューコントローラです。この種類のインタフェースにおいては、１つのビューコントローラでの変化が、他のコンテンツに影響を与えます。

Split view インタフェースは、コンテンツをフィルタリングしたり、階層構造のコンテンツをナビゲートするのにもっとも適しています。例えば Notes（メモ）アプリの場合、primary sidebar でフォルダを選択し、その中のノート一覧から１つを選択すると、secondary view に選択されたノートが表示されます。

![primary、supplementary、secondary カラムを持つ３段カラムの split view インタフェース](https://docs-assets.developer.apple.com/published/057b3e2964/rendered2x-1591053027.png)

通常、split view controller は、アプリの window の root view controller とします。Split view controller それ自身は特別な見た目は持ちません。ほとんどの見た目は子ビューコントローラによって決まります。


>navigation スタックに split view controller をプッシュすることはできません。また、split view controller を子として、他のコンテナビューコントローラに入れることができますが、ほとんどの場合おすすめしません。デザインについては、[iOS Human Interface Guidelines](https://developer.apple.com/design/human-interface-guidelines/ios/overview/themes/)をご覧ください。


## Split View スタイル（Split View Styles）

iOS14 以降では、`UISplitViewController` は「カラムスタイルレイアウト」をサポートします。カラムスタイルの split view controller では、`init(style:)` でインスタンスする際に、２カラムもしくは３カラムのインタフェースを指定できます。

- `UISplitViewController.Style.doubleColumn` を指定すると、２カラムのレイアウトを構築できます。このスタイルの split view controller は、primary と secondary の２つの子ビューコントローラを配置し、管理します。
- `UISplitViewController.Style.tripleColumn` を指定することで、３カラムのレイアウトを構築できます。このスタイルの split view controller は、primary、supplementary、secondary の３つの子 view controller を配置し、管理します。

![２カラムと３カラムの split view インタフェース](https://docs-assets.developer.apple.com/published/8f7b414fba/rendered2x-1591053027.png)

iOS14 より前のバージョンでは、`UISplitViewController` は、primary view controller と secondary view controller を持つ split view インタフェーススタイルのみをサポートします。この以前のスタイルは `init(style:)` 以外の方法でインスタンスされた場合に適用されます。この場合、`UISplitViewController.Style.unspecified` を持ち、iOS14 以降に導入されたカラムスタイルの API には応答しません。

## 子ビューコントローラ（Child View Controllers）

カラムスタイルの split view インタフェースにおいては、それぞれのビューコントローラを登録、取得するのに `setViewController(_:for:)` と `viewController(for:)` を使います。Split view controller は全ての子ビューコントローラをナビゲーションコントローラの中にラップします。もしナビゲーションコントローラではない子ビューコントローラを登録した時、split view controller はナビゲーションコントローラを生成します。Split view controller は `viewController(for:)` を通じて元のビューコントローラを返しますが、`children` プロパティは、元のビューコントローラをラップするナビゲーションコントローラを含みます。ビューコントローラを各カラムに指定することで、`show(_:)` や `hide(_:)` を使って表示したり、非表示にすることができます。

以前の split view インタフェースにおいては、Interface Builder を使うか、`viewControllers` プロパティにビューコントローラをセットすることで、子ビューコントローラを設定できます。`primary` もしくは `secondary` ビューコントローラを変更する必要がある場合、`show(_:sender:)` と `showDetailViewController(_:sender:)` を使って行うことが推奨されます。（ビューコントローラのプロパティを直接変更する代わりに）これらのメソッドを使うことで、現在の表示モードやサイズクラスに最適な方法で、指定のビューコントローラを表示します。

## 画面遷移（Interface Transitions）

Split view controller は、そのインタフェース内で起きた変化に応じて、ビューを折り畳んだり広げたりします。例えば、サイズクラスが holizontally regular から horizontally compact に切り替わった時に発生したり、ユーザの操作やプログラムによってカラムを表示／非表示する場合に発生します。Split view controller はその `delegate` オブジェクトとともに、この動作を行います。このデリゲートは `UISplitViewControllerDelegate` プロトコルに適合したオブジェクトです。

カラムスタイルの split view インタフェースにおいて、折り畳まれた状態の時、primary、supplementary、secondary ではない異なるビューコントローラを表示することができます。`setViewController(_:for:)` を使って望みのビューコントローラを `UISplitViewController.Column.compact` カラムに設定してください。もし折り畳む遷移や、広げる遷移をよりカスタマイズしたい場合は、[Column-Style Split Views](https://developer.apple.com/documentation/uikit/uisplitviewcontrollerdelegate#3596702) を参照してください。

以前の split view インタフェースの画面遷移についてのは、[Classic Split Views](https://developer.apple.com/documentation/uikit/uisplitviewcontrollerdelegate#3596701) を参照してください。

## 表示モード（Display Mode）

Split view controller の現在の表示モードは、子ビューコントローラの見た目の組み合わせによって表されます。それにより、いくつの子ビューコントローラが表示されるか、どのように相互に連携して配置されるかが決まります。例えば、子ビューコントローラを横並びで表示させたり、１つだけ表示せたり、部分的に覆い隠す設定が可能です。

表示モードは直接設定できません。代わりに、`preferredDisplayMode` プロパティを使って希望の表示モードを指定します。Split view controller は指定された表示モードを尊重しますが、スペースの制約によって、実際の表示ははそのようにならないかもしれません。例えば、horizontally compact environment（水平方向に表示幅が狭い状況）においては、子ビューコントローラを並べて表示することはできません。設定可能な条件は [`UISplitViewController.DisplayMode`](https://developer.apple.com/documentation/uikit/uisplitviewcontroller/displaymode) を参照してください。

![分割の挙動とカラムスタイルに基づいた、表示モード間の遷移の可能性](https://docs-assets.developer.apple.com/published/a557d26de8/rendered2x-1591388381.png)

## ジェスチャーとボタンのサポート（Gesture and Button Support）

ユーザの操作によって、現在の表示モードを切り替える方法がいくつかあります。

Split view controller は、スワイプによって表示モードを変更できるよう、ビルトインのジェスチャー処理が組み込まれています。`presentsWithGesture` プロパティを `false` にすることで、このジェスチャーを制限することができます。例えば、primary ビューコントロラーを常に表示させたい場合には、このプロパティを `false` にしたいかもしれません。

`presentsWithGesture` が `true` の場合、split view controller は、表示モードを切り替えるための特別な bar button item を表示します。split view controller はこの挙動や見た目、位置を管理します。`UISplitViewController.SplitBehavior.tile` の場合は sidebar toggle アイコンが、`UISplitViewController.SplitBehavior.overlay` と `UISplitViewController.SplitBehavior.displace` の場合は back-chevron アイコンが表示されます。このボタンをタップすると、現在の表示モードと分割の挙動に基づいて、新しい表示モードに遷移します。

３カラムの split view インタフェース（`UISplitViewController.Style.tripleColumn`）に対して、表示モードに影響を与える他のプロパティは `showsSecondaryOnlyButton` です。このプロパティが `true` の時、split view controller は、表示モードを `UISplitViewController.DisplayMode.secondaryOnly` とトグルするために、他の bar button item を表示させます。split view controller はこのアイテムの挙動や見た目、位置を管理します。これは、double-arrow アイコンとして表示され、ユーザーがタップした時、表示モードを `UISplitViewController.DisplayMode.secondaryOnly` とトグルします。

![３カラム split view controller の Tile、Overlay、Displace の挙動](https://docs-assets.developer.apple.com/published/8ff94c73be/rendered2x-1591127836.png)

## 分割の挙動（Split Behavior）

split view controller は、secondary ビューコントローラが、どのように他のビューコントローラと連携しながら表示されるかを制御します。secondary ビューコントローラが、常に他のビューコントローラと横並びに表示されるようにしたり、部分的に覆いかぶされるようにしたり、他のビューコントローラのためにスペースを空けるために画面外に表示するようにしたり、挙動を設定することができます。

分割の挙動を直接設定することはできません。代わりに、`preferredSplitBehavior` プロパティを使って希望の表示モードを指定します。このプロパティの変更は、次のレイアウト遷移後に有効になります。split view controller は実際の分割の挙動を `splitBehavior` プロパティに反映させます。`splitBehavior` プロパティの値は、どの表示モードを有効にするかに影響を与えます。設定可能な条件は [`UISplitViewController.SplitBehavior`](https://developer.apple.com/documentation/uikit/uisplitviewcontroller/splitbehavior) を参照してください。

## カラム幅のカスタマイズ（Column Width Customization）

`preferredPrimaryColumnWidthFraction` と `preferredSupplementaryColumnWidthFraction` を調整することで、primary カラムと supplementary カラムに、独自の幅を指定することができます。もし指定しない場合はデフォルト値として `automaticDimension` が設定され、利用可能なスペースに基づいて、システムが適切な挙動を決定します。

## メッセージの配送（Message Forwarding）

split view controller はアプリのウィンドウと子ビューコントローラの間を仲裁します。そのため、子ビューコントローラへの全てのメッセージは必ず split view controller を経由し、適切に配送されます。例えば、ビューの表示と非表示のメッセージは、対応する子ビューコントローラが実際にスクリーンに表示される時だけ送信されます。

## 状態の保存（State Preservation）

もし、split view controller の `restorationIdentifier` プロパティに値をセットした場合、有効な restoration identifier を持つ子ビューコントローラを保持します。次の起動サイクルで、split view controller は、保持した子ビューコントローラをそれらの前の状態にリストアします。split view controller のそれぞれの子ビューコントローラは、同じ restoration identifier を利用するかもしれません。split view controller は、それぞれの子ビューコントローラの restoration path がユニークになることを保証するために、自動的に追加の情報を保存します。

# 訳者あとがき

実際に動かしてみないとよくわからん！