MediaQueryList

MediaQueryList オブジェクトは文書に適用されているメディアクエリーの情報を格納し、文書の状態に対する即時かつイベントドリブンのマッチングに対応します。

MediaQueryListmatchMedia()window オブジェクト上で呼び出すことで作成することができます。結果として得られるオブジェクトは、メディアクエリーの状態が変化したとき (つまり、メディアクエリーのテストが true の評価が開始または停止したとき) に、リスナーへの通知の送信を処理します。

これにより、定期的に値をポーリングするのではなく、文書を監視してメディアクエリーが変更されたときに検出することが可能になり、メディアクエリーの状態に基づいて文書にプログラム的に変更を加えることができるので、アダプティブデザインにとても便利です。

プロパティ

MediaQueryList インターフェイスは親インターフェイスである EventTarget からプロパティを継承しています。

matches読取専用

boolean で、 true であれば document が現在メディアクエリーリストに一致しており、 false であればそうではありません。

media読取専用

文字列で、シリアライズされたメディアクエリーを表します。

メソッド

MediaQueryList インターフェイスは親インターフェイスである EventTarget からメソッドを継承しています。

addListener() (en-US) Deprecated

MediaQueryList にコールバックを追加します。このコールバックは、メディアクエリーの状態 (リスト内のメディアクエリーと文書が一致するかどうか) が変化するたびに呼び出されます。このメソッドは、主に下位互換性のために存在します。可能であれば、代わりに addEventListener()を使用して change イベントを監視してください。

removeListener() (en-US) Deprecated

指定されたリスナーコールバックを、 MediaQueryList でメディアクエリーの状態が変化するたび、すなわち MediaQueryList に列挙されたメディアクエリーの一致・不一致の状態が変化するに呼び出されるコールバックから削除します。このメソッドは下位互換性のために保持されています。可能であれば、一般的に removeEventListener() を使用して、変更通知コールバックを削除してください (以前 addEventListener() を使用して追加されたものです)。

イベント

以下のイベントは MediaQueryList オブジェクトに配信されます。

change

文書に対してメディアクエリーを実行した結果が変更されたときに MediaQueryList に送信されます。例えば、メディアクエリーが (min-width: 400px) の場合、 change イベントが文書のビューポートの幅が 400px の閾値を通過するよう変更されるたびに発行されます。

このシンプルな例では、 MediaQueryList を作成し、メディアクエリーの状態が変化したときにそれを検出するリスナーを設定し、それがページの表示を変更するときにカスタム関数を実行します。

const para = document.querySelector('p');
const mql = window.matchMedia('(max-width: 600px)');

function screenTest(e) {
  if (e.matches) {
    /* the viewport is 600 pixels wide or less */
    para.textContent = 'This is a narrow screen — less than 600px wide.';
    document.body.style.backgroundColor = 'red';
  } else {
    /* the viewport is more than 600 pixels wide */
    para.textContent = 'This is a wide screen — more than 600px wide.';
    document.body.style.backgroundColor = 'blue';
  }
}

mql.addEventListener('change', screenTest);

Note: この例は GitHub にあります (ソースコードを参照、およびライブで実行)。

他の例は個別のプロパティやメソッドのページにあります。

仕様書

Specification
Unknown specification
# the-mediaquerylist-interface

ブラウザーの互換性

BCD tables only load in the browser

関連情報