Skip to content

2-Reference-ja.md

Latest commit

 

History

History
159 lines (124 loc) · 11.3 KB

2-Reference-ja.md

File metadata and controls

159 lines (124 loc) · 11.3 KB

[Home] > リファレンス

リファレンス

  1. 遷移イベント種別
    1. OnInitialize
    2. OnLoaded
    3. OnUnloaded
    4. OnClosed
  2. 画面遷移時パラメーター仕様
  3. Applicationライフサイクルイベント仕様
    1. OnSleep
    2. OnResume

遷移イベント種別

KAMISHIBAIでは、画面遷移時に複数のイベント通知に対応しています。
イベントの通知は対応するインターフェース（IPageInitializeAwareなど）を実装したPageまたはViewModelに対して行います。
ViewModelだけではなく、Pageに対しても通知可能です。

イベントの通知は、親Pageから子Pageへ再帰的に実行されます。
ただし、具体的な通知対象や通知順はイベント種別や、Pageの種別（NavigationPageかTabbedPageか...）によって異なります。

対応するイベント種別は、つぎの通りです。

なおイベントの通知を受け取るためには、個別の対応インターフェースのほかに、全てのイベントを受け取るつぎのインターフェースも存在します。

  • IPageLifecycleAware
  • IPageLifecycleAware<in TParam>

OnInitialize

項目 説明
概要 画面遷移時に新しく作成されたPageおよびViewModelにたいして一度だけ通知される。
初期化処理の実装に用いることを想定している。
遷移要求時に画面遷移パラメーターが指定されていた場合、OnInitializeイベントにてパラメーターを受け取ることが可能。パラメーターを受け取ることが可能なのはOnInitializeイベントのみ。
画面遷移時において、遷移処理の実行前（例えばINavigation#PusyAsync()メソッドの呼び出し前）に通知される。
戻る処理で戻ってきた場合などは通知されない。
対応インターフェース IPageInitializeAware、IPageInitializeAware<in TParam>
基本通知順序 画面遷移処理の実施前（PushAsyncなどの呼び出し前）に通知される。
親から子へトップダウンで通知する。
またPageへ先に通知した後に、ViewModelへ通知する。
MasterDetailPage MasterDetailPage、MasterPage、DetailPageの順で通知する。
NavigationPage NavigationPage、NavigationStackの全ページの昇順で通知する。
DeepLinkを行っていない場合は、実質子ページは一つであるため、NavigationPageへの通知の後に、Currentへ通知されることになる。
TabbedPage TabbedPage、全タブの昇順で通知される。
CarouselPage CarouselPage、全子Pageの昇順で通知される。

OnLoaded

項目 説明
概要 画面遷移後の画面の表示後に通知される。
（PushAsyncなどで）前方へ画面遷移した場合だけでなく、何らかの戻る処理で戻ってきたタイミングでも通知される。
OnUnloadで、画面の非活性化処理を想定しており、OnLoadedでは逆に活性化処理を想定している。
物理バックボタンやスワイプで戻ってくることも想定しているため、画面遷移パラメーターには対応しない。
対応インターフェース IPageLoadedAware
基本通知順序 画面遷移処理の完了後、OnUnloadの前に通知される。
親から子へトップダウンで通知する。
またPageへ先に通知した後に、ViewModelへ通知する。
MasterDetailPage MasterDetailPage、MasterPage、DetailPageの順で通知する。
NavigationPage NavigationPage、Currentの順で通知される。
NavigationStackに多数のページがあった場合でも、Currentにのみ通知する。
TabbedPage TabbedPage、Currentタブの順で通知される。
タブが複数あった場合、非表示のタブには通知されない。
タブが切り替えられた場合、切り替え後のタブにたいしても通知される。
CarouselPage CarouselPage、Currentページの順で通知される。
ページが複数あった場合、非表示のページには通知されない。
ページが切り替えられた場合、切り替え後のページにも通知される。

OnUnloaded

項目 説明
概要 （PushAsyncなどで）前方へ画面遷移した際に、遷移元の画面に通知される。
画面の非活性化処理の実装を想定している。
戻ってくる可能性のあるPageにたいして通知される。
対応インターフェース IPageUnloadedAware
基本通知順序 画面遷移処理の完了後、OnLoadedの後に通知される。
子から親へボトムアップで通知する。
またViewModelへ通知した後、Pageへ先に通知される。
MasterDetailPage DetailPage、MasterPage、MasterDetailPageの順で通知する。
NavigationPage Currentページ、NavigationPageの順で通知される。
NavigationStackに多数のページがあった場合でも、Currentにのみ通知する。
TabbedPage Currentタブ、TabbedPageの順で通知される。
タブが複数あった場合、非表示のタブには通知されない。
タブが切り替えられた場合、切り替え前に表示していたタブのページにたいしても通知される。
CarouselPage Currentページ、CarouselPageの順で通知される。
ページが複数あった場合、非表示のページには通知されない。
ページが切り替えられた場合、切り替え前に表示していたページにも通知される。

OnClosed

項目 説明
概要 Pageが破棄されるタイミングで通知される。
リソースの解放や、イベントの購読解除などを想定している。
戻る処理が発生した場合の元画面にたいして通知される。
対応インターフェース IPageClosedAware
基本通知順序 戻る処理の完了後、OnLoadedの後に通知される。
子から親へボトムアップで通知する。
またViewModelへ通知した後、Pageへ先に通知される。
MasterDetailPage DetailPage、MasterPage、MasterDetailPageの順で通知する。
NavigationPage NavigationStackの全ページの降順、NavigationPageの順で通知される。
NavigationPageそのものがPopされたり、MainPageが変更された場合が該当する。
TabbedPage 全タブの降順、TabbedPageの順で通知される。
CarouselPage 全子ページの降順、CarouselPageの順で通知される。

画面遷移時パラメーター仕様

つぎの条件を満たした場合、型安全性の保障されたパラメーターを遷移時に渡すことが可能です。

  • INavigationRequest<in TParam>を利用した遷移通知
  • PageかViewModelが、IPageInitializeAware<in TParam>もしくはIPageLifecycleAware<in TParam>を実装している

例えばstring型のパラメーターを渡す場合、ViewModelではつぎのように実装します。

public INavigationRequest<string> RequestNavigation { get; } = new NavigationRequest<string>();

public Task Navigation()
{
    return RequestNavigation.RaiseAsync("param");
}

そしてViewModel側ではつぎのように受け取ります。

public FooPageViewModel : IPageInitializeAware<string>
{
    public void OnInitialize(string parameter)
    {
        ...
    }
}

型パラメーターと実際に受け渡すパラメーターは、完全に一致する必要はありませんが、受け渡すパラメーターが受け取る側の型に代入可能である必要があります。
また、遷移要求時にパラメーターを指定した場合、型パラメーターで修飾されていないIPageInitializeAwareを実装しても、通知を受け取ることができませんので注意が必要です。

Applicationライフサイクルイベント仕様

KAMISHIBAIは画面遷移フレームワークであり、本来はアプリケーションのライフサイクルイベントを扱うのは適当ではないかもしれません。
しかし、ApplicationのOnSleepやOnResumeを通知する仕組みは、KAMISHIBAIの画面遷移イベントの通知と非常に似通ったものになるでしょう。
その為、KAMISHIBAIではApplicationのライフサイクルイベントに関しても、通知できる仕組みを用意しています。

通知を行う場合、App.csクラスのOnSleepとOnResumeで次のように実装してください。

protected override void OnSleep()
{
    LifecycleNoticeService.OnSleep(this);
}

protected override void OnResume()
{
    LifecycleNoticeService.OnResume(this);
}

OnSleep

項目 説明
概要 アプリケーションが背面に移動した場合などに通知される。
通知タイミングはXamarin.Forms.ApplicationのOnSleepの仕様に準ずる
対応インターフェース IApplicationLifecycleAware
基本通知順序 全ての画面へ通知する。
ModalStack上のページすべてに降順で通知した後、MainPageへ通知する。
ModalStack上のページがネストした構造を持っていた場合、子から親へボトムアップで通知する。
またViewModelへ通知した後、Pageへ先に通知される。
MasterDetailPage DetailPage、MasterPage、MasterDetailPageの順で通知する。
NavigationPage NavigationStackの全ページの降順、NavigationPageの順で通知される。
NavigationPageそのものがPopされたり、MainPageが変更された場合が該当する。
TabbedPage 全タブの降順、TabbedPageの順で通知される。
CarouselPage 全子ページの降順、CarouselPageの順で通知される。

OnResume

項目 説明
概要 アプリケーションが背面に移動した場合などに通知される。
通知タイミングはXamarin.Forms.ApplicationのOnResumeの仕様に準ずる
対応インターフェース IApplicationLifecycleAware
基本通知順序 全ての画面へ通知する。
MainPageへ通知した後、ModalStack上のすべてのページへ昇順で通知する。
ModalStack上のページがネストした構造を持っていた場合、親から子へトップダウンで通知する。
またPageへ先に通知した後に、ViewModelへ通知する。
MasterDetailPage MasterDetailPage、MasterPage、DetailPageの順で通知する。
NavigationPage NavigationPage、NavigationStackの全ページの昇順で通知する。
DeepLinkを行っていない場合は、実質子ページは一つであるため、NavigationPageへの通知の後に、Currentへ通知されることになる。
TabbedPage TabbedPage、全タブの昇順で通知される。
CarouselPage CarouselPage、全子Pageの昇順で通知される。