[2026/4/13]

[Tauri #04] Tauri v2 + macOS：透過ウィンドウの白背景とドラッグ移動の不具合を修正

はじめに

前回の記事でGitHub Actionsによる自動ビルド環境を構築しましたが、いざmacOS実機で動かしてみると、そこには「OS固有の仕様」という名の深淵が待っていました。

透過ウィンドウが白背景に塗りつぶされ、それを直せばクリックが効かなくなる……。そんなマルチプラットフォーム開発の地獄を、Tauri v2でどう突破したかの記録です。

前回の記事：

Tauri v2のクロスプラットフォームビルドを自動化するための完全なGitHub Actions設定ファイルと、つまずきやすいエラー（識別子、アイコンパス、Linux依存ライブラリ）の解決策をまとめました。

Tauriの設定で transparent: true にしても、macOSではWebViewの仕様で背景が白く残ることがあります。これを解決するには、Tauri v2の「禁断の隠しオプション」を叩く必要がありました。

v1とは書き方が異なり、app 直下に直接指定するのが正解です。

{
  "app": {
    "macOSPrivateApi": true,
    "windows": [
      {
        "transparent": true,
        "decorations": false
      }
    ]
  }
}

※ macOS の OS が大文字である点に注意。

透過に成功すると、今度は「透明な部分はクリックが下のウィンドウに突き抜ける」というmacOSの仕様にぶつかります。時計を掴んで動かすことができなくなるのです。

これを解決するためにCSSで「ここはドラッグできる領域だ」とOSに教え込みます。

.clock-floating {
  -webkit-app-region: drag; /* OSにドラッグを任せる */
}

ドラッグができるようになると、今度は「OSがマウスイベントを奪い取ってしまい、JavaScriptの右クリックメニュー（contextmenu）が発火しない」という問題が起きます。

解決策は、メニューを出したい要素だけ「ドラッグさせない（イベントをJSに返す）」設定を追加することでした。

#analog-clock {
  -webkit-app-region: no-drag; /* ここだけはJSにイベントを渡す */
  pointer-events: auto;
}

「Webアプリと同じ感覚で書ける」のがTauriの魅力ですが、OSの深い部分（透過やウィンドウ操作）に触れた瞬間、ブラウザという保護膜の外にある「OSごとのわがまま」との戦いが始まります。

大変な道のりでしたが、GitHub ActionsでWindows/Mac両方のビルドが緑色に染まった瞬間、すべてが報われました。