開発者ブログ
リファレンス（仕様詳細） » 画面遷移制御・履歴管理(シーン機能)仕様 [ver.1.2]

画面遷移制御・履歴管理(シーン機能)仕様 [ver.1.2]

Last modified by tom on 2016/01/21, 13:29

いわゆる「SPA」(シングルページアプリケーション)の開発をサポートする「シーン機能」の仕様を説明します。

シーンコンテナ

シーンコンテナは、シーン間の遷移を制御する単位です。
ひとまとまりのコンテンツの単位である「シーン」を内部に表示します。

メインシーンコンテナについて

シーンコンテナのうち、メインシーンコンテナとして指定されたものは、シーン遷移時にブラウザの履歴（ヒストリ）と連動します。
メインシーンコンテナは、ページ上に一つだけ作成でき、複数作成できません。

シーンの表示に必要な情報をURLに保持しているため、ブラウザの戻る、進むでも画面を遷移させての表示が可能です。
※この際、メインシーンコンテナ要素以外の部分はそのままとなります。
※現VerではパラメーターのURLでの保持は未対応です。

リロードや直接リンクへの対応については、HTMLベースの遷移の場合、遷移先のHTMLが同様にシーンの設定・実装を行っている必要があります。
(現状、HTMLベースの遷移のみ)

シーンコンテナの生成

以下の二つの方法があります。

  • HTMLの記述に基づいた自動生成
  • スクリプトによる生成

HTMLの記述に基づいた自動生成

ドキュメントロード前にh5.settings.scene.autoInitにtrueを設定すると、以下の条件に基づき、フレームワークによりシーンコンテナが自動生成されます。

h5.settings.scene.autoInitのデフォルト値はfalseです。

  • メインシーンコンテナ
    以下の条件で、上が優先。ページ上で一つだけ作成できます。
    • data-h5-main-scene-container属性のある要素
    • mainタグ要素 ※ドキュメントロード前にh5.settings.scene.autoCreateMainContainerにtrueが設定されている場合
    • bodyタグ要素 ※ドキュメントロード前にh5.settings.scene.autoCreateMainContainerにtrueが設定されている場合
  • 通常のシーンコンテナ
    • data-h5-scene-container属性のある要素

HTMLベースで遷移するメインシーンコンテナについては、こちらで生成するようにしてください。
※後述の「メインシーンコンテナの遷移について」>「メインシーンコンテナ生成時の注意点」を参照してください。

スクリプトによる生成

h5.scene.createSceneContainer(element, isMain)を呼び出します。

  • 第1引数 … シーンコンテナにするDOM要素（jQueryオブジェクトも可）です。nullの場合、新たにdiv要素を生成してその要素をシーンコンテナとします。
  • 第2引数 … メインシーンコンテナとして扱うか否か。trueを設定するとメインシーンコンテナとして扱います。
  • 戻り値 … SceneContainerのインスタンスです。

この場合、配下にシーンコンテナ・コントローラーが生成されていないことが前提となります。

HTMLベースで遷移するメインシーンコンテナについては、こちらで生成しないようにしてください。
※後述の「メインシーンコンテナの遷移について」>「メインシーンコンテナ生成時の注意点」を参照してください。

シーンコンテナの取得

シーンコンテナの取得方法には以下があります。

  • createSceneContainerメソッドの戻り値で取得
  • h5.scene.getMainSceneContainer()メインシーンコンテナを取得
  • h5.scene.getSceneContainerByName()シーンコンテナ名を指定してシーンコンテナを取得
  • h5.scene.getSceneContainers()引数に要素またはセレクタを指定してシーンコンテナを配列で取得
  • コントローラーのscene.getParentSceneContainer()メソッドで所属のシーンコンテナを取得

createSceneContainerメソッドの戻り値で取得

前述の「シーンコンテナの生成」>「スクリプトによる生成」を参照してください。

h5.scene.getMainSceneContainer()関数でメインシーンコンテナを取得

メインシーンコンテナはh5.scene.getMainSceneContainer()関数で取得できます。引数はありません。

h5.scene.getSceneContainerByName()関数でメインシーンコンテナを取得

第1引数にシーンコンテナ名を文字列で指定し、該当するシーンコンテナを取得します。

シーンコンテナ名は、data-h5-scene-container属性、またはdata-h5-main-scene-container属性の値が対象です。

<html>
<head><!--省略--></head>
<body>
 <h1>TO</h1>
 <div data-h5-scene-container="sub">
   <h2>SUB</h2>
 </div>
</body>
</html>
// data-h5-scene-container="sub" の要素のシーンコンテナを取得
var container = h5.scene.getSceneContainerByName('sub');

h5.scene.getSceneContainers()関数でメインシーンコンテナを取得

第1引数に対象のDOM要素またはjQueryまたはセレクタ、第2引数にオプションオブジェクトを指定します。

第1引数に指定された要素を対象要素とし、対象要素にバインドされているシーンコンテナを取得します。省略した場合はbody要素が対象です。

第2引数のオプションオブジェクトは、以下のプロパティを取ります。

プロパティ名型デフォルト説明
deepbooleantrue子孫要素にバインドされているコントローラも含めるかどうか(デフォルトは含める)

第1引数に指定された要素の子要素も探索の対象に含めます。

戻り値はシーンコンテナの配列です。該当するシーンコンテナが無い場合も空配列を返します。

コントローラーのgetParentSceneContainer()メソッドで所属のシーンコンテナを取得

コントローラーから、自身の所属するシーンコンテナを取得する場合は、scene.getParentSceneContainer()メソッドで取得できます。

シーン

シーンは、ひとまとまりのコンテンツを表す単位です。
シーンはいずれかのシーンコンテナの直下に含まれて表示されます。

シーンの生成

1つのシーンのルートとなるタグにはdata-h5-scene、またはdata-h5-default-scene属性を記述します。
シーン要素はシーンコンテナ要素の直下に配置します。それ以外には配置できません。(配置した場合、処理の対象外となります)
data-h5-default-scene属性は、最初に表示するシーンに記述します。シーンコンテナ内で一つだけ記述できます。

シーンコンテナの生成時、直下先頭要素にdata-h5-scene属性、data-h5-default-scene属性のどちらも存在しない場合、フレームワークにより、自動的にシーンコンテナ直下にシーン要素(data-h5-default-scene属性を持つ)が追加され、配下の要素すべてが包含されます。
この際、シーンコンテナに後述のdata-h5-controller属性があった場合、その指定は追加されたシーン要素に移動されます。(ただし、シーン要素にdata-h5-controller属性がある場合は移動しません。)

※シーンコンテナ内に複数シーン要素が同時に存在するケースは現在未対応です。

コントローラーベースで遷移する場合、シーン要素は自動生成され、開発者が指定することはできません。

対応するコントローラーについて(シーンコントローラー)

シーン要素にはコントローラーがバインドされることが前提となります。シーンコンテナは、現在表示しているシーンのコントローラーを保持しています。(一つのみ)
これを「シーンコントローラー」と呼びます。
シーンコンテナ生成時、シーンコントローラーが指定されていない場合は、ダミーのコントローラーをバインドしています。(開発者が気にする必要はありません)
シーンコントローラーは、後述の「シーンコンテナ内の遷移(シーンの遷移)」で、遷移元からのパラメーターを受け取ることができます。

シーンコンテナ内の遷移(シーンの遷移)

シーンコンテナ内の表示を遷移させることができます。
シーンを遷移させる方法には以下があります。

  • シーンコンテナのnavigateメソッドの実行
  • シーンコンテナ所属コントローラーからのnavigateメソッドの実行
  • シーンコンテナ所属要素からのnavigateイベントの発行

シーンコンテナのnavigateメソッドの実行

シーンコンテナのnavigateメソッドを使用します。
引数は以下の通りです。

第一引数 … 指定必須。遷移先の指定をしてします。遷移先のみであれば文字列で指定します。その他オプションが必要な場合はオブジェクトで指定します。

  • 文字列の場合
    • HTMLページのURL
      HTMLをAjaxでロード後、以下の条件で表示部分を抽出します。
      • ※[ver1.2.1] 表示対象コンテナの指定があればその部分を抽出します。(後述 第二引数のcontainerプロパティで指定)
      • メインシーンコンテナと同じ条件で表示部分を抽出します。
      • 上記条件に合致しない場合はそのまま使用します。
    • コントローラーの__name属性
      文字列の終端が'Controller'である場合にコントローラーを表示するものとみなします。
      この値でh5.res.requireによりコントローラーのソースファイルが読み込めることが前提となります。( リソース管理機能参照)
      空のDIV要素を生成し、これにコントローラーをバインド後、シーンコンテナ内に表示します。このため、画面描画はコントローラーで行う必要があります。
  • オブジェクトの場合
    以下のプロパティを持つオブジェクトです。
    • to … 指定必須。上述の「文字列の場合」と同様になります。
    • title … 移動した際のシーンコンテナのタイトル(後述)を設定します。
    • args … 最初に表示されるシーンに対応するコントローラー生成時の第三引数を設定します。コントローラー側で__initメソッド等の仮引数に設定されます。
    • navigationType … メインシーンコンテナのみで有効。遷移時のパターンを指定します。以下の値が設定できます。
      • 'normal' … URLに開発者指定のパラメーターを入れます(デフォルト)。ブラウザバック等でパラメーター含めて再表示可能です。h5.scene.navigationType.NORMALと同値なのでこれを指定してもよいです。
      • 'once' … URLに開発者指定のパラメーターを入れません。フレームワーク用パラメーターのみとなります。ブラウザバック等で再表示はできなくなります(再表示不可のメッセージ画面(後述)を表示)。h5.scene.navigationType.ONCEと同値なのでこれを指定してもよいです。
      • 'silent' … URLは変化させずに遷移します。h5.scene.navigationType.SILTENTと同値なのでこれを指定してもよいです。
    • replace … URLを置換しつつ遷移するか否か。置換して遷移する場合はtrueを設定します。(デフォルトfalse)
      trueで遷移した場合、元の画面のURLは履歴から削除されるため、ブラウザバックでは戻れなくなります。
    • method … toの設定値がHTMLページのURLである場合に有効。AjaxでのHTMLデータ取得時のHTTPメソッドを指定します。
      • 'get' … GETメソッドで取得します(デフォルト)。h5.scene.method.GETと同値なのでこれを指定してもよいです。
      • 'post' … POSTメソッドで取得します。h5.scene.method.POSTと同値なのでこれを指定してもよいです。
        ブラウザバック等で再表示はできなくなります(再表示不可のメッセージ画面(後述)を表示)。
    • serverArgs … toの設定値がHTMLページのURLである場合に有効。AjaxでのHTMLデータ取得時のパラメーターを指定します。jQuery.ajaxの引数のdataプロパティに相当します。ただし、直下メンバーの各値として配列以外のオブジェクトは設定できません。値の配列については、その要素にオブジェクトは設定できません。

この値は、h5.u.obj.serializeでシリアライズされた後、h5.u.obj.deserializeでデシリアライズされて使用されます。このため、シリアライズ可能である必要があります。(シリアライズの条件についてはこちらを参照してください)
また、前のシーンと次のシーンで、使用するオブジェクトは、完全に別のものとなります。(一方への操作は、他方に影響しない)

"to.html"に遷移させる例

  h5.scene.getMainContainer().navigate({
    to : 'to.html',
    args : {
      test : 'TEST'
    }
  });
<!--to.html-->
<html>
<head><!--省略--></head>
<body>
 <h1>TO</h1>
 <div data-h5-scene-container="sub" data-h5-controller="SubController"><!-- 表示対象はこの要素 -->
 </div>
</body>
</html>
/*SubController.js*/
(function(){
 'use strict';
 var SubToController = {
    __name : 'SubToController',
    __init : function(context){
     var args = context.args || {};
      console.debug(args.test); //->'TEST'
    },
  };
  h5.core.expose(SubToController);
})();

シーンコンテナ所属要素からのsceneChangeRequestイベントの発行

シーンコンテナに所属する要素から、自身を別のシーンに遷移させたい場合は、sceneChangeRequestイベントを発行します。

  • 第1引数 … 'sceneChangeRequest'
  • 第2引数 … 前述navigateメソッドの引数がオブジェクトの場合と同様です。
      $elm.trigger('sceneChangeRequest', {
        to : 'to.html'
        args : {
          test : 'TEST'
        }
      });

シーンコンテナ要素にてイベントのバブリングが停止されるので、上方直近のシーンコンテナ要素以外には影響ありません。

シーンコンテナ所属コントローラーからのscene.navigateメソッドの実行

シーンコンテナに所属するコントローラーから、自身を別のシーンに遷移させたい場合は、navigateメソッドを実行します。
内部処理で前述sceneChangeRequestイベントを発行します。

  • 第1引数 … 前述navigateメソッドの引数がオブジェクトの場合と同様です。
     // コントローラーメソッドでの処理
      // コントローラはsceneモジュールを持ちます
      // sceneモジュールのnavigate()の実行
      this.scene.navigate({
        to : 'to.html'
        args : {
          test : 'TEST'
        }
      });

シーンコンテナ要素にてイベントのバブリングが停止されるので、上方直近のシーンコンテナ要素以外には影響ありません。

メインシーンコンテナの遷移について

メインシーンコンテナ生成時の注意点

メインシーンコンテナの遷移先として、HTMLのURLを指定する場合、メインシーンコンテナの生成は前述の「HTMLの記述に基づいた自動生成」で行うこととし、「スクリプトによる生成」は行わないようにしてください。

内部処理としては、遷移先のHTMLをAjaxで取得、そのうちのメインシーンコンテナ該当部分をDATA属性等により判別していますが、「スクリプトによる生成」だとHTML上にDATA属性がないため、メインシーンコンテナ該当部分を判別することができず、正しく表示できない場合があります。

メインシーンコンテナの場合、通常のシーン遷移だけでなく、ブラウザの戻る・進む、各HTMLでのリロード、ブックマーク等での直接アクセスについても考慮する必要があります。
HTMLベースでの遷移時、メインシーンコンテナ生成を「スクリプトによる生成」で行うと、この点で不適合になる可能性が非常に高くなります。

また、「HTMLの記述に基づいた自動生成」の場合でも、サーバーから取得したHTMLに所定のDATA属性がなく、クライアントサイドで付加している場合は、同様に正しく表示できない場合があります。
サーバーから取得したHTMLに所定のDATA属性が存在するようにしてください。

次のシーンコントローラーに渡されるパラメータについて

メインシーンコンテナでの遷移時、上述のnavigateメソッドのパラメーターは、h5.u.obj.serialize関数を使用してシリアライズされ、URLのクエリパラメータ、またはハッシュに付加されます。
遷移時はこれがh5.u.obj.deserialize関数を使用してデシリアライズされ、シーンに対応するコントローラーに渡されます。

シリアライズ・デシリアライズの仕様

シリアライズの仕様は以下の通りです。

  • ドキュメントロード前に設定された以下の設定を読み込む
    • h5.settings.scene.clientFWQueryStringPrefix … シーン遷移パラメーター識別用プレフィクス(FW用) (デフォルト値"_h5_")
    • h5.settings.scene.clientQueryStringPrefix … シーン遷移パラメーター識別用プレフィクス (デフォルト値""(空文字))
    • ※ver1.2.0ではclientQueryStringPrefixはデフォルト値(空文字)では動作しません(bug)
    • 以下、clientQueryStringPrefixに"_cl_"を設定した場合について、説明します。
  • navigateメソッドのパラメーターの直下のメンバーのうち、args以外のもの
    • そのメンバー名にプレフィクス「_h5_」を付加してキー文字列とする。
    • 値をh5.u.obj.serializeによりシリアライズし、シリアライズバージョン識別用の先頭「2|」を削除して値文字列とする。
    • キー文字列、値文字列をそれぞれencodeURIComponentでエンコードし、「=」で結合する。
  • navigateメソッドのパラメーターの直下のargs
    • args直下のメンバーについて、そのメンバー名にプレフィクス「_cl_」を付加してキー文字列とする。
    • 値をh5.u.obj.serializeによりシリアライズし、シリアライズバージョン識別用の先頭「2|」を削除して値文字列とする。
    • キー文字列、値文字列をそれぞれencodeURIComponentでエンコードし、「=」で結合する。

デシリアライズの仕様は以下の通りです。

  • 文字列を「&」で分割する。
  • 分割した文字列の「=」の前側をキー文字列とし、後ろ側を値文字列とする。それぞれ、decodeURIComponentでデコードする。
  • キー文字列がプレフィクス「_h5_」「_cl_」のものを対象とする。キー文字列からプレフィクスを除いたのもをメンバー名とする。
  • 各値文字列は、先頭にシリアライズバージョン識別用に「2|」を付加し、h5.u.obj.deserializeによりデシリアライズする。
  • プレフィクス「_h5_」の場合、結果オブジェクト直下に上記メンバー名で値をセットする。
  • プレフィクス「_cl_」の場合、結果オブジェクト下のargsプロパティのオブジェクトに上記メンバー名で値をセットする。

シーン遷移パラメーター識別用プレフィクスの変更

上述のプレフィクスについては、変更することができます。

それぞれ、以下の変数にドキュメントロード前に設定してください。

  • h5.settings.scene.clientFWQueryStringPrefix … シーン遷移パラメーター識別用プレフィクス(FW用)。デフォルト「"_h5_"」
  • h5.settings.scene.clientQueryStringPrefix … シーン遷移パラメーター識別用プレフィクス。デフォルト「""(空文字)」

遷移時のURL変更方式の切り替え

デフォルトではHTML5 History APIを使用してURLを変更します。

h5.settings.scene.urlHistoryModeに以下の値を指定することで、動作を変更することができます。

  • 'hash' … シーン遷移パラメーターをハッシュに格納する。h5.scene.urlHistoryMode.HASHも同値。
  • 'none' … URLを変更しない。h5.scene.urlHistoryMode.NONEも同値。
  • 'fullreload' … Ajaxを使用せず、ページ全体を再読み込みする(通常の遷移)。h5.scene.urlHistoryMode.FULLRELOADも同値。
  • 'history'(デフォルト) … HTML5 History APIを使用してURLを変更する。History APIが使用できない場合はハッシュを使用する。h5.scene.urlHistoryMode.HISTORYも同値。
  • 'historyOrHash' … 'history'と同義。h5.scene.urlHistoryMode.HISTORY_OR_HASHも同値。
  • 'historyOrError' … HTML5 History APIを使用してURLを変更する。History APIが使用できない場合はエラーとする。h5.scene.urlHistoryMode.HISTORY_OR_ERRORも同値。
  • 'historyOrNone' … HTML5 History APIを使用してURLを変更する。History APIが使用できない場合はURLを変更せずに遷移する。h5.scene.urlHistoryMode.HISTORY_OR_NONEも同値。
  • 'historyOrFullreload' … HTML5 History APIを使用してURLを変更する。History APIが使用できない場合はAjaxを使用せずに遷移する(通常遷移)。h5.scene.urlHistoryMode.HISTORY_OR_FULLRELOADも同値。

サイズ制限について

メインシーンコンテナのシーン遷移時、遷移先のURL長(URL全体)が1800を超過した場合、dev版ではエラーとし、min版では警告ログを出力します。
このサイズは、以下の変数をドキュメントロード前に設定することで変更できます。

  • h5.settings.scene.urlMaxLength … シーン遷移先URL最大長。デフォルト1800。

遷移時パラメーターをハッシュに格納する場合の動作

シーン間パラメーターにURLのハッシュ使用する場合は、他のハッシュを使用した機能(ページ内移動等)は使用できません。
また、遷移先としてHTMLのURLが指定された場合、パス自体は変更されず、ハッシュ以下にURLを保持する形式になります。

/*ハッシュ使用でfrom.htmlからto.htmlへ、パラメータ「test=TEST」で遷移した場合のURLの例*/
http://sample/from.html#/to.html?_cl_test=sTEST

/*(参考)ハッシュ使用でない場合*/
http://sample/to.html?_cl_test=sTEST

ハッシュ直下には、ドメインルート以下のパスがすべて指定されることになります。

再表示不可のメッセージ画面について

上述のシーン遷移時、navigationType:'once' または method:'post' を指定した場合、遷移先画面から更に遷移後、ブラウザ履歴等で戻った場合、再表示不可のメッセージ画面を表示します。
フレームワーク内部で持つコントローラーにより、以下のようなデフォルトのメッセージを表示します。

notReshowSample.png

シーンコンテナのタイトル

シーンコンテナのタイトルはシーンコンテナのメソッド、setTitle(タイトル)で設定でき、getTitle()で取得できます。

setTitle()で設定する以外にも、シーンコンテナのタイトルは以下の条件(上が優先)で自動で設定されます。

  • navigate()で指定されたパラメータのtitleプロパティの値
  • toにコントローラ名が指定された場合はそのコントローラのsceneTitleプロパティの値
  • toにページURLが指定された場合は以下
    • シーン要素のdata-h5-scene-title属性の値
    • シーン要素内のtitleタグの内容

メインシーンコンテナのタイトル

シーンコンテナがメインシーンコンテナである場合は、設定されているタイトルがdocument.titleに反映されます。

document.titleへの反映をさせたくない場合は、h5.settings.scene.followTitleにfalseを設定してください(デフォルトはtrue)。

ベースURLの指定

h5.settings.scene.baseUrl を指定することで、シーンの遷移先、およびルーティング指定のベースとなるURLを指定することができます。
指定しない場合、遷移先としては現URLをベースとし、ルーティング指定はドメインルートがベースとなります。

HTML要素の記述に基づいたコントローラの自動バインド

前提として、 リソース管理機能によりコントローラーのソースファイルが読み込めるよう、ソースファイルを記述・配置する必要があります。

タグにdata-h5-controller属性にてコントローラの__name属性を記述し、ドキュメントロード前にh5.settings.scene.autoInitにtrueを設定すると、フレームワークによりコントローラーのソースファイルロード、およびバインドが自動的に行われます。

<div data-h5-controller="my.project.controller.MyController">

[ver1.2.1]また、後述のh5.scene.scan()関数を実行することでも同様にできます。

カンマ区切りで複数記述することも可能です。シーンと同時に指定した場合、最初のコントローラーがシーンコントローラーとなります。
(※シーン遷移時のパラメーターを受け取れるのはシーンコントローラーのみです)

別ウィンドウを開いてのポップアップ[ver1.2.1]

別ウィンドウを開き、そのウィンドウ内のシーンと連携したい場合は以下のAPIを使用します。
ポップアップウィンドウなどを使用したい場合に便利です。

h5.scene.openWindow(url, name, features, isModal, controllerName, controllerParam)

controllerName, controllerParamは指定しなくても構いません。
その場合、第一引数で指定されたURLをロードした結果のHTMLおよびJSコードに基づいて動作が決定されます。
なお、urlで読み込むページは、最低限シーン機能モジュールを有効にしたhifiveをロードする必要があります。

戻り値はPromiseで、完了時の値はRemoteWindowインスタンスです。
ウィンドウを開くことができなかった、一定時間内に子ウィンドウとの通信を確立できなかった、などの場合はPromiseがfailします。

RemoteWindow = {
 /** 別ウィンドウのシーンを含むウィンドウインスタンス */
 window: obj,

 /** このウィンドウの現在のメインシーンのメソッドを呼び出す。
  戻り値としてPromiseが返された場合、invokeの戻り値はそれに連動したPromiseとなる。
  ただし、引数、戻り値とも、h5.u.obj.serialize()でシリアライズ可能でなければならない。
  該当する名前のメソッドがない場合、例外が発生した場合などはPromiseがfailする。 */
  invoke: function(method:String, args:Array) => Promise,

 /** 指定されたセレクタにマッチするコントローラのプロキシオブジェクトを取得。
        nullの場合は現在のメインシーンのプロキシオブジェクトを取得。 */
  getControllerProxy: function(selector) => InvocationProxy (or null),

 /** このウィンドウをモーダル扱いするかどうか。なお、openModalDialogは使用しないので
  親ウィンドウの操作をブロックすることによる疑似的なモーダルである。
  そのため、一度ウィンドウを開いた後もtrue/falseを切り替えることができる。 */
  setModal: function(bool) => Promise,

 /** ウィンドウを閉じる（※ブラウザにより閉じない場合があるので注意） */
  close: function(void) => Promise  //このメソッドは非同期
}

また、RemoteWindowはいくつかのイベントを発生させます。

発生するイベント：

  • messageReceived: 子ウィンドウからメッセージを受け取った（evArg.data にデータが含まれる）

子ウィンドウから親ウィンドウにメッセージを送る

子ウィンドウ側では、h5.scene.getParentWindow()を呼び出すと、親ウィンドウのRemoteWindowインスタンスを取得できます。

シーンコンテナのnavigateメソッドの実行[ver1.2.1]

シーンコンテナのnavigateについて、ver1.2.0仕様に加えてver1.2.1では以下のプロパティを設定できます。

  • transition … [ver1.2.1] 遷移時のアニメーション効果等を指定します。以下の値が設定できます。
    • 'default' … アニメーションなしで遷移(デフォルト) ※現状これのみ
  • container … [ver1.2.1] 第一引数により取得したHTML要素内で、表示対象とするコンテナのdata-h5-scene-container属性の値を指定します。メインシーンコンテナでは無効となります。

h5.scene.scan関数[ver1.2.1]

前述の通り、h5.settings.scene.autoInitにtrueを設定した場合、ドキュメントロード時にドキュメント全体を対象としてシーンコンテナ・コントローラーの自動生成が行われますが、これを任意のタイミング、もしくは任意の範囲で行いたい場合は、h5.settings.scene.autoInitにtrueを設定せずに、h5.scene.scan関数を実行してください。

  • 第1引数 … 処理対象ルート要素。この要素およびその配下の要素を処理対象とします。指定なしの場合、document.bodyを対象とします。
  • 第2引数 … バインド対象コントローラー名。バインドするコントローラーを限定する場合に指定。指定しない場合(null)は限定しない(data-h5-controller属性の値すべてを対象とする)
  • 第3引数 … シーンに対応するコントローラー生成時に渡すパラメータ。処理対象ルート要素がシーン要素の場合のみ有効。配下要素のシーンには渡されない。
    ※フレームワークでの使用のみを想定。メインシーンコンテナ下のシーンに直接使用されると、URLとの矛盾が生じる。

遷移先のルーティングについて[ver1.2.1]

ルーティングの指定[ver1.2.1]

h5.settings.scene.routes を指定することで、シーンの遷移先を変更することができます。この場合、メインシーンコンテナではURLは変更されませんが、表示は変更後の画面となります。
h5.settings.scene.routesは、以下の形式のオブジェクトの配列となります。

  • testプロパティ … URLチェック用。文字列、正規表現オブジェクト、関数が指定可能です。
    • チェック対象は以下となります。
      • History使用であればURLのドメインルート以下からクエリパラメーターまで
      • Hash使用であれば、Hash以下をドメインルート以下とみなし、クエリパラメーターまで。ただし、Hash値がない場合はURLのドメインルート以下からクエリパラメーターまで(History使用の場合と同様)
    • 指定値の型による動作は以下となります。
      • 文字列の場合 … 完全一致をチェックします。
      • 正規表現オブジェクトの場合 … 正規表現の一致をチェックします。
      • 関数の場合 … 第一引数に上述のチェック対象文字列、第二引数に文字列を遷移パラメーター化したもの(前述「シーンコンテナのnavigateメソッドの実行」の引数と同等)を指定して実行、戻り値がtrueの場合に一致とみなします。
  • navigationInfo … 文字列、オブジェクト、null、関数指定可能です。
    • 文字列の場合 … 前述「シーンコンテナのnavigateメソッドの実行」の引数と同様
    • オブジェクトの場合 … 前述「シーンコンテナのnavigateメソッドの実行」の引数と同様
    • nullの場合 … 変換前のURLに対応した画面を表示します。
    • 関数の場合 …  第一引数に上述のチェック対象文字列、第二引数に文字列を遷移パラメーター化したもの(前述「シーンコンテナのnavigateメソッドの実行」の引数と同等)を指定して実行、戻り値は上述の3パターンのいずれかを返却します。

※定義がループしないよう注意してください。変更後の画面は、ブラウザのURLは変更されないものの、内部的にはURLをルーティングします。変更後の画面のURLが更にルーティングされることもあり得ます。

h5.settings.scene.baseUrl = '/sample/dir/'; // baseUrl については後述
h5.settings.scene.routes = [
    {
        test: 'string.html?param=value', // 文字列で指定する場合はパラメーターも含めてすべて指定
        navigationInfo: 'string_r.html'
    }, {
        test: /^regexp\.html(?:\?|#|$)/,
        navigationInfo: {
            to: 'regexp_r.html'
        }
    }, {
        test: function(url, navigationInfo) {
           return /^function_url\.html(?:\?|#|$)/.test(url);
        },
        navigationInfo: function(url, navigationInfo) {
           return 'function_url_r.html';
        }
    }, {
        test: function(url, navigationInfo) {
           return navigationInfo.to === 'function_info.html';
        },
        navigationInfo: function(url, navigationInfo) {
            navigationInfo.to = 'function_info_r.html'; // この方法だと簡単に他のパラメーターを引き継げる
            return navigationInfo;
        }
    }, {
        test: /^no_info\.html(?:\?|#|$)/,
        navigationInfo: null // nullを指定した場合は変換前のURLが使用される。
    }, {
       // 以下、straight1.html → straight2.html → straight3.html と連続しており、
        // straight1.htmlに遷移するとstraight3.htmlが表示される。(メインシーンコンテナではURLはstraight1.htmlのまま)
        test: /^straight1\.html(?:\?|#|$)/,
        navigationInfo: 'straight2.html'
    }, {
        test: /^straight2\.html(?:\?|#|$)/,
        navigationInfo: 'straight3.html'
    }
];
Copyright (C) 2012-2017 NS Solutions Corporation, All Rights Reserved.