PWA のタイトルバーのウィンドウ コントロール オーバーレイをカスタマイズする

ウィンドウ コントロールの横にあるタイトルバー領域を使用して、PWA をアプリに近いものにすることができます。

Amanda Baker

Thomas Steiner

PWA をアプリに近いものにするという記事を覚えているかもしれません。 アプリのタイトルバーをカスタマイズする方法を アプリライクなエクスペリエンスを創出するための 戦略について説明しますこれはサンプル画像です macOS Podcasts アプリが表示されています

<ph type="x-smartling-placeholder">

</ph> <ph type="x-smartling-placeholder">

</ph> カスタム タイトルバーを使用すると、PWA をプラットフォーム固有のアプリであるかのように感じられます。

をご覧ください。

ここで、ポッドキャストはプラットフォーム固有の macOS アプリであり、 ブラウザでは実行されないため、ブラウザのデバイスで再生することなく、 できます。そのとおりですが、幸いなことに、ウィンドウ コントロール オーバーレイ機能は それでは、PWA に同様のユーザー インターフェースを作成しましょう。

Window Controls Overlay コンポーネント

ウィンドウ コントロール オーバーレイは、次の 4 つのサブ機能で構成されています。

1. "display_override" フィールドの "window-controls-overlay" 値: 使用します。
2. CSS 環境変数 titlebar-area-x、titlebar-area-y、titlebar-area-width、 titlebar-area-height。
3. これまで独自の CSS プロパティ -webkit-app-region を app-region プロパティを使用して、ウェブ コンテンツ内のドラッグ可能な領域を定義します。
4. ウィンドウ制御領域を照会して回避するメカニズムは、 window.navigator の windowControlsOverlay 人のメンバー。

ウィンドウ コントロール オーバーレイとは

タイトルバー領域とは、ウィンドウ コントロール（つまり、 最小化、最大化、閉じるなどのボタンなど）が含まれ、多くの場合、アプリのタイトルが含まれています。ウィンドウ コントロール オーバーレイを使用すると、プログレッシブ ウェブ アプリケーション（PWA）を切り替えて、アプリのように感じられる ウィンドウ コントロールを含む小さなオーバーレイ用の既存の全幅タイトルバー。これにより、 デベロッパーは、これまでブラウザで制御されていたタイトルバー領域にカスタム コンテンツを配置できるようになりました。

現在のステータス

ステップ	ステータス
1. 説明を作成	完了
2. 仕様の初期ドラフトを作成する	完了
3. フィードバックの収集と設計の反復処理	作成中
4. オリジン トライアル	完了
5. リリース	完了（Chromium 104）

ウィンドウ コントロール オーバーレイの使用方法

ウェブアプリ マニフェストへの window-controls-overlay の追加

プログレッシブ ウェブアプリでウィンドウ コントロール オーバーレイを有効にするには、 ウェブアプリ マニフェストで、"window-controls-overlay" を "display_override" のプライマリ メンバーとして設定します。

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

ウィンドウ コントロール オーバーレイは、次のすべての条件が満たされた場合にのみ表示されます。

1. アプリはブラウザではなく、別の PWA ウィンドウで開かれます。
2. マニフェストには "display_override": ["window-controls-overlay"] が含まれています。（その他の値は、 なります。）
3. PWA がデスクトップ オペレーティング システムで実行されている。
4. 現在のオリジンは、PWA がインストールされているオリジンと一致します。

その結果、タイトルバーの領域が空白になり、通常のウィンドウ コントロールが左側、または オペレーティングシステムに応じて 選択できます

<ph type="x-smartling-placeholder">

</ph> <ph type="x-smartling-placeholder">

</ph> カスタム コンテンツを表示する空のタイトルバー。

コンテンツをタイトルバーに移動する

タイトルバーにスペースができたので、ここにアイテムを移動できます。この記事では、 Wikimedia 注目のコンテンツ PWA を作成しました。このアプリの便利な機能として、 特定します。検索機能の HTML は次のようになります。

<div class="search">
  <img src="logo.svg" alt="Wikimedia logo." width="32" height="32" />
  <label>
    <input type="search" />
    Search for words in articles
  </label>
</div>

この div をタイトルバーの上に移動するには、いくつかの CSS が必要です。

.search {
  /* Make sure the `div` stays there, even when scrolling. */
  position: fixed;
  /**
   * Gradient, because why not. Endless opportunities.
   * The gradient ends in `#36c`, which happens to be the app's
   * `<meta name="theme-color" content="#36c">`.
   */
  background-image: linear-gradient(90deg, #36c, #131313, 33%, #36c);
  /* Use the environment variable for the left anchoring with a fallback. */
  left: env(titlebar-area-x, 0);
  /* Use the environment variable for the top anchoring with a fallback. */
  top: env(titlebar-area-y, 0);
  /* Use the environment variable for setting the width with a fallback. */
  width: env(titlebar-area-width, 100%);
  /* Use the environment variable for setting the height with a fallback. */
  height: env(titlebar-area-height, 33px);
}

以下のスクリーンショットでこのコードの効果を確認できます。タイトルバーは完全にレスポンシブです。日時 PWA ウィンドウのサイズを変更すると、タイトルバーが通常の HTML コンテンツで構成されているかのように反応します。 実際のところです

<ph type="x-smartling-placeholder">

</ph> <ph type="x-smartling-placeholder">

</ph> 新しいタイトルバーはアクティブでレスポンシブです。

タイトルバーのドラッグ可能な部分を特定する

上のスクリーンショットは完了したように見えますが、まだ完了していません。PWA ウィンドウは ウィンドウ コントロールのボタンはドラッグされなくなったため、（非常に小さな領域から離れて）ドラッグできなくなった タイトルバーの残りの部分は検索ウィジェットで構成されています。これを修正するには 値を drag に設定した app-region CSS プロパティ具体的なケースでは、 input 要素以外のすべての要素がドラッグ可能になっています。

/* The entire search `div` is draggable… */
.search {
  -webkit-app-region: drag;
  app-region: drag;
}

/* …except for the `input`. */
input {
  -webkit-app-region: no-drag;
  app-region: no-drag;
}

注: 現時点では app-region は標準化されていないため、app-region が標準化されるまで接頭辞 -webkit-app-region を引き続き使用する予定です。現在、ブラウザでサポートされているのは -webkit-app-region のみです。

この CSS を配置したら、ユーザーは div、img、 または label。input 要素のみがインタラクティブであるため、検索クエリを入力できます。

機能検出

ウィンドウ コントロール オーバーレイのサポートは、 windowControlsOverlay:

if ('windowControlsOverlay' in navigator) {
  // Window Controls Overlay is supported.
}

windowControlsOverlay でウィンドウ コントロール リージョンをクエリする

ここまでのコードには問題が 1 つあります。プラットフォームによっては、ウィンドウ コントロールが右側、 その他は左側に表示されます。さらに厄介なことに、「3 つの点」はChrome メニューの変更 プラットフォームに応じてつまり、線形グラデーションの背景画像には、 #131313→maroon または maroon→#131313→maroon の順に実行するように動的に適応させて、 タイトルバーの maroon の背景色に溶け込ませます。背景色は <meta name="theme-color" content="maroon">。そのためには、まず BigQuery に navigator.windowControlsOverlay プロパティの getTitlebarAreaRect() API。

if ('windowControlsOverlay' in navigator) {
  const { x } = navigator.windowControlsOverlay.getTitlebarAreaRect();
  // Window controls are on the right (like on Windows).
  // Chrome menu is left of the window controls.
  // [ windowControlsOverlay___________________ […] [_] [■] [X] ]
  if (x === 0) {
    div.classList.add('search-controls-right');
  }
  // Window controls are on the left (like on macOS).
  // Chrome menu is right of the window controls overlay.
  // [ [X] [_] [■] ___________________windowControlsOverlay [⋮] ]
  else {
    div.classList.add('search-controls-left');
  }
} else {
  // When running in a non-supporting browser tab.
  div.classList.add('search-controls-right');
}

前のように、背景画像を .search クラスの CSS ルールで直接指定するのではなく、 変更したコードでは、上記のコードが動的に設定する 2 つのクラスを使用するようになりました。

/* For macOS: */
.search-controls-left {
  background-image: linear-gradient(90deg, #36c, 45%, #131313, 90%, #36c);
}

/* For Windows: */
.search-controls-right {
  background-image: linear-gradient(90deg, #36c, #131313, 33%, #36c);
}

ウィンドウ コントロール オーバーレイを表示するかどうかの確認

ウィンドウ コントロール オーバーレイは、どのような状況でもタイトルバー領域に表示されない場合があります。この間、 ウィンドウ コントロール オーバーレイ機能をサポートしていないブラウザには、当然ながら存在しません。 また、該当する PWA がタブで実行されているときには表示されません。この状況を検出するには windowControlsOverlay の visible プロパティに対してクエリを実行します。

if (navigator.windowControlsOverlay.visible) {
  // The window controls overlay is visible in the title bar area.
}

注: ウィンドウ コントロール オーバーレイの可視性は、ウィンドウ コントロール オーバーレイの横に配置する HTML コンテンツの CSS における可視性と混同しないでください。ウィンドウ コントロール オーバーレイに配置された div に display: none を設定しても、ウィンドウ コントロール オーバーレイの visible プロパティは true を報告します。

または、JavaScript や CSS で display-mode メディアクエリを使用することもできます。

// Create the query list.
const mediaQueryList = window.matchMedia('(display-mode: window-controls-overlay)');

// Define a callback function for the event listener.
function handleDisplayModeChange(mql) {
  // React on display mode changes.
}

// Run the display mode change handler once.
handleDisplayChange(mediaQueryList);

// Add the callback function as a listener to the query list.
mediaQueryList.addEventListener('change', handleDisplayModeChange);

@media (display-mode: window-controls-overlay) { 
  /* React on display mode changes. */ 
}

ジオメトリの変更の通知

getTitlebarAreaRect() を使用してウィンドウ コントロールのオーバーレイ領域をクエリすると、1 回限りのクエリで十分である ウィンドウ コントロールの位置に基づいて適切な背景画像を設定するなど、 よりきめ細かい制御が必要になります。ユースケースとしては、たとえば ウィンドウ コントロール オーバーレイを使用可能なスペースに合わせて調整し、ウィンドウに直接ジョークを追加します。 コントロール オーバーレイを表示することもできます。

<ph type="x-smartling-placeholder">

</ph> <ph type="x-smartling-placeholder">

</ph> 幅の狭いウィンドウに合わせて調整されたタイトルバー コントロール。

登録すると、ジオメトリの変更に関する通知を受け取ることができます。 navigator.windowControlsOverlay.ongeometrychange を使用するか、サービスのイベント リスナーをセットアップして、 geometrychange イベント。このイベントは、ウィンドウ コントロール オーバーレイが表示され、 navigator.windowControlsOverlay.visible が true の場合です。

注: このイベントは頻繁に発生するため（スクロール リスナーの起動に匹敵する）、イベントが頻繁に発生しすぎないようにデバウンス関数を使用することをおすすめします。

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.ongeometrychange = debounce((e) => {
    span.hidden = e.titlebarAreaRect.width < 800;
  }, 250);
}

関数を ongeometrychange に割り当てる代わりに、イベント リスナーを windowControlsOverlay を以下のように指定します。この 2 つの違いについては、 MDN。

navigator.windowControlsOverlay.addEventListener(
  'geometrychange',
  debounce((e) => {
    span.hidden = e.titlebarAreaRect.width < 800;
  }, 250),
);

タブ内および非対応ブラウザで実行する場合の互換性

次の 2 つのケースが考えられます。

• ウィンドウ コントロール オーバーレイをサポートしているブラウザでアプリが実行されているものの、 ブラウザタブでアプリが使用されている場合
• ウィンドウ コントロール オーバーレイをサポートしていないブラウザでアプリが実行されている場合。

どちらの場合も、デフォルトでウィンドウ コントロール用に作成された HTML オーバーレイは通常の HTML コンテンツと同様にインライン表示され、env() 変数のフォールバック値 ポジショニングを開始しますサポートされているブラウザでは、 ウィンドウ コントロール オーバーレイ用に指定された HTML。オーバーレイの visible プロパティをチェックして、 false をレポートし、その HTML コンテンツを非表示にします。

<ph type="x-smartling-placeholder">

</ph> <ph type="x-smartling-placeholder">

</ph> 古いブラウザでは、タイトルバー用のコントロールを本文に簡単に表示できます。

なお、対応していないブラウザでは、 "display_override" ウェブアプリ マニフェスト プロパティがまったくないか、 "window-controls-overlay" になるため、フォールバック チェーンに従って次の可能な値が使用されます。 例: "standalone"

<ph type="x-smartling-placeholder">

</ph> <ph type="x-smartling-placeholder">

</ph> 古いブラウザでは、タイトルバー用のコントロールを本文に簡単に表示できます。

UI に関する考慮事項

[Window Controls Overlay] 領域でクラシック プルダウン メニューを作成しないでほしいのですが、おすすめしません。使用すると、 macOS の設計ガイドライン ユーザーがメニューバーを期待するプラットフォーム（システム提供のものも、 カスタム絵文字など）が表示されます。

注: Electron.js アプリで使用できる Menu のような適切な App Menu API があることは、crbug/1295253 として追跡されます。

アプリが全画面エクスペリエンスを提供する場合は、全画面モードにする意味があるかどうかを慎重に検討してください ウィンドウ コントロール オーバーレイを全画面表示にします。たとえば、 配置を変更する必要がある場合は、 onfullscreenchange イベントが発生します。

デモ

デモを作成しました。 異なるサポート ブラウザと非サポート ブラウザ、およびインストール済み状態と未インストール状態を比較できます。対象 ウィンドウ コントロール オーバーレイを実際に体験するには、アプリをインストールする必要があります。実際の動作を示す 2 つのスクリーンショットを以下に示します。「 アプリのソースコードは Glitch で入手できます。

<ph type="x-smartling-placeholder">

</ph> <ph type="x-smartling-placeholder">

</ph> デモアプリはテストに利用できます。

ウィンドウ コントロール オーバーレイの検索機能は、すべて使用できます。

<ph type="x-smartling-placeholder">

</ph> <ph type="x-smartling-placeholder">

</ph> ウィンドウ コントロール オーバーレイを使用した検索機能。

セキュリティ上の考慮事項

Chromium チームは、基本原則に基づいて Window Controls Overlay API を設計、実装しました 強力なウェブ プラットフォーム機能へのアクセスの制御で定義されている 制御、透明性、エルゴノミクスの点で優れています。

なりすまし

サイトにタイトルバーを部分的に制御できるようにすることで、デベロッパーがコンテンツを偽装できる余地が生まれる ブラウザによって制御される信頼できる地域でした。現在、Chromium ブラウザでは、スタンドアロン 初期起動時に左側にウェブページのタイトルを表示するタイトルバーと、 右側のページのオリジン（[設定など] ボタンとウィンドウが続く） 設定されます。数秒後、元のテキストが消えます。ブラウザが右から左に設定されている場合 （RTL）言語を使用している場合、元のテキストが左側になるようにこのレイアウトが反転しています。すると 起点との間に十分なパディングがない場合に、起点を偽装するためにウィンドウ コントロールがオーバーレイされる オーバーレイの右端を追加します。たとえば、オリジン「evil.ltd」は信頼できる ID のタグを追加して 「google.com」というサイトで、ユーザーは信頼できる情報源と見なすように誘導しています。今後も引き続き オリジン テキストを追加して、アプリのオリジンをユーザーが把握し、 あります。RTL 設定ブラウザでは、オリジンの右側に十分なパディングが必要です テキストを追加して、悪意のあるウェブサイトが安全でないオリジンが信頼できるオリジンに追加されないようにします。

フィンガープリント

ウィンドウ コントロール オーバーレイを有効にしてもドラッグ可能な領域が配置されない プライバシーに関するかなりの懸念がありますしかし、 ウィンドウ コントロール ボタンのサイズや位置が、 システム、 navigator.windowControlsOverlay.getTitlebarAreaRect() メソッドが DOMRect を返す その位置とディメンションによって、オペレーティング システムに関する情報が 関連付けられます。現在、開発者はすでに OS を ユーザー エージェント文字列から取得されますが、フィンガープリントの問題により、 UA 文字列の凍結と OS バージョンの統合に関するディスカッションです。こちらの ブラウザ コミュニティ内での継続的な取り組みを通じて、 ウィンドウ コントロールのサイズは、プラットフォームによって どの OS バージョンでもかなり安定しているため、 OS のマイナー バージョンを監視する場合に便利です。これは潜在的な フィンガープリントの問題が発生します。これは、カスタム イメージを使用するインストール済みの PWA にのみ適用されます。 タイトルバー機能であり、一般的なブラウザの使用には適用されません。また、 navigator.windowControlsOverlay API を使用できなくなります PWA 内に埋め込まれます。

ナビゲーション

PWA 内で別のオリジンに移動すると、通常のスタンドアロンにフォールバックする タイトルバーが上記の基準を満たし、ウィンドウ コントロール オーバーレイとともに起動されている場合も含む。 これは、別のオリジンへのナビゲーション時に黒いバーが表示されるようにするためです。変更後 元の原点に戻ると、ウィンドウ コントロール オーバーレイが再び使用されます。

<ph type="x-smartling-placeholder">

</ph> <ph type="x-smartling-placeholder">

</ph> ユーザーが別のオリジンに移動すると、黒いバーが表示されます。

フィードバック

Chromium チームに、Window Controls Overlay API の感想をお聞かせください。

API 設計について教えてください

API で想定どおりに機能していないものはありますか？あるいは不足しているメソッドがあるか アイデアを実現するために必要なものやプロパティは？セキュリティに関する質問またはコメント どうすればよいでしょうか。対応する GitHub リポジトリで仕様に関する問題を報告するか、 解決します

実装に関する問題を報告する

Chromium の実装にバグは見つかりましたか？または、実装が仕様と異なっていますか？ new.crbug.com でバグを報告します。できるだけ詳細に説明してください [Components] セクションで [UI>Browser>WebAppInstalls] を入力します。 のボックスを選択します。Glitch は、すばやく簡単に再現を共有するのに最適です。

API のサポートを表示する

Window Controls Overlay API を使用する予定はありますか？皆様の公開サポートが Chromium チームの力になります 他のブラウザ ベンダーがそれらの機能をサポートすることの重要性を説明します。

@ChromiumDev に #WindowControlsOverlay 使用する場所と方法をお知らせください。

関連情報

• 説明
• 仕様ドラフト
• Chromium のバグ
• Chrome プラットフォームのステータスのエントリ
• TAG の審査
• Microsoft Edge の関連ドキュメント

謝辞

ウィンドウ コントロール オーバーレイは、 Microsoft Edge チームの Amanda Baker この記事は Joe Medley によってレビューされ、 Kenneth Rohde Christiansen。ヒーロー画像: Sigmund、Unsplash より