ons-pull-hook

実例

Pull to refresh

The <ons-pull-hook> is used to perform an action when the user pulls down the page. It’s a common design pattern in mobile apps.

It is normally put as a direct descendant to the <ons-page> element.

<ons-page>
  <ons-toolbar>
    ...
  </ons-toolbar>

  <ons-pull-hook></ons-pull-hook>
</ons-page>

Setting the callback

The callback that should be executed when the user pulls the page can be set as an expression with ng-action attribute: <ons-pull-hook ng-action="myController.load($done)">

This callback will take a $done function as an argument that needs to be called when the action is performed. Calling the function will cause the page to snap back into position.

app.controller('MyController', function() {
  this.load = function($done) {
    refreshData()
      .then($done);
  };
});

States

The <ons-pull-hook> has three different states:

  • initial - Initial state.
  • preaction - Will run the callback when released.
  • action - Currently running the callback.

The element will update its state in pullHook.state property so it can be easily accessed by, for example, ng-switch:

<ons-pull-hook ng-action="page.load($done)" var="pullHook">
  <span ng-switch="pullHookElement.state">
    <span ng-switch-when="initial">Pull down to refresh</span>
    <span ng-switch-when="preaction">Release to refresh</span>
    <span ng-switch-when="action">Loading data...</span>
  </span>
</ons-pull-hook>

Styling with CSS

Another way to change the content or the appearance of the <ons-pull-hook> element is to use CSS and attribute selectors.

The element has the attribute style which will have the value of the current state:

ons-pull-hook[style="initial"] {
  // Write some style for initial state here.
}

...

Customizing the behavior

There are a number of attributes that can be used to configure how the <ons-pull-hook> will behave.

The height attribute defines how long the component must be pulled before transitioning to the preaction state. With the threshold-height attribute the component can be configured to transition directly to the action state without releasing.

There is also an attribute called fixed-content that prevents the page from moving while scrolling.

属性

名前 型 / デフォルト値 概要
disabled この属性がある時、disabled状態になりアクションが実行されなくなります Optional.
height String コンポーネントの高さを指定します。この高さ以上にpull downすると”preaction”状態に移行します。デフォルトの値は”64px”です。 Optional.
threshold-height String 閾値となる高さを指定します。この値で指定した高さよりもpull downすると、このコンポーネントは自動的に”action”状態に移行します。 Optional.
fixed-content この属性がある時、プルフックが引き出されている時にもコンテンツは動きません。 Optional.
var String このコンポーネントを参照するための名前を指定します。 Optional. 初期化時のみ有効
ng-action Expression pull downしたときの振る舞いを指定します。アクションが完了した時には$done関数を呼び出します。 Optional. 初期化時のみ有効
ons-changestate Expression “changestate”イベントが発火された時の挙動を独自に指定できます。 Optional. 初期化時のみ有効

プロパティ概要

名前 概要
onAction This will be called in the action state if it exists. The function will be given a done callback as it’s first argument. (翻訳中)
onPull Hook called whenever the user pulls the element. It gets the pulled distance ratio (scroll / height) and an animationOptions object as arguments. (翻訳中)
height The height of the pull hook in pixels. The default value is 64px. (翻訳中)
thresholdHeight The thresholdHeight of the pull hook in pixels. The default value is 96px. (翻訳中)
state Current state of the element. (翻訳中)
pullDistance 現在のプルフックが引き出された距離をピクセル数。
disabled 無効化されている場合にtrue

メソッド

シグネチャ 概要
on(eventName, listener) イベントリスナーを追加します。
once(eventName, listener) 一度だけ呼び出されるイベントリスナーを追加します。
off(eventName, [listener]) イベントリスナーを削除します。もしイベントリスナーを指定しなかった場合には、そのイベントに紐づく全てのイベントリスナーが削除されます。
on(eventName, listener)

イベントリスナーを追加します。

パラメーター
名前 概要
eventName String イベント名を指定します。
listener Function このイベントが発火された際に呼び出される関数オブジェクトを指定します。
once(eventName, listener)

一度だけ呼び出されるイベントリスナーを追加します。

パラメーター
名前 概要
eventName String イベント名を指定します。
listener Function イベントが発火した際に呼び出される関数オブジェクトを指定します。
off(eventName, [listener])

イベントリスナーを削除します。もしイベントリスナーを指定しなかった場合には、そのイベントに紐づく全てのイベントリスナーが削除されます。

パラメーター
名前 概要
eventName String イベント名を指定します。
listener Function 削除するイベントリスナーを指定します。

イベント

名前 概要
changestate コンポーネントの状態が変わった場合に発火します。状態は、”initial”, “preaction”, “action”のいずれかです。
changestate

コンポーネントの状態が変わった場合に発火します。状態は、”initial”, “preaction”, “action”のいずれかです。

パラメーター
名前 概要
event Object イベントオブジェクト。
event.pullHook Object コンポーネントのオブジェクト。
event.state String 現在の状態名を参照できます。

お困りですか?

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

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

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