ons-page

ページ定義のためのコンポーネントです。このコンポーネントの内容はスクロールが許可されます。

実例

The page element

The root of a page in Onsen UI is created using the <ons-page> element. It covers the whole screen and is used as a container for the other elements. When managing multiple views, all of them must be contained in <ons-page> element.

<ons-page>
  Content goes here
</ons-page>

This element automatically spawns a background and a content elements. These can also be manually provided for higher customizability:

<ons-page>
  Toolbar here

  <div class="background"></div>

  <div class="content">
    Scrollable content here
  </div>

  Fixed content here
</ons-page>

Since content element is transparent by default, we can add custom colors to the background element. Notice that, if content element is provided, scrollable and fixed content must be manually separated as well. See Compilation section for further details.

Lifecycle

The page element throws init, show, hide and destroy events depending on its lifecycle. The most important one is perhaps init event, where all the page initialization code should be placed:

document.addEventListener('init', function(event) {
  var page = event.target;
  if (page.matches('#myPageID') {
    // Set up page's dynamic content or behavior
    page.querySelector('ons-toolbar .center').innerHTML = 'Title';
    page.querySelector('ons-button').onclick = function() {};
    // ...
  }
});

Alternatively, lifecycle hooks are also provided for those who prefer a more compact approach. onInit, onShow, onHide and onDestroy are run at the same time as their corresponding events. Hooks must be added in a script tag directly inside the page:

<ons-page>
  Content here

  <script>
    ons.getScriptPage().onInit = function() {
      // Hooks are bound to the page element

      this.querySelector('ons-toolbar .center').innerHTML = 'Title';
      this.onShow = function() {};
    };
  </script>
</ons-page>

ons.getScriptPage() returns the page element of the current script tag. It cannot be used in any other context.

Infinite scroll

By using the onInfiniteScroll DOM prop or the on-infinite-scroll attribute we can set an action that will be executed whenever the scroll reaches the bottom of the page. This can be used, for example, to add new items to a list:

document.addEventListener('init', function(event) {
  var page = event.target;

  page.onInfiniteScroll = function(done) {
    var list = page.querySelector('ons-list');

    getNewAsyncData()
      .then(function(data) {

        data.forEach(function(item) {
          var newItem = ons.createElement('<ons-list-item>' + item + '<ons-list-item>');
          list.appendChild(newItem);
        });

        done(); // Important!
      });
  };
});

Note that done callback should be called when the processing is over. If, for some reason, you have asynchronous operations, make sure done runs after everything is finished.

Compilation

There are basically 3 parts inside an ons-page:

  • Background: Applies background color or image.
  • Scrollable content: Scrollable part where most of the content is included.
  • Fixed elements: Content that is fixed in the screen during scroll.

ons-page tries to separate fixed and scrollable content upon creation when these parts are not provided. Specifically, when you create a page like this:

<ons-page>
  <ons-toolbar></ons-toolbar>
  Some content here
  <ons-input></ons-input>
  <ons-fab></ons-fab>
  <div>More content</div>
</ons-page>
`

ons-page will compile in the following way:

<ons-page class="page">
  <ons-toolbar></ons-toolbar>
  <div class="page__background"></div>
  <div class="page__content">
    Some content here
    <ons-input></ons-input>
    <div>More content</div>
  </div>
  <ons-fab></ons-fab>
</ons-page>

As you can see, it added .page, div.page__background and div.page__content automatically. ons-toolbar and ons-fab are fixed content so they are left outside the previous wrappers. If you want to add an extra ons-fab after all of this happens, you should add it as a direct child of ons-page. However, other non-fixed elements like ons-input must be appended inside div.page__content.

Knowing this, it is very easy to bypass the compilation process. If you directly provide the previous structure, Onsen UI won’t need to change anything at all. To make it easier, you can just include <div class="content"> or <div class="background"> and the other necessary classes (page__content and page__background) will be added automatically. Example:

<ons-page>
  <ons-toolbar></ons-toolbar>
  <div class="content">
    Some content here
    <ons-input></ons-input>
    <div>More content</div>
  </div>
  <ons-fab></ons-fab>
</ons-page>

As a side note, the scrollable part of ons-page is precisely div.page__content. Therefore, if you need to add listeners or anything else, you should use the latter.

関連情報

属性

名前 型 / デフォルト値 概要
modifier String スタイル定義をカスタマイズするための名前を指定します。 Optional.
on-infinite-scroll String Path of the function to be executed on infinite scrolling. Example: app.loadData. The function receives a done callback that must be called when it’s finished. (翻訳中) Optional.

プロパティ概要

名前 概要
onInfiniteScroll Function to be executed when scrolling to the bottom of the page. The function receives a done callback as an argument that must be called when it’s finished. (翻訳中)
onDeviceBackButton バックボタンハンドラ。
data User’s custom data passed to pushPage()-like methods. (翻訳中)

プリセットのmodifier

Name 概要
material Material Design style (翻訳中)

イベント

名前 概要
init ページがアタッチされた後に発火します。
show ページが表示された後に発火します。
hide ページが隠れた後に発火します。
destroy ページが破棄される前に発火します。
init

ページがアタッチされた後に発火します。

パラメーター
名前 概要
event Object Event object.
show

ページが表示された後に発火します。

パラメーター
名前 概要
event Object Event object.
hide

ページが隠れた後に発火します。

パラメーター
名前 概要
event Object Event object.
destroy

ページが破棄される前に発火します。

パラメーター
名前 概要
event Object Event object.

お困りですか?

Onsen UIに関する質問は、Stack Overflowにてonsen-uiタグを付与してください。Onsen UIチームはあなたの問題解決をお手伝いします。

バグ報告や機能要望については、GitHub Issuesに記載をお願いいたします。

あわせて、下記の情報も参考にしてください。