タイトル バーにコンテンツを表示する
PWA は、Web アプリ マニフェスト ファイルの表示メンバーを使用して、モバイル プラットフォームでの 表示 方法を定義できます。 ただし、イマーシブでネイティブに似たエクスペリエンスを作成するために、 デスクトップ PWA は別の方法を使用できます。
既定では、デスクトップにインストールされている PWA は、予約タイトル バー領域のすぐ下から始まる領域にコンテンツを表示できます。
タイトル バーが通常どおり表示されるコンテンツを表示すると、PWA がよりネイティブに感じるのに役立ちます。 Visual Studio Code、Microsoft Teams、Microsoft Edge などの多くのデスクトップ アプリケーションでは、既に次の操作を行っています。
ウィンドウ コントロール オーバーレイ API では、次の処理が行われます。
- アプリのサーフェス領域全体に Web コンテンツを表示できます。
- 重要なシステムに必要なウィンドウ コントロールをオーバーレイに移動します。
- コンテンツがこのオーバーレイをクリアし続けできるようにします。
アプリでウィンドウ コントロール オーバーレイを有効にする
最初に、アプリの Web アプリ マニフェスト ファイルでウィンドウ コントロール オーバーレイ機能を有効にすることです。 これを行うには、マニフェスト ファイルで プロパティを display_override 設定します。
{
"display_override": ["window-controls-overlay"]
}
タイトル バーを切り替える
ウィンドウ コントロール オーバーレイ機能が有効になっている場合、ユーザーはタイトル バーの切り替えボタンをクリックして、タイトル バーの有無を選択できます。
次の理由から、ウィンドウ コントロールオーバーレイが表示されているとコードで想定することはできません。
- ユーザーは、タイトル バーを表示するかどうかを選択できます。
- アプリは、Web ブラウザーまたはモバイル デバイスで実行したり、デスクトップ アプリとして実行したりすることもできます。
そのため、コードはタイトル バーのジオメトリの変更に対応する必要があります。 詳細については、「変更をオーバーレイするReact」を参照してください。
CSS 環境変数を使用してオーバーレイをクリアする
CSS 関数を env() 使用して、ユーザー エージェントが定義する環境変数にアクセスできます。
ウィンドウ コントロール オーバーレイ機能では、次の 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 ではオーバーレイは右側にあります。 また、オーバーレイが常に同じサイズであるとは限りません。
CSS 関数は env() 、ウィンドウコントロールオーバーレイ機能が見つからないか無効になっているときに、アプリコンテンツの位置を定義するのに役立つ 2 番目のパラメーターを受け取ります。
ウィンドウのアプリドラッグ ハンドラーのリージョンを作成する
タイトル バーが非表示の場合、システム クリティカルなウィンドウ コントロールのみが表示されます ( [最大化]、[ 最小化]、[ 閉じる]、および [アプリ情報 ] アイコン)。 つまり、ユーザーがアプリケーション ウィンドウを移動できる領域は非常に少ないということです。
CSS プロパティを使用すると、 -webkit-app-region ユーザーがアプリをドラッグするためのより多くの方法を提供できます。 たとえば、アプリに独自のタイトル バーがある場合は、そのタイトル バーをウィンドウドラッグ ハンドラーに変換できます。
#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;
}
変更をオーバーレイするReact
ユーザーは、アプリの実行中にタイトル バーを切り替えたり、ウィンドウのサイズを変更したりできます。 これらのことがいつ起こるかを知ることは、アプリにとって重要な場合があります。 アプリでは、タイトル バーに表示されているコンテンツの一部を並べ替えたり、ページの他の場所でレイアウトを並べ替えたりする必要がある場合があります。
変更をリッスンするには、 オブジェクトで geometrychange イベントを navigator.windowControlsOverlay 使用します。 タイトル バーが表示されているかどうかを検出するには、 オブジェクトの visible プロパティを navigator.windowControlsOverlay 使用します。
は、ユーザーがウィンドウの 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 リポジトリにあります。
manifest.json ソース ファイルは、ウィンドウ コントロール オーバーレイ機能のアプリの使用を宣言します。
app.jsソース ファイルでは、 オブジェクトが
navigator.windowControlsOverlay使用されます。app.css ソース ファイルでは、CSS 環境変数が使用されます
titlebar-area-*。