ポップオーバー

Popoverコンポーネントは、ポップオーバー内のコンテンツの表示を管理するために使用されます。ポップオーバーは、情報を一時的に表示するために使用します。ポップオーバーは、ユーザーがポップオーバーウィンドウの外をタップするか、明示的にポップオーバーを解除するまで表示されます。

なお、小さな画面（iPhone）でのポップオーバーの使用は推奨されません。小さな画面では、アクションシートを使用してください。

ポップオーバーのレイアウト

まず、ポップオーバーのレイアウトを見てみましょう。それはとてもシンプルです。

<body>
    ...
    <div class="popover">
        <!-- ポップオーバーの角度の矢印 -->
        <div class="popover-angle"></div>

        <!-- ポップオーバーのコンテンツ -->
        <div class="popover-inner">
            <!-- 任意のHTMLコンテンツ -->
        </div>
    </div>
</body>

ポップオーバーは非常にカスタマイズしやすい要素で、中に何かを入れたり、ナビゲーション付きの別のビューをイベントとして表示したりすることができます。

Popoverアプリのメソッド

Popoverに関連するアプリのメソッドを見てみましょう。

app.popover.create(parameters)- Popoverインスタンスの作成

parameters - object. ポップオーバーのパラメータを持つオブジェクト

作成されたPopoverのインスタンスを返すメソッド

app.popover.destroy(el)- Popoverのインスタンスを破棄する

el - HTMLElement または string (CSSセレクタ付き) または object. 破棄するPopover要素またはPopoverインスタンスです。

app.popover.get(el)- HTML要素によるポップオーバーインスタンスの取得

el - HTMLElement または string (CSS Selectorを使用). Popoverの要素です。

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

app.popover.open(el, targetEl, animate)- ポップオーバーを開く

el - HTMLElement または string (with CSS Selector). 開くポップオーバーの要素
targetEl - HTMLElementまたはstring(CSSセレクタを使用)。ポップオーバーの位置を設定する対象となる要素
animate - boolean。ポップオーバーをアニメーションで開きます。

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

app.popover.close(el, animate)- ポップオーバーを閉じる

el - HTMLElement または string (CSS Selectorを使用). ポップオーバーの要素を閉じます。
animate - boolean。アニメーションでPopoverを閉じます。

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

ポップオーバーのパラメータ

それでは、Popoverを作成するために必要なパラメータの一覧を見てみましょう。

Parameter	Type	Default	Description
el	HTMLElement		Popover要素。HTML にすでに Popover 要素があり、この要素を使用して新しいインスタンスを作成したい場合に便利です。
content	string		Full Popover HTML layout string. Popover要素を動的に作成したい場合に便利です。
backdrop	boolean	true	ポップオーバーの背景を有効にする (背後にある暗い半透明のレイヤー)
backdropEl	HTMLElement string		HTML 要素または文字列カスタム背景要素の CSS セレクタ
closeByBackdropClick	boolean	true	有効にすると、ポップオーバーは背景のクリックで閉じられます。
closeByOutsideClick	boolean	true	有効にすると、ポップオーバーはその外側をクリックすると閉じられます。
closeOnEscape	boolean	false	有効にすると、ESCキーを押したときにポップオーバーが閉じます。
animate	boolean	true	ポップオーバーの開閉をアニメーションで行うかどうか。.open()`と`.close()`メソッドで上書きすることができます。
targetEl	HTMLElement string		対象となる要素の HTML 要素または文字列 CSS セレクタ
targetX	number		画面の左端からの仮想ターゲット要素の水平方向のオフセットを指定します。実際のターゲット要素(`targetEl`)を使用しない場合は必須です。
targetY	number		仮想目標要素の画面上端からの垂直方向のオフセットを表す。実際のターゲット要素(`targetEl`)を使用しない場合は必要です。
targetWidth	number	0	仮想ターゲット要素の幅 (px単位) リアルターゲット要素を使用しない場合は必須 (`targetEl`)
targetHeight	number	0	仮想ターゲット要素の高さ (px単位) 実際のターゲット要素(`targetEl`)を使用しない場合は必須です。
on	object		イベントハンドラーを持つオブジェクトです。例えば、以下のようになります。 `var popover = app.popover.create({ content: '<div class="popover">...</div>', on: { opened: function () { console.log('Popover opened') } } })`

以下のすべてのパラメータは、アプリのグローバルパラメータの popover プロパティで使用することができ、すべてのポップオーバーのデフォルトを設定することができます。例えば、以下のようなものがあります。

var app = new Framework7({
  popover: {
    closeByBackdropClick: false,
  }
});

自動初期化されたポップオーバーを使用する場合（例：app.popover.create で作成しない場合）、利用可能なすべてのポップオーバーのパラメータを data- 属性で渡すことができます。たとえば、次のようになります。

<!-- パラメータを kebab-case の data 属性として渡す -->
<div class="popover" data-close-on-escape="true" data-backdrop="false">
  ...
</div>

ポップオーバーのメソッドとプロパティ

ポップオーバーを作成するためには、以下のメソッドを呼び出す必要があります。

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

その後、便利なメソッドとプロパティを持つ初期化されたインスタンス（上記の例では popover という変数）が作成されます。

Properties
popover.app	グローバルアプリのインスタンスへのリンク
popover.el	ポップオーバー HTML 要素
popover.$el	POPOVER HTML要素を持つDom7インスタンス
popover.backdropEl	背景のHTML要素
popover.$backdropEl	背景のHTML要素を持つDom7のインスタンス
popover.targetEl	ポップオーバーターゲットHTML要素
popover.$targetEl	ポップオーバーのターゲットとなる HTML 要素を持つ Dom7 インスタンス
popover.params	ポップオーバーのパラメータ
popover.opened	ポップオーバーを開くかどうかを示すブール値のプロップ
Methods
popover.open(targetEl, animate)	ポップオーバーをターゲット要素の周りに開きます。対象要素 targetEl - HTMLElement or string - ポップオーバーの位置を設定する対象となる要素。 animate - boolean（デフォルトは`true`） - アニメーションで開くかどうかを定義します。
popover.open(animate)	ポップオーバー作成時に渡されたターゲット要素の周りにポップオーバーを開きます。ここでは animate - boolean (デフォルトでは `true`) - アニメーションを使って開くかどうかを定義します。
popover.close(animate)	ポップオーバーを閉じます。ポップオーバーを閉じる animate - boolean (デフォルトでは `true`) - アニメーションで閉じるかどうかを定義します。
popover.destroy()	ポップオーバーの破棄
popover.on(event, handler)	イベントハンドラの追加
popover.once(event, handler)	イベントハンドラーを追加します。追加したイベントハンドラーは起動後に削除されます。
popover.off(event, handler)	イベントハンドラの削除
popover.off(event)	指定されたイベントのハンドラをすべて削除します
popover.emit(event, ...args)	インスタンスでイベントを発生させる

リンクによるポップオーバーの制御

リンクの特別なクラスやデータ属性を使って、必要なポップオーバー（DOMにある場合）を開いたり閉じたりすることができます。

ポップオーバーを開くには、"popover-open" クラスを任意の HTML 要素に追加する必要があります (リンクが望ましい)。
ポップオーバーを閉じるには、"popover-close"クラスを任意の HTML 要素 (preferred to link) に追加する必要があります。
DOM に複数のポップオーバーがある場合は、この HTML 要素に data-popover=".my-popover" 属性を追加して、適切なポップオーバーを指定する必要があります。

上記のメモによると

<!-- data-popover 属性では、開く必要のあるポップオーバーの CSS セレクタを指定します。 -->
<p><a href="#" data-popover=".my-popover" class="popover-open">Open Popover</a></p>

<!-- また、DOMのどこかに -->
<div class="popover my-popover">
  <div class="popover-inner">
    <!-- ポップオーバーを閉じるためのリンク -->
    <a class="link popover-close">Close Popover</a>
  </div>
</div>

ポップオーバーのイベント

popover は以下の DOM イベントを popover 要素に、イベントをアプリと popover インスタンスに発行します。

DOM イベント

Event	Target	Description
popover:open	Popover Element<div class="popover">	ポップオーバーがオープニングアニメーションを開始すると、イベントが発生します。
popover:opened	Popover Element<div class="popover">	イベントは、ポップオーバーがオープニングアニメーションを完了した後に発生します。
popover:close	Popover Element<div class="popover">	Popover が閉じるアニメーションを開始するとイベントが発生します。
popover:closed	Popover Element<div class="popover">	Popover が閉じるアニメーションを完了すると、イベントが発生します。

アプリと Popover インスタンスのイベント

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

Event	Arguments	Target	Description
open	popover	popover	イベントは Popover がオープニングアニメーションを開始したときにトリガーされます。イベントハンドラは引数として popover インスタンスを受け取ります。
popoverOpen	popover	app
opened	popover	popover	イベントは Popover がそのオープニングアニメーションを完了した後にトリガーされます。As an argument event handler receive popover instance
popoverOpened	popover	app
close	popover	popover	ポップオーバーが閉じるアニメーションを開始するとイベントが発生します。As an argument event handler receive popover instance
popoverClose	popover	app
closed	popover	popover	ポップオーバーが閉じるアニメーションを完了するとイベントが発生します。As an argument event handler receive popover instance
popoverClosed	popover	app
beforeDestroy	popover	popover	イベントは Popover インスタンスが破壊される直前に発生します。As an argument event handler receive popover instance
popoverBeforeDestroy	popover	app

CSS Variables

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

:root {
  --f7-popover-width: 260px;
}
.ios {
  --f7-popover-border-radius: 13px;
  --f7-popover-box-shadow: none;
  --f7-popover-actions-icon-size: 28px;
  --f7-popover-bg-color: rgba(255, 255, 255, 0.95);
  --f7-popover-actions-label-text-color: rgba(0, 0, 0, 0.45);
}
.ios .theme-dark,
.ios.theme-dark {
  --f7-popover-bg-color: rgba(30, 30, 30, 0.95);
  --f7-popover-actions-label-text-color: rgba(255, 255, 255, 0.55);
}
.md {
  --f7-popover-border-radius: 4px;
  --f7-popover-box-shadow: var(--f7-elevation-8);
  --f7-popover-actions-icon-size: 24px;
  --f7-popover-bg-color: #fff;
  --f7-popover-actions-label-text-color: rgba(0, 0, 0, 0.54);
}
.md .theme-dark,
.md.theme-dark {
  --f7-popover-bg-color: #1c1c1d;
  --f7-popover-actions-label-text-color: rgba(255, 255, 255, 0.54);
}
.aurora {
  --f7-popover-border-radius: 8px;
  --f7-popover-box-shadow: var(--f7-elevation-8);
  --f7-popover-actions-icon-size: 24px;
  --f7-popover-bg-color: #fff;
  --f7-popover-actions-label-text-color: rgba(0, 0, 0, 0.6);
}
.aurora .theme-dark,
.aurora.theme-dark {
  --f7-popover-bg-color: #1c1c1d;
  --f7-popover-actions-label-text-color: rgba(255, 255, 255, 0.6);
}

Examples

<template>
  <div class="page">
    <div class="navbar">
      <div class="navbar-bg"></div>
      <div class="navbar-inner">
        <div class="left"><a class="link popover-open" href="#" data-popover=".popover-about">About</a></div>
        <div class="title">Popover</div>
        <div class="right"><a class="link popover-open" href="#" data-popover=".popover-links">Links</a></div>
      </div>
    </div>
    <div class="page-content">
      <div class="block">
        <p><a class="link popover-open" href="#" data-popover=".popover-about">Open About Popover</a></p>
        <p><a class="link popover-open" href="#" data-popover=".popover-links">Open Links Popover</a></p>
      </div>
    </div>

    <div class="popover popover-about">
      <div class="popover-inner">
        <div class="block">
          <p>About</p>
          <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Quisque ac diam ac quam euismod porta vel a
            nunc.
            Quisque sodales scelerisque est, at porta justo cursus ac.</p>
        </div>
      </div>
    </div>
    <div class="popover popover-links">
      <div class="popover-inner">
        <div class="list">
          <ul>
            <li><a class="list-button item-link" href="#">Link 1</a></li>
            <li><a class="list-button item-link" href="#">Link 2</a></li>
            <li><a class="list-button item-link" href="#">Link 3</a></li>
            <li><a class="list-button item-link" href="#">Link 4</a></li>
          </ul>
        </div>
      </div>
    </div>
  </div>
</template>
<style>
  .popover {
    width: 200px;
  }
</style>

<script>
  export default (props, { $, $f7, $on }) => {

    $on('pageInit', () => {
      // DOM events for About popover
      $('.popover-about').on('popover:open', function (e) {
        console.log('About popover open');
      });
      $('.popover-about').on('popover:opened', function (e) {
        console.log('About popover opened');
      });
    })

    return $render;
  }
</script>