パネル / サイドパネル

パネルレイアウト

アプリにサイドパネルを追加する方法を見てみましょう。アプリには最大2つのパネルを含めることができ、左側に1つ、右側にもう1つです。パネルのHTMLは、アプリのルート要素（またはルート要素を使用していない場合は<body>）の先頭に記述する必要があります。

<body>
  <!-- App root element -->
  <div id="app">
    <!-- Left panel -->
    <div class="panel panel-left">
        ... panel content goes here ...
    </div>

    <!-- Right panel -->
    <div class="panel panel-right">
        ... panel content goes here ...
    </div>

    ...
  </div>
</body>

パネルを追加したら、各パネルの開閉効果を選択する必要があります。次のいずれかの効果を使用できます。

"reveal" - パネルがアプリのコンテンツ全体を移動させます。
"cover" - パネルがアプリのコンテンツを覆い隠します。
"push" - パネルとアプリのコンテンツの両方が一緒に移動します。
"floating" - "cover"と似ていますが、パネルの周りに余分なスペースがあります。

"Reveal"効果を使用する場合は、パネルに追加のpanel-revealクラスを追加する必要があります。cover効果の場合はpanel-cover、push効果の場合はpanel-pushを追加します。

<body>
  <!-- App root element -->
  <div id="app">
    <!-- Left panel, let it be with reveal effect -->
    <div class="panel panel-left panel-reveal">
        ... panel content goes here ...
    </div>

    <!-- Right panel, with cover effect -->
    <div class="panel panel-right panel-cover">
        ... panel content goes here ...
    </div>

    ...
  </div>
</body>

各パネルはサイズ変更可能です。パネルをサイズ変更可能にするには、パネル要素にpanel-resizableクラスを追加するだけです。

<body>
  <!-- App root element -->
  <div id="app">
    <!-- Make left panel resizable -->
    <div class="panel panel-left panel-resizable">
        ... panel content goes here ...
    </div>

    <!-- Make right panel resizable -->
    <div class="panel panel-right panel-resizable">
        ... panel content goes here ...
    </div>
    ...
  </div>
</body>

パネルアプリメソッド

パネルを操作するための関連するアプリメソッドを見てみましょう。

app.panel.create(parameters) - パネルインスタンスを作成します。

parameters - object。パネルパラメーターを持つオブジェクト。

メソッドは作成されたパネルのインスタンスを返します。

app.panel.destroy(el) - パネルインスタンスを破棄します。

el - HTMLElement または string（CSSセレクター付き）または object。破棄するパネル要素またはパネルインスタンス。

app.panel.get(el) - HTML要素でパネルインスタンスを取得します。

el - HTMLElement または string（CSSセレクター付き）。パネル要素。

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

app.panel.open(panel, animate) - パネルを開きます。

panel - HTMLElement または string（開くパネル要素のCSSセレクター付き）
animate - boolean。アニメーション付きで開くかどうか。オプション、デフォルトはtrueです。

app.panel.close(panel, animate) - パネルを閉じます。

panel - HTMLElement または string（閉じるパネル要素のCSSセレクター付き）
animate - boolean。アニメーション付きで閉じるかどうか。オプション、デフォルトはtrueです。

app.panel.toggle(panel, animate) - パネルを切り替えます。

panel - HTMLElement または string（切り替えるパネル要素のCSSセレクター付き）
animate - boolean。アニメーション付きで開閉するかどうか。オプション、デフォルトはtrueです。

パネルパラメーター

app.panel.createメソッドを使用してパネルを手動で作成する場合、パネルパラメーターを持つオブジェクトを渡す必要があります。

パラメーター	型	デフォルト	説明
el	HTMLElement string		パネル要素
resizable	boolean		サイズ変更可能なパネルを有効にします。渡されない場合、`panel-resizable`クラスに基づいて決定されます。
visibleBreakpoint	number		左パネルが常に表示される最小アプリ幅（px単位）
collapsedBreakpoint	number		最小アプリ幅（px単位）で、左パネルが部分的に表示（折りたたまれた状態）になります。
swipe	boolean	false	スワイプでパネルを開閉する機能を有効にする場合に有効にします。
swipeNoFollow	boolean	false	古い/低速デバイスでのパフォーマンスを向上させるためのフォールバックオプション。有効にすると、スワイプパネルはタッチ移動中に指に従わず、左右にスワイプすると自動的に開閉します。
swipeActiveArea	number	0	画面からパネルスワイプをトリガーする不可視エッジの幅（px単位）
swipeOnlyClose	boolean	false	このパラメーターを使用すると、スワイプでパネルを閉じることができます（開くことはできません）。（`swipe`も有効にする必要があります）
swipeThreshold	number	0	「タッチ距離」がこの値（px単位）より小さい場合、パネルはスワイプで移動しません。
backdrop	boolean	true	パネルの背景（背後の暗い半透明レイヤー）を有効にします。
backdropEl	HTMLElement string		カスタム背景要素のHTML要素または文字列CSSセレクター
closeByBackdropClick	boolean	true	パネルの外側をクリックしてパネルを閉じる機能を有効/無効にします。
containerEl	HTMLElement string		パネルをアプリのルート要素ではなく、カスタム要素にマウントできます。
on	object		イベントハンドラーを持つオブジェクト。たとえば、 `var panel = app.panel.create({ el: '.panel-left', on: { opened: function () { console.log('Panel opened') } } })`

例:

var panel = app.panel.create({
  el: '.panel-left',
  resizable: true,
  visibleBreakpoint: 1024,
  collapsedBreakpoint: 768,
})

次のすべてのパラメーターは、グローバルアプリパラメーターのpanelプロパティの下で使用して、すべてのパネルのデフォルトを設定できることに注意してください。例：

var app = new Framework7({
  panel: {
    swipe: true,
    visibleBreakpoint: 1024,
  }
});

パネルメソッドとプロパティ

パネルインスタンスを作成（app.panel.createの呼び出し）した後、またはパネルインスタンスを取得（app.panel.getの呼び出し）した後、その便利なメソッドとプロパティを使用できます。

プロパティ
panel.app	グローバルアプリインスタンスへのリンク
panel.side	パネルの側面を示す文字列：`left`または`right`
panel.effect	パネル効果を示す文字列：`cover`、`reveal`、`floating`、または`push`
panel.opened	開いているかどうかを示すブール値プロパティ
panel.el	パネルHTML要素
panel.$el	パネルHTML要素を持つDom7インスタンス
panel.backdropEl	背景HTML要素
panel.$backdropEl	背景HTML要素を持つDom7インスタンス
panel.params	パネルパラメーター
panel.containerEl	パネルをマウントする要素。（デフォルト`app.el`-ルートアプリ要素）
panel.$containerEl	パネルをマウントする要素を持つDom7インスタンス。（デフォルト`app.el`-ルートアプリ要素）
メソッド
panel.open(animate)	パネルを開きます。ここで animate - boolean（デフォルトは`true`） - アニメーション付きで開くかどうかを定義します。
panel.close(animate)	パネルを閉じます。ここで animate - boolean（デフォルトは`true`） - アニメーション付きで閉じるかどうかを定義します。
panel.toggle(animate)	パネルを切り替えます。ここで animate - boolean（デフォルトは`true`） - アニメーション付きで閉じるかどうかを定義します。
panel.enableVisibleBreakpoint()	表示ブレークポイントを有効にします
panel.disableVisibleBreakpoint()	表示ブレークポイントを無効にします
panel.toggleVisibleBreakpoint()	表示ブレークポイントを切り替えます
panel.enableCollapsedBreakpoint()	折りたたみブレークポイントを有効にします
panel.disableCollapsedBreakpoint()	折りたたみブレークポイントを無効にします
panel.toggleCollapsedBreakpoint()	折りたたみブレークポイントを切り替えます
panel.enableResizable()	サイズ変更可能なパネルを有効にします
panel.disableResizable()	サイズ変更可能なパネルを無効にします
panel.enableSwipe()	スワイプ可能なパネルを有効にします
panel.disableSwipe()	スワイプ可能なパネルを無効にします
panel.destroy()	パネルインスタンスを破棄します
panel.on(event, handler)	イベントハンドラーを追加します
panel.once(event, handler)	発生後に削除されるイベントハンドラーを追加します
panel.off(event, handler)	イベントハンドラーを削除します
panel.off(event)	指定されたイベントのすべてのハンドラーを削除します
panel.emit(event, ...args)	インスタンスでイベントを発火させます

パネルイベント

パネルは、パネル要素で次のDOMイベントを発火させ、アプリとパネルインスタンスでイベントを発火させます。

DOMイベント

イベント	ターゲット	説明
panel:open	パネル要素<div class="panel">	パネルが開くアニメーションを開始するとトリガーされるイベント
panel:opened	パネル要素<div class="panel">	パネルが開くアニメーションを完了した後にトリガーされるイベント
panel:close	パネル要素<div class="panel">	パネルが閉じるアニメーションを開始するとトリガーされるイベント
panel:closed	パネル要素<div class="panel">	パネルが閉じるアニメーションを完了した後にトリガーされるイベント
panel:backdrop-click	パネルオーバーレイ要素<div class="panel-backdrop">	パネルオーバーレイがクリックされたときにトリガーされるイベント
panel:swipeopen	パネル要素<div class="panel">	スワイプで開くごく最初にトリガーされるイベント
panel:swipe	パネル要素<div class="panel">	タッチスワイプ動作中にスワイプパネルでトリガーされるイベント
panel:collapsedbreakpoint	パネル要素<div class="panel">	アプリの幅が`collapsedBreakpoint`と一致した場合に、表示/非表示になるとトリガーされるイベント
panel:breakpoint	パネル要素<div class="panel">	アプリの幅が`visibleBreakpoint`と一致した場合に、表示/非表示になるとトリガーされるイベント
panel:resize	パネル要素<div class="panel">	サイズ変更可能なパネルのサイズ変更時にトリガーされるイベント
panel:beforedestroy	パネル要素<div class="panel">	パネルインスタンスが破棄される直前にトリガーされるイベント

アプリとパネルインスタンスイベント

パネルインスタンスは、自分自身のインスタンスとアプリインスタンスの両方でイベントを発行します。アプリインスタンスイベントには、panelという接頭辞が付いた同じ名前があります。

イベント	ターゲット	引数	説明
open	パネル	(パネル)	パネルが開くアニメーションを開始するとトリガーされるイベント。引数として、イベントハンドラーはパネルインスタンスを受け取ります。
panelOpen	アプリ	(パネル)
opened	パネル	(パネル)	パネルの開くアニメーションが完了したときにイベントがトリガーされます。イベントハンドラーは引数としてパネルインスタンスを受け取ります。
panelOpened	アプリ	(パネル)
close	パネル	(パネル)	パネルの閉じるアニメーションが開始されたときにイベントがトリガーされます。イベントハンドラーは引数としてパネルインスタンスを受け取ります。
panelClose	アプリ	(パネル)
closed	パネル	(パネル)	パネルの閉じるアニメーションが完了したときにイベントがトリガーされます。イベントハンドラーは引数としてパネルインスタンスを受け取ります。
panelClosed	アプリ	(パネル)
backdropClick	パネル	(パネル)	パネルの背景がクリックされたときにイベントがトリガーされます。イベントハンドラーは引数としてパネルインスタンスを受け取ります。
panelBackdropClick	アプリ	(パネル)
swipeOpen	パネル	(パネル)	スワイプでパネルを開き始めたときにイベントがトリガーされます。イベントハンドラーは引数としてパネルインスタンスを受け取ります。
panelSwipeOpen	アプリ	(パネル)
swipe	パネル	(panel, progress)	タッチスワイプ操作中にスワイプパネルに対してイベントがトリガーされます。イベントハンドラーは引数としてパネルインスタンスと開いた進捗状況（0から1）を受け取ります。
panelSwipe	アプリ	(panel, progress)
collapsedBreakpoint	パネル	(パネル)	アプリの幅が`collapsedBreakpoint`に一致したときに、表示/非表示になったときにイベントがトリガーされます。イベントハンドラーは引数としてパネルインスタンスを受け取ります。
panelCollapsedBreakpoint	アプリ	(パネル)
breakpoint	パネル	(パネル)	アプリの幅が`visibleBreakpoint`に一致したときに、表示/非表示になったときにイベントがトリガーされます。イベントハンドラーは引数としてパネルインスタンスを受け取ります。
panelBreakpoint	アプリ	(パネル)
resize	パネル	(panel, newPanelWidth)	サイズ変更可能なパネルのサイズ変更時にトリガーされるイベント
panelResize	アプリ	(パネル)	サイズ変更可能なパネルのサイズ変更時にトリガーされるイベント
beforeDestroy	パネル	(パネル)	パネルインスタンスが破棄される直前にトリガーされるイベント
panelBeforeDestroy	アプリ	(パネル)	パネルインスタンスが破棄される直前にトリガーされるイベント

パネルの自動初期化

パネルAPIを使用する必要がなく、パネルが初期化時またはページ内のアプリ内にあり、ページ初期化の瞬間にDOMに表示されている場合は、追加のpanel-initクラスを追加するだけで自動的に初期化できます。

<!-- Add panel-init class -->
<div class="panel panel-left panel-cover panel-init">
  ...
</div>

この場合、作成されたパネルインスタンスにアクセスする必要がある場合は、app.panel.getアプリメソッドを使用できます。

var panel = app.panel.get('.panel-left');

if (panel.opened) {
  // do something
}

自動初期化を使用する場合は、追加のパラメーターを渡す必要がある場合があります。これは、パネル要素のdata-属性を使用して行うことができます。

<!-- parameters set via data- attributes -->
<div
  class="panel panel-left panel-reveal panel-init"
  data-collapsed-breakpoint="768"
  data-visible-breakpoint="1024"
  data-swipe="true"
>
  ...
</div>

キャメルケースで使用されるパラメーター（例：visibleBreakpoint）は、data-属性ではケバブケース（例：data-visible-breakpoint）で使用する必要があります。

リンクによるパネルの制御

リンクの特別なクラスとdata属性を使用して、必要なパネル（DOMにある場合）を開閉できます。

パネルを開くには、任意のHTML要素（リンクが推奨）にpanel-openクラスを追加する必要があります。
パネルを閉じるには、任意のHTML要素（リンクが推奨）にpanel-closeクラスを追加する必要があります。
パネルを切り替えるには、任意のHTML要素（リンクが推奨）にpanel-toggleクラスを追加する必要があります。
どのパネルを開閉するかを指定する場合は、このHTML要素の追加のdata-panel=".panel-left"属性を使用して指定できます。この属性は、DOMにそのような側のパネルが1つしかない場合は、leftまたはrightの値のみを受け取ることもできます。

上記注記による

<body>
  <div id="app">
    <!-- Left Panel with Reveal effect -->
    <div class="panel panel-left panel-reveal panel-init">
      <div class="block">
        ...
        <!-- Clicking on link with "panel-close" class will close panel -->
        <p><a href="#" class="panel-close">Close me</a></p>
        <!-- Click on link with "panel-open" and data-panel=".panel-right" attribute will open Right panel -->
        <p><a href="#" data-panel=".panel-right" class="panel-open">Open Right Panel</a></p>
      </div>
    </div>

    <!-- Right Panel with Cover effect -->
    <div class="panel panel-right panel-cover panel-init">
      <div class="block">
        ...
        <!-- Click on link with "panel-close" class will close panel -->
        <p><a href="#" class="panel-close">Close me</a></p>
        <!-- Click on link with "panel-open" and data-panel=".panel-left" attribute will open Left panel -->
        <p><a href="#" data-panel=".panel-left" class="panel-open">Open Left Panel</a></p>
      </div>
    </div>

    ...
    <div class="page-content">
      <div class="block">
        <!-- Click on link with "panel-open" and data-panel=".panel-left" attribute will open Left panel -->
        <p><a href="#" data-panel=".panel-left" class="panel-open">Open Left Panel</a></p>
        <!-- Click on link with "panel-open" and data-panel=".panel-right" attribute will open Right panel -->
        <p><a href="#" data-panel=".panel-right" class="panel-open">Open Right Panel</a></p>
      </div>
    </div>
  </div>
  ...
</body>

ルーティング可能なパネル

パネルは、ルーティング可能なモーダルやページと同じ機能でルーティングすることもできます。

これにより、いわゆる特別なリンクやAPIではなく、通常のリンクでパネルを開く機会が提供されます。
ブラウザの履歴が有効になっている場合、ブラウザをリフレッシュしたり、履歴を前後に移動したりすると、同じパネルが開きます。
ルーティング可能なパネルを使用すると、url、content、component、またはcomponentUrlを使用して、ページやモーダルと同じ方法でパネル自体とそのコンテンツをロードできます。

routes = [
  ...
  // Creates Panel from passed HTML string
  {
    path: '/left-panel/',
    panel: {
      content: `
        <div class="panel panel-left panel-cover">
          <div class="view">
            <div class="page">
              ...
            </div>
          </div>
        </div>
      `
    }
  },
  // Load Panel from file via Ajax
  {
    path: '/right-panel-ajax/',
    panel: {
      url: './right-panel.html',
      /* right-panel.html contains:
      <div class="panel panel-right panel-reveal">
        <div class="view">
          <div class="page">
            ...
          </div>
        </div>
      </div>
      */
    },
  },
  // Load Panel from component file
  {
    path: '/panel-component/',
    panel: {
      componentUrl: './panel-component.html',
      /* panel-component.html contains:
      <template>
        <div class="panel panel-left panel-cover">
          <div class="view">
            <div class="page">
              ...
            </div>
          </div>
        </div>
      </template>
      <style>...</style>
      <script>...</script>
      */
    },
  },
]

上記の例による

/left-panel/ href属性を持つリンクをクリックすると、指定された文字列コンテンツからパネルが開きます。
/right-panel-ajax/ href属性を持つリンクをクリックすると、right-panel.htmlファイルへのAjaxリクエストが実行され、右パネルとして開きます。
/panel-component/ href属性を持つリンクをクリックすると、panel-component.htmlファイルへのAjaxリクエストが実行され、ルーターコンポーネントとして解析され、パネルとして開きます。

ネストされたパネル

メインアプリパネルに加えて、ページ内などネストされたパネルを持つことも可能です。パネルをネストするには、親コンテナ（例：ページ要素）を指すcontainerElパラメーターを指定し、page-content要素の前に配置する必要があります。

<div class="page" id="panel-page">
  <div class="navbar">
    <!-- ... -->
  </div>

  <!-- Nested panel has parent page specified in containerEl parameter -->
  <div class="panel panel-left panel-cover panel-init dark" id="panel-nested" data-container-el="#panel-page">
    <div class="page">
      <!-- ... -->
    </div>
  </div>

  <!-- Rest of the page -->
  <div class="page-content">
    <!-- ... -->
  </div>
</div>

CSS変数

以下は、関連するCSS変数（CSSカスタムプロパティ）のリストです。

コメント付きの変数はデフォルトで指定されておらず、その値は、この場合フォールバックする値であることに注意してください。

:root {
  --f7-panel-width: 260px;
  --f7-panel-backdrop-bg-color: rgba(0, 0, 0, 0.3);
  /*
  --f7-panel-left-width: var(--f7-panel-width);
  --f7-panel-right-width: var(--f7-panel-width);
  --f7-panel-left-collapsed-width: var(--f7-panel-collapsed-width);
  --f7-panel-right-collapsed-width: var(--f7-panel-collapsed-width);
  */
  --f7-panel-bg-color: #fff;
}
:root .dark,
:root.dark {
  --f7-panel-bg-color: #000;
}
.ios {
  --f7-panel-collapsed-width: 58px;
  --f7-panel-transition-duration: 400ms;
  --f7-panel-transition-timing-function: initial;
}
.md {
  --f7-panel-collapsed-width: 60px;
  --f7-panel-transition-duration: 400ms;
  --f7-panel-transition-timing-function: cubic-bezier(0, 0.8, 0.34, 1);
}

例

panel.html

<div class="page" id="panel-page">
  <div class="navbar">
    <div class="navbar-bg"></div>
    <div class="navbar-inner sliding">
      <div class="title">Panel / Side panels</div>
    </div>
  </div>
  <div class="panel panel-left panel-cover panel-init" id="panel-nested" data-container-el="#panel-page">
    <div class="page">
      <div class="page-content">
        <div class="block block-strong-ios block-outline-ios">
          <p>This is page-nested Panel.</p>
          <p><a class="panel-close">Close me</a></p>
        </div>
      </div>
    </div>
  </div>

  <div class="page-content">
    <div class="block block-strong-ios block-outline-ios">
      <p>Framework7 comes with 2 panels (on left and on right), both are optional.
        You can put absolutely anything inside: data lists, forms, custom content, and even other isolated app view
        (like in right panel now) with its own dynamic navbar.</p>
    </div>
    <div class="block block-strong-ios block-outline-ios">
      <p class="grid grid-cols-2 grid-gap">
        <a class="button button-raised button-fill panel-open">Open left panel</a>
        <a class="button button-raised button-fill panel-open" data-panel="right">Open right panel</a>
      </p>
      <p>
        <a class="button button-raised button-fill panel-open" data-panel="#panel-nested">Open nested panel</a>
      </p>
    </div>
  </div>
</div>

このドキュメントを改善する

このページについて

パネルレイアウト
パネルアプリメソッド
パネルパラメーター
パネルメソッドとプロパティ
パネルイベント

DOMイベント
アプリとパネルインスタンスイベント

パネルの自動初期化
リンクによるパネルの制御
ルーティング可能なパネル
ネストされたパネル
CSS変数
例