プルトゥリフレッシュ

Pull To Refreshは、ページのコンテンツの更新を開始するために使用できる特別なコンポーネントです。

リフレッシュボタンのレイアウト

ページにPull To Refreshを組み込む方法を見てみましょう。

<div class="page">
  <!-- ページのコンテンツには、"ptr-content "クラスを追加する必要があります。 -->
  <div class="page-content ptr-content" data-ptr-distance="55" data-ptr-mousewheel="true">
    <!-- デフォルトの pull to refresh プリローダ-->
    <div class="ptr-preloader">
      <div class="preloader"></div>
      <div class="ptr-arrow"></div>
    </div>

    <!-- 通常のコンテンツの下に -->
    <div class="list">
      ...
    </div>

    <!-- 入れ子になったスクロール可能な要素 -->
    <div class="my-scolling-content ptr-watch-scrollable">
      ...
    </div>

    <!-- 別のネストされたスクロール可能な要素 -->
    <div class="another-scolling-content ptr-ignore">
      ...
    </div>
  </div>
</div>

構造

ptr-content のクラスです。これは、プル・トゥ・リフレッシュを有効にするために必要です。
div class="ptr-preloader" 隠されたレイヤーで、プル・トゥ・リフレッシュのビジュアル要素であるプリローダーと矢印があります。
data-ptr-distance="55" 追加属性で、カスタムのプル・トゥ・リフレッシュのトリガー距離を設定できます。デフォルトでは（指定されていない場合）、44pxです。
data-ptr-mousewheel="true" 追加属性で、マウスホイールでのプル・トゥ・リフレッシュを有効にします（デスクトップアプリ用）。PTR topでのみ動作します。
ptr-watch-scrollable - ネストされたスクロール可能な要素上に追加されるクラスで、そのような要素がスクロールしたときに、プルでのリフレッシュを防止します。
ptr-ignore - ネストされたスクロール可能な要素や、スクロールやタッチ操作でのプルトゥリフレッシュを防ぐために、そのような要素上に追加する必要のあるクラスです。

下から更新する場合

また、下から引くように動作させることも可能です。この場合、ptr-preloader要素をページコンテンツの一番下に移動させ、コンテンツを更新するために、追加のptr-bottomクラスを追加する必要があります。

<div class="page">
  <!-- ptr-contentには "ptr-bottom "クラスを追加する必要があります。 -->
  <div class="page-content ptr-content ptr-bottom">
    <div class="list">
      ...
    </div>

    <!-- リフレッシュのためにプリローダーを下に移動 -->
    <div class="ptr-preloader">
      <div class="preloader"></div>
      <div class="ptr-arrow"></div>
    </div>
  </div>
</div>

リフレッシュのためのプルシーケンス

ユーザーがptr-contentを下に引っ張り始めると、ptr-preloaderは追加のptr-pull-downクラスを受け取ります。

ユーザーがptr-contentを44px以上引き下げると（ptr-preloaderが完全に表示される場合）、ptr-preloaderは追加のptr-pull-upクラスを受け取り、矢印の回転を変えて、リリース時のリフレッシュ動作をユーザーに通知します。

ptr-pull-up "状態のときに、コンテンツをリフレッシュするためにユーザーがプルをリリースすると、ptr-preloaderは追加のptr-refreshingクラスを受け取ります。refreshing "状態では、矢印は隠され、ユーザーはプリローダーのインジケータを見ることになります。この段階では、おそらくAjaxリクエストを行い、ページのコンテンツを更新する必要があります。

アプリのメソッドをリフレッシュするプル

Pull To Refreshコンテナで使用できるアプリのメソッドはいくつかあります。

app.ptr.create(el)- initialise PTR on specified HTML element container.

el - HTMLElementまたはstring（CSSセレクタ付き） - PTR要素（ptr-content）。必須です。

作成されたPTRのインスタンスを返します。

Use this method only in case you have added ptr content after page init or if you want to enable it later. Otherwise if there is "ptr-content" element on page init it will be created automatically

app.ptr.destroy(el)- remove PTR event listeners from the specified HTML element

el - HTMLElement または string (with CSS selector) - PTR要素 (ptr-content). 必須です。

app.ptr.get(el)- HTML要素によるPTRインスタンスの取得

el - HTMLElement または string (with CSS selector). PTR要素(ptr-content)です。

メソッドはPTRのインスタンスを返します。

app.ptr.done(el)- 指定されたPTRコンテンツ要素のPTR状態をリセットする

el - HTMLElement または string (with CSS Selector). PTR要素（ptr-content）です。必須。

app.ptr.refresh(el)- 指定されたPTRコンテンツ要素に対してPTRを起動する

el - HTMLElement または string (with CSS Selector). PTR要素(ptr-content)を指定します。必須。

メソッドとプロパティを更新するためのプル

PTRを手動で作成した場合や、app.ptr.getメソッドを使用した場合、便利なメソッドやプロパティを持つPTRの初期化されたインスタンスが得られます。

// 手動でPTRを初期化
var ptr = app.ptr.create('.ptr-content');

// または get を使って既に作成されたインスタンスを取得します。
var ptr = app.ptr.get('.ptr-content');

Properties
ptr.app	グローバルアプリのインスタンスへのリンク
ptr.el	PTRのHTML要素 (`ptr-content`)
ptr.$el	PTRのHTML要素(`ptr-content`)を使って、Dom7インスタンスを作成します。
Methods
ptr.done()	PTRの状態をリセット
ptr.refresh()	PTRのトリガー
ptr.destroy()	PTR インスタンスを破棄し、指定された HTML 要素から PTR イベントリスナーを削除します。

リフレッシュイベントへの引き込み

PTR は popup 要素に対して以下の DOM イベントを、app と popup インスタンスに対してイベントを発生させます。

DOM イベント

Event	Target	Description
ptr:pullstart	Pull To Refresh content<div class="ptr-content">	イベントは、コンテンツを更新するためにプルを動かし始めたときに発生します。
ptr:pullmove	Pull To Refresh content<div class="ptr-content">	イベントは、コンテンツを更新するためにプルを動かしている間に発生します。
ptr:pullend	Pull To Refresh content<div class="ptr-content">	コンテンツを更新するためにプルを解放したときにイベントが発生します。
ptr:refresh	Pull To Refresh content<div class="ptr-content">	イベントは、プルツーリフレッシュが "リフレッシュ "状態になったときに発生します。event.detail `には、読み込み完了後に状態をリセットするための` ptr.done` メソッドが含まれています。
ptr:done	Pull To Refresh content<div class="ptr-content">	イベントは、プルツーリフレッシュが完了し、初期状態に戻った後（`ptr.done`メソッドを呼び出した後）に発生します。
ptr:beforedestroy	Pull To Refresh content<div class="ptr-content">	PTRインスタンスが破棄される直前にイベントが発生します。

App と Pull To Refresh インスタンスのイベント

PTRインスタンスはselfインスタンスとappインスタンスの両方にイベントを発行します。アプリインスタンスのイベントは、同じ名前でプレフィックスとして ptr が付きます。

Event	Target	Arguments	Description
pullStart	ptr	(el)	イベントは、コンテンツを更新するためにプルを動かし始めたときにトリガーされます。イベントハンドラは引数として ptr 要素を受け取ります。
ptrPullStart	app	(el)
pullMove	ptr	(el, data)	イベントは、コンテンツを更新するためにプルを動かしている間に発生します。イベントハンドラは引数として、ptr 要素と、以下のプロパティを含む ptr データを受け取ります。 `event` - touchmove イベント `scrollTop` - 現在のスクロールトップの位置 `translate` - 現在のトランスレートYオフセット `touchesDiff` - タッチの差（px単位）。
ptrPullMove	app	(el, data)
pullEnd	ptr	(el, data)	イベントは、コンテンツを更新するためにプルをリリースしたときにトリガーされます。イベントハンドラは引数として、ptr要素を受け取ります。
ptrPullEnd	app	(el, data)
refresh	ptr	(el, done)	イベントは、pull to refresh が "refreshing" 状態になった時に発生します。イベントハンドラは引数として、ptr要素とPTRの状態をリセットする`done`関数を受け取ります。
ptrRefresh	app	(el, done)
done	ptr	(el)	プルツーリフレッシュが完了し、初期状態に戻った後（`ptr.done`メソッドを呼び出した後）にイベントが発生します。イベントハンドラは引数として ptr 要素を受け取ります。
ptrDone	app	(el)
beforeDestroy	ptr	(ptr)	PTRインスタンスが破棄される直前にイベントが発生します。PTRインスタンスを受け取るイベントハンドラの引数として
ptrBeforeDestroy	app	(ptr)	PTRインスタンスが破棄される直前にイベントが発生します。PTRインスタンスを受け取るイベントハンドラの引数として

CSS Variables

Below is the list of related CSS variables (CSS custom properties).

.ios {
  --f7-ptr-preloader-size: 28px;
  --f7-ptr-size: 44px;
}
.md {
  --f7-ptr-preloader-size: 22px;
  --f7-ptr-size: 40px;
}
.aurora {
  --f7-ptr-preloader-size: 20px;
  --f7-ptr-size: 38px;
}

例

Pull From Top

<template>
  <div class="page">
    <div class="navbar">
      <div class="navbar-bg"></div>
      <div class="navbar-inner">
        <div class="title">Pull To Refresh</div>
      </div>
    </div>
    <div class="page-content ptr-content" @ptr:refresh=${loadMore}>
      <div class="ptr-preloader">
        <div class="preloader"></div>
        <div class="ptr-arrow"></div>
      </div>
      <div class="list media-list">
        <ul>
          ${items.map((item) => $h`
          <li class="item-content">
            <div class="item-media"><img src=${item.picURL} width="44" /></div>
            <div class="item-inner">
              <div class="item-title-row">
                <div class="item-title">${item.song}</div>
              </div>
              <div class="item-subtitle">${item.author}</div>
            </div>
          </li>
          `)}
        </ul>
      </div>
    </div>
  </div>
</template>
<script>
  export default (props, { $update }) => {
    // Dummy Content
    const songs = ['Yellow Submarine', 'Don\'t Stop Me Now', 'Billie Jean', 'Californication'];
    const authors = ['Beatles', 'Queen', 'Michael Jackson', 'Red Hot Chili Peppers'];
    let items = [
      {
        picURL: 'https://cdn.framework7.io/placeholder/abstract-88x88-1.jpg',
        song: 'Yellow Submarine',
        author: 'Beatles',
      },
      {
        picURL: 'https://cdn.framework7.io/placeholder/abstract-88x88-2.jpg',
        song: 'Don\'t Stop Me Now',
        author: 'Queen',
      },
      {
        picURL: 'https://cdn.framework7.io/placeholder/abstract-88x88-3.jpg',
        song: 'Billie Jean',
        author: 'Michael Jackson',
      },
    ]

    const loadMore = (e, done) => {
      // Emulate 2s loading
      setTimeout(() => {
        const picURL = 'https://cdn.framework7.io/placeholder/abstract-88x88-' + (Math.floor(Math.random() * 10) + 1) + '.jpg';
        const song = songs[Math.floor(Math.random() * songs.length)];
        const author = authors[Math.floor(Math.random() * authors.length)];
        // Add new item
        items.push({
          picURL,
          song,
          author,
        });

        // Update state to rerender
        $update();

        // When loading done, we need to reset it
        done();
      }, 2000);
    }

    return $render;
  }
</script>

Pull From Bottom

<template>
  <div class="page">
    <div class="navbar">
      <div class="navbar-bg"></div>
      <div class="navbar-inner">
        <div class="title">Pull To Refresh Bottom</div>
      </div>
    </div>
    <div class="page-content ptr-content ptr-bottom" @ptr:refresh=${loadMore}>
      <div class="ptr-preloader">
        <div class="preloader"></div>
        <div class="ptr-arrow"></div>
      </div>
      <div class="list media-list">
        <ul>
          ${items.map((item) => $h`
          <li class="item-content">
            <div class="item-media"><img src=${item.picURL} width="44" /></div>
            <div class="item-inner">
              <div class="item-title-row">
                <div class="item-title">${item.song}</div>
              </div>
              <div class="item-subtitle">${item.author}</div>
            </div>
          </li>
          `)}
        </ul>
      </div>
    </div>
  </div>
</template>
<script>
  export default (props, { $update }) => {
    // Dummy Content
    const songs = ['Yellow Submarine', 'Don\'t Stop Me Now', 'Billie Jean', 'Californication'];
    const authors = ['Beatles', 'Queen', 'Michael Jackson', 'Red Hot Chili Peppers'];
    let items = [
      {
        picURL: 'https://cdn.framework7.io/placeholder/abstract-88x88-1.jpg',
        song: 'Yellow Submarine',
        author: 'Beatles',
      },
      {
        picURL: 'https://cdn.framework7.io/placeholder/abstract-88x88-2.jpg',
        song: 'Don\'t Stop Me Now',
        author: 'Queen',
      },
      {
        picURL: 'https://cdn.framework7.io/placeholder/abstract-88x88-3.jpg',
        song: 'Billie Jean',
        author: 'Michael Jackson',
      },
    ]

    const loadMore = (e, done) => {
      // Emulate 2s loading
      setTimeout(() => {
        const picURL = 'https://cdn.framework7.io/placeholder/abstract-88x88-' + (Math.floor(Math.random() * 10) + 1) + '.jpg';
        const song = songs[Math.floor(Math.random() * songs.length)];
        const author = authors[Math.floor(Math.random() * authors.length)];
        // Add new item
        items.push({
          picURL,
          song,
          author,
        });

        // Update state to rerender
        $update();

        // When loading done, we need to reset it
        done();
      }, 2000);
    }

    return $render;
  }
</script>