v6.3.3
Support Framework7
logo_github stars forks
logo_applelogo_androiddevice_desktop
スポンサー
Support Framework7

バーチャルリスト

    バーチャルリストは、膨大な量の要素を持つリストを、パフォーマンスを落とすことなくレンダリングできます。また、検索バー、無限スクロール、プルトゥリフレッシュ、スワイプアウト（スワイプトゥデリート）、ソート可能など、リストを扱うすべてのFramework7コンポーネントと完全に互換性があります。

    仮想リストのレイアウト

    バーチャルリストのHTMLレイアウトは非常にシンプルで、通常のリストビューとほぼ同じですが、唯一の違いは空にする必要があることです。

    <!-- バーチャルリスト -->
<div class="list virtual-list">
  <!-- 空にする -->
</div>

    構造

    • virtual-list - バーチャルリストを使用するリストブロックに必要な追加クラスです。

    バーチャルリストアプリのメソッド

    さて、リストのHTMLができたら、それを初期化する必要があります。そのためには、必須のAppメソッドを使用します。

    app.virtualList.create(parameters)- initialize virtual list with parameters

    • parameters - object - バーチャルリストのパラメータを持つオブジェクト。必要です。
    • メソッドは初期化された仮想リストのインスタンスを返します。

    app.virtualList.destroy(el)- 仮想リストインスタンスの破棄

    • el - HTMLElementまたはstring（CSSセレクタを使用）またはobject。破棄する仮想リスト要素または仮想リストインスタンスです。

    app.virtualList.get(el)- HTML要素による仮想リストインスタンスの取得

    • el - HTMLElement または string (CSS Selectorを使用)。仮想リストの要素です。

    メソッドは仮想リストのインスタンスを返します。

    なお、仮想リストのコンテナ（リストブロック要素）は、初期化時にDOMに存在している必要があります。

    仮想リストのパラメータ

    利用可能なパラメータの一覧を見てみましょう。

    ParameterTypeDefaultDescription
    elHTMLElement
    string    		対象となるのは、リストブロック要素です。文字列`の場合 - リストブロック要素のCSSセレクタ
    ulHTMLElement
    string    		リストブロックの中のリスト要素 <ul> です。
    createUlbooleantrue仮想リストブロックの中に、自動的に <ul> という要素が作成されます。無効にすると、バーチャルリストは、ul > li 構造を持たない任意のブロック要素で使用することができます。
    itemsarrayリストアイテムを持つ配列
    rowsBeforenumber現在のスクリーンのスクロール位置の前にレンダリングされる行(アイテム)の量です。デフォルトでは、画面に収まる行(アイテム)の2倍の量になります。
    rowsAfternumber現在の画面のスクロール位置の後にレンダリングされる行（アイテム）の量。デフォルトでは、画面に収まる行（アイテム）の量と同じになります。
    colsnumber11行あたりのアイテムの数。仮想リストを動的な高さで使用する場合は互換性がありません。
    heightnumber or function(item)number の場合は、リストのアイテムの高さを px で表します。functionであれば、関数がアイテムの高さを返します。デフォルトでは、iOSテーマでは44、MDテーマでは48、Auroraテーマでは38となります。
    renderItemfunction(item)このオプション関数は、アイテムの HTML をレンダリングするためにカスタム関数を使用できます。template パラメータの代わりに使うことができます。
    renderExternalfunction(vl, renderParameters)このオプション関数は、カスタムメソッドを使ってDOMアイテムをレンダリングします。例えば、Vue/Reactプラグインを使って、DOMのレンダリングや操作をVue/Reactに渡す場合に便利です。renderParameters は、以下のプロパティを持つオブジェクトを表します。fromIndex, toIndex, listHeight, topPosition, items`.
    emptyTemplatestring空のデータが渡された場合のリストアイテムのテンプレートを定義します。
    dynamicHeightBufferSizenumber1このパラメータは、ダイナミックな高さを持つバーチャルリスト(height パラメータが関数の場合)のバッファサイズを、バッファサイズの乗数として制御することができます。
    cachebooleantrueすでにレンダリングされたリストアイテムのDOMキャッシュを無効または有効にします。この場合、各アイテムは一度だけレンダリングされ、それ以降の操作はすべてDOM要素で行われます。これは、リストアイテムにユーザーインタラクション要素（フォーム要素やスワイプアウトなど）がある場合や、変更が可能な場合に便利です。
    updatableScrollboolean現在のデバイスが更新され、スクロール中にスクロールイベントを処理するかどうかを指定します。デフォルトでは（指定されていない場合）、iOS バージョン 8 未満のすべての iOS デバイスに対して "false" です。
    setListHeightbooleantrue有効な場合、リストブロックの高さを設定します
    showFilteredItemsOnlybooleanfalseフィルタリングされたアイテムを表示するオプションは メソッドで設定されます。
    scrollableParentElHTMLElement
    string    		仮想リストのスクロール可能な親を指定します。指定されていない場合は、親の <div class="page-content"> 要素を探します。
    Searchbar
    searchByItemfunction(query, item, index)サーチバーで使用される検索関数で、検索クエリ、アイテム自体、アイテムのインデックスを受け取ります。アイテムが検索クエリにマッチした場合は true を、そうでない場合は false を返す必要があります。
    searchAllfunction(query, items)Searchbarで使用される検索関数は、検索クエリとすべてのアイテムを含む配列を受け取ります。検索クエリと、すべてのアイテムを含む配列を受け取ります。

    仮想リストのメソッドとプロパティ

    仮想リストを作成するには、以下のメソッドを呼び出す必要があります。

    var virtualList = app.virtualList.create({ /* parameters */ })

    仮想リストを初期化すると、その初期化されたインスタンスが変数（上記の例では virtualList という変数）に格納され、便利なメソッドやプロパティが用意されます。

    Properties
    virtualList.itemsアイテム付きの配列
    virtualList.filteredItemsフィルタリングされたアイテムを含む配列（".filterItems "メソッド使用後
    virtualList.domCacheキャッシュされたdomアイテムを持つオブジェクト
    virtualList.paramsリスト初期化時に渡されるパラメータ
    virtualList.el仮想リストのターゲット・リスト・ブロック要素
    virtualList.$elターゲット・リスト・ブロック要素の Dom7 インスタンス
    virtualList.pageContentEl親 "page-content "要素
    virtualList.$pageContentEl親の "page-content "要素の Dom7 インスタンス
    virtualList.currentFromIndex現在最初にレンダリングされているアイテムのインデックス番号
    virtualList.currentToIndex現在、最後にレンダリングされたアイテムのインデックス番号
    virtualList.reachEndBoolean プロパティ。現在最後にレンダリングされているアイテムが、指定されたすべてのアイテムの最後のアイテムである場合、trueになります。
    Methods
    virtualList.filterItems(indexes);表示するアイテムのインデックスを持つ配列を渡して、仮想リストをフィルタリングします。
    virtualList.resetFilter();フィルタを無効にして、すべてのアイテムを再表示します。
    virtualList.appendItem(item);仮想リストにアイテムを追加する
    virtualList.appendItems(items);アイテムを含む配列を仮想リストに追加します。
    virtualList.prependItem(item);仮想リストにアイテムを追加する
    virtualList.prependItems(items);仮想リストにアイテムを含む配列を前置する
    virtualList.replaceItem(index, item);指定したインデックスのアイテムを新しいものに置き換える
    virtualList.replaceAllItems(items);すべてのアイテムを新しいアイテムの配列で置き換える
    virtualList.moveItem(oldIndex, newIndex);仮想アイテムをoldIndexからnewIndexに移動する
    virtualList.insertItemBefore(index, item);指定されたインデックスのアイテムの前に新しいアイテムを挿入する
    virtualList.deleteItem(index);指定されたインデックスのアイテムを削除する
    virtualList.deleteItems(indexes);指定されたインデックスの配列のアイテムを削除する
    virtualList.deleteAllItems();すべての項目を削除する
    virtualList.clearCache();仮想リストにキャッシュされた DOM 要素のクリア
    virtualList.destroy();初期化された仮想リストの破棄と全てのイベントの切り離し
    virtualList.update();仮想リストの更新(リストサイズの再計算、仮想リストの再レンダリングを含む)
    virtualList.scrollToItem(index);仮想リストをインデックス番号で指定したアイテムまでスクロールする

    仮想リストのイベント

    仮想リストでは、アプリと仮想リストインスタンスで以下のイベントが発生します。

    仮想リストのインスタンスは、自己のインスタンスとアプリのインスタンスの両方にイベントを発行します。アプリインスタンスのイベントは、同じ名前でプレフィックスが vl となっています。

    EventTargetArgumentsDescription
    itemBeforeInsertvirtualListvirtualList, itemEl, itemアイテムが仮想ドキュメントフラグメントに追加される前にイベントが発生します。
    vlItemBeforeInsertapp
    itemsBeforeInsertvirtualListvirtualList, fragment現在のDOMリストが削除され、新しいドキュメントが挿入される前にイベントが発生します。
    vlItemsBeforeInsertapp
    beforeClearvirtualListvirtualList, fragment現在のDOMリストが削除され、新しいドキュメントフラグメントで置き換えられる前に、イベントが発生します。
    vlBeforeClearapp
    itemsAfterInsertvirtualListvirtualList, fragmentイベントは、アイテムが挿入された新しいドキュメントフラグメントの後にトリガされます。
    vlItemsAfterInsertapp

    Examples

    <template>
  <div class="page">
    <div class="navbar">
      <div class="navbar-bg"></div>
      <div class="navbar-inner sliding">
        <div class="title">Virtual List</div>
        <div class="subnavbar">
          <form data-search-container=".virtual-list" data-search-item="li" data-search-in=".item-title"
            class="searchbar searchbar-init">
            <div class="searchbar-inner">
              <div class="searchbar-input-wrap">
                <input type="search" placeholder="Search" />
                <i class="searchbar-icon"></i>
                <span class="input-clear-button"></span>
              </div>
              <span class="searchbar-disable-button if-not-aurora">Cancel</span>
            </div>
          </form>
        </div>
      </div>
    </div>
    <div class="searchbar-backdrop"></div>
    <div class="page-content">
      <div class="list simple-list searchbar-not-found">
        <ul>
          <li>Nothing found</li>
        </ul>
      </div>
      <div class="list virtual-list media-list searchbar-found"></div>
    </div>
  </div>
</template>
<script>
  export default (props, { $f7, $el, $theme, $on }) => {
    let items = [];
    for (let i = 1; i <= 10000; i++) {
      items.push({
        title: 'Item ' + i,
        subtitle: 'Subtitle ' + i
      });
    }
    $on('pageInit', () => {
      const virtualList = $f7.virtualList.create({
        // List Element
        el: $el.value.find('.virtual-list'),
        // Pass array with items
        items,
        // Custom search function for searchbar
        searchAll: function (query, items) {
          var found = [];
          for (var i = 0; i < items.length; i++) {
            if (items[i].title.toLowerCase().indexOf(query.toLowerCase()) >= 0 || query.trim() === '') found.push(i);
          }
          return found; //return array with mathced indexes
        },
        // List item render
        renderItem(item) {
          return `
          <li>
            <a href="#" class="item-link item-content">
              <div class="item-inner">
                <div class="item-title-row">
                  <div class="item-title">${item.title}</div>
                </div>
                <div class="item-subtitle">${item.subtitle}</div>
              </div>
            </a>
          </li>`;
        },
        // Item height
        height: $theme.ios ? 63 : ($theme.md ? 73 : 77),
      });
    });

    return $render;
  }
</script>