ウィンドウ コントロール オーバーレイを使用してタイトル バー領域にコンテンツを表示する

デスクトップにインストールされているプログレッシブ Web アプリ (PWA) では、ウィンドウ コントロール オーバーレイ API を使用して、タイトル バーが通常どおりであるコンテンツを表示して、PWA をよりネイティブに感じることができます。

ウィンドウ コントロール オーバーレイ API では、次の処理が行われます。

• アプリのサーフェス領域全体に Web コンテンツを表示できます。
• 重要なシステムに必要なウィンドウ コントロールをオーバーレイに移動します。
• コンテンツがこのオーバーレイをクリアし続けできるようにします。

プログレッシブ Web アプリ (PWA) は、Web アプリ マニフェスト ファイルの表示メンバーを使用して、モバイル プラットフォームでの 表示 方法を定義できます。 ただし、イマーシブでネイティブに似たエクスペリエンスを作成するために、 デスクトップ PWA は別の方法を使用できます。

既定では、デスクトップにインストールされている PWA は、予約タイトル バー領域のすぐ下から始まる領域にコンテンツを表示できます。

タイトル バーが通常どおり表示されるコンテンツを表示すると、PWA がよりネイティブに感じるのに役立ちます。 Visual Studio Code、Microsoft Teams、Microsoft Edge などの多くのデスクトップ アプリケーションでは、既に次の操作を行っています。

アプリでウィンドウ コントロール オーバーレイを有効にする

まず、アプリの Web アプリ マニフェスト ファイルでウィンドウ コントロール オーバーレイ機能を有効にします。 これを行うには、マニフェスト ファイルで display_override プロパティを設定します。

{
  "display_override": ["window-controls-overlay"]
}

関連項目:

• MDN でdisplay_override。
• Web アプリ マニフェストを使用して PWA を OS に統合する

タイトル バーを切り替える

ウィンドウ コントロール オーバーレイ機能が有効になっている場合、ユーザーはタイトル バーの切り替えボタンをクリックして、タイトル バーの有無を選択できます。

次の理由から、ウィンドウ コントロールオーバーレイが表示されているとコードで想定することはできません。

• ユーザーは、タイトル バーを表示するかどうかを選択できます。
• アプリは、Web ブラウザーまたはモバイル デバイスで実行したり、デスクトップ アプリとして実行したりすることもできます。

そのため、コードはタイトル バーのジオメトリの変更に対応する必要があります。 詳細については、「 オーバーレイの変更に対応する」を参照してください。

CSS 環境変数を使用してオーバーレイをクリアする

env() CSS 関数を使用して、ユーザー エージェントが定義する環境変数にアクセスできます。

ウィンドウ コントロール オーバーレイ機能では、次の 4 つの環境変数が追加されます。

変数	説明
titlebar-area-x	ウィンドウの左側からタイトル バーが通常占有する領域の px距離
titlebar-area-y	ウィンドウの上部からタイトル バーが通常占有する領域の px距離
titlebar-area-width	タイトル バー領域の幅 px
titlebar-area-height	タイトル バー領域の高さ px

これらの環境変数を使用すると、ウィンドウコントロールオーバーレイ機能が無効になっているときに、タイトルバーが通常表示される場所に独自のコンテンツを配置してサイズを設定できます。

#title-bar {
  position: fixed;
  left: env(titlebar-area-x, 0);
  top: env(titlebar-area-y, 0);
  height: env(titlebar-area-height, 50px);
  width: env(titlebar-area-width, 100%);
}

position: fixed;を使用すると、タイトル バーがコンテンツの残りの部分と共にスクロールされず、代わりにウィンドウ コントロール オーバーレイに合わせて配置されます。

オーバーレイがどこにあり、どの程度大きいかを知ることは重要です。 オーバーレイが常にウィンドウの同じ側にあるとは限りません。macOS の場合、オーバーレイは左側にありますが、Windows ではオーバーレイは右側にあります。 また、オーバーレイが常に同じサイズであるとは限りません。

env() CSS 関数は、ウィンドウコントロールオーバーレイ機能が見つからないか無効になっているときにアプリコンテンツの位置を定義するのに役立つ 2 番目のパラメーターを受け取ります。

領域をウィンドウのドラッグ ハンドルにする

タイトル バーが非表示の場合、システム クリティカルなウィンドウ コントロールのみが表示されます ( [最大化]、[ 最小化]、[ 閉じる]、および [アプリ情報 ] アイコン)。 つまり、ユーザーがアプリケーション ウィンドウを移動できる領域は非常に少ないということです。

-webkit-app-region CSS プロパティを使用すると、ユーザーがアプリをドラッグするためのより多くの方法を提供できます。 たとえば、アプリに独自のタイトル バーがある場合は、そのタイトル バーをウィンドウドラッグ ハンドルに変えることができます。

#title-bar {
  position: fixed;
  left: env(titlebar-area-x, 0);
  top: env(titlebar-area-y, 0);
  height: env(titlebar-area-height, 50px);
  width: env(titlebar-area-width, 100%);
  -webkit-app-region: drag;
}

オーバーレイの変更に対応する

ユーザーは、アプリの実行中にタイトル バーを切り替えたり、ウィンドウのサイズを変更したりできます。 これらのことがいつ起こるかを知ることは、アプリにとって重要な場合があります。 アプリでは、タイトル バーに表示されているコンテンツの一部を並べ替えたり、ページの他の場所でレイアウトを並べ替えたりする必要がある場合があります。

変更をリッスンするには、navigator.windowControlsOverlay オブジェクトで geometrychange イベントを使用します。 タイトル バーが表示されているかどうかを検出するには、navigator.windowControlsOverlay オブジェクトの visible プロパティを使用します。

ユーザーがウィンドウのサイズを変更すると、 geometrychange が非常に頻繁に発生します。 レイアウト変更コードを頻繁に実行し、アプリでパフォーマンスの問題を引き起こさないようにするには、 debounce 関数を使用して、イベントが処理される回数を制限します。 調整とデバウンスの違いを参照してください。

const debounce = (func, wait) => {
  let timeout;
  return function executedFunction(...args) {
    const later = () => {
      clearTimeout(timeout);
      func(...args);
    };
    clearTimeout(timeout);
    timeout = setTimeout(later, wait);
  };
};

if ('windowControlsOverlay' in navigator) {
  navigator.windowControlsOverlay.addEventListener('geometrychange', debounce(e => {
    // Detect if the Window Controls Overlay is visible.
    const isOverlayVisible = navigator.windowControlsOverlay.visible;

    // Get the size and position of the title bar area.
    const titleBarRect = e.titlebarAreaRect;

    console.log(`The overlay is ${isOverlayVisible ? 'visible' : 'hidden'}, the title bar width is ${titleBarRect.width}px`);
  }, 200));
}

デモ アプリ

1DIV は、ウィンドウ コントロール オーバーレイ機能を使用する PWA デモ アプリです。

1. Microsoft Edge で、新しいウィンドウまたはタブで 1DIV デモ アプリを開きます。

2. [アドレス] バーで、[使用可能なアプリ] をクリックします 。1DIV をインストール します () ボタンをインストールします。 [ 1DIV アプリのインストール ] ダイアログが開きます。

3. [ インストール ] ボタンをクリックします。 1DIV アプリが独自のウィンドウで開き、[ アプリがインストールされました ] ダイアログが開きます。

   

4. ダイアログの [閉じる (X)] ボタンをクリックします。 (または、チェック ボックスをオンまたはオフにして、[ 許可 ] ボタンをクリックします)。

   アプリのタイトル バーには、少なくとも次のウィンドウ コントロールが含まれています。

   アイコン	ヒント
   	タイトル バーを非表示にする
   	設定など
   	Minimize
   	復元
   	Close

5. タイトル バーで、[ タイトル バーを非表示にする ] () ボタンをクリックします。

   これで、タイトル バーが表示されたウィンドウ フレームの上部までコンテンツが表示されるようになりました。

   

   アプリの上部の領域は、ユーザーがウィンドウを移動できるようにするためのドラッグ ハンドルです。

このデモ アプリのソース コードは 、1DIV リポジトリにあります。

• manifest.json ソース ファイルは、ウィンドウ コントロール オーバーレイ機能のアプリの使用を宣言します。

• app.js ソース ファイルでは、navigator.windowControlsOverlay オブジェクトが使用されます。

• app.cssソース ファイルでは、titlebar-area-* CSS 環境変数が使用されます。

PWA をインストールせずにカスタム オーバーレイをプレビューする

Microsoft Edge DevTools の アプリケーション ツールでは、最初に PWA をインストールして WCO 機能を有効にすることなく、ウィンドウ コントロール オーバーレイ (WCO) 機能をシミュレートできます。 DevTools 内から WCO 機能をシミュレートすることで、変更された PWA を再インストールするよりも、タイトル バー領域の CSS コードの変更を迅速にテストできます。

シミュレートされたオーバーレイは静的イメージです。 CSS 変数 env(titlebar-area-left)、 env(titlebar-area-top)、 env(titlebar-area-width)、 env(titlebar-area-height) の値は、選択したプラットフォームと一致するように設定されます。

PWA をインストールせずにウィンドウ コントロール オーバーレイ API をシミュレートするを参照してください。

関連項目

• PWA - DevTools 機能をインストールせずに、ウィンドウ コントロール オーバーレイ API をシミュレートします 。
• ウィンドウ コントロール オーバーレイのビデオ チュートリアル
• PWA のタイトル バーのウィンドウ コントロール オーバーレイをカスタマイズする
• 箱から抜け出す
• MDN でdisplay_override。