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

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

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

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

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

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

予約済みのタイトルバー領域の下にアプリコンテンツが表示されていることを示している Windows の PWA アプリ

タイトルバーが通常配置されている場所にコンテンツを表示することで、PWA がよりネイティブに感じられるようになります。 Visual Studio Code、Microsoft Teams、Microsoft Edge などの多くのデスクトップアプリケーションでは、既にこれが行われています。

Visual Studio Code は、タイトルバー領域にコンテンツを表示します

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

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

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

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 番目のパラメーターを受け取ります。

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

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

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%);
  app-region: drag;
}

オーバーレイの変更にReact

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

変更をリッスンするには、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 デモアプリです。

Microsoft Edge で、新しいウィンドウまたはタブで 1DIV デモアプリを開きます。
アドレスバーで、[ 利用可能なアプリ] をクリックします。1DIV をインストールします (" ボタンをクリックします。「 1DIVアプリのインストール」 ダイアログが開きます。
[ インストール] ボタンをクリックします。 1DIVアプリが独自のウィンドウで開き、 アプリがインストール済み のダイアログが開きます。

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

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

アイコン	ヒント
	設定など
	Minimize
	復元
	Close

アプリは、タイトルバーがあるとされたウィンドウフレームの最上部までコンテンツを表示するようになりました。

マップの上部領域は、ウィンドウの移動に使用できます

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

このデモアプリのソースコードは、 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 をシミュレートする」を参照してください。

フィードバック

このページはお役に立ちましたか?

Last updated on 2026-08-12

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

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

CSS 環境変数を使用して、オーバーレイを避けます

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

オーバーレイの変更にReact

デモ アプリ

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

関連項目