Tauri v2에서 Custom Title Bar 만들 때 권한 설정하기

문제 상황

Tauri로 터미널 앱을 만들면서 Custom Title Bar를 구현하려고 tauri.conf.json에서 decorations: false로 설정했습니다.

{
  "title": "penterm-rust",
  "width": 800,
  "height": 600,
  "decorations": false,
  "resizable": true,
  "maximizable": true,
  "minimizable": true
}

프론트엔드에서 Tauri의 Window API를 사용해서 최소화, 최대화, 닫기 버튼을 구현했는데, 클릭해도 아무런 동작이 일어나지 않았습니다.

import { getCurrentWindow } from '@tauri-apps/api/window';

const appWindow = getCurrentWindow();
await appWindow.minimize(); // 작동하지 않음
await appWindow.toggleMaximize(); // 작동하지 않음
await appWindow.close(); // 작동하지 않음

원인

Tauri v2부터는 보안을 강화하기 위해 Capability 기반 권한 시스템을 도입했습니다.

기본적으로 제공되는 core:default 권한만으로는 window 제어 API를 사용할 수 없고, 각 기능별로 명시적으로 권한을 추가해야 합니다.

해결 방법

src-tauri/capabilities/default.json 파일에 필요한 권한들을 추가합니다.

{
  "$schema": "../gen/schemas/desktop-schema.json",
  "identifier": "default",
  "description": "Capability for the main window",
  "windows": ["main"],
  "permissions": [
    "core:default",
    "core:window:allow-minimize",
    "core:window:allow-toggle-maximize",
    "core:window:allow-close",
    "core:window:allow-is-maximized",
    "opener:default"
  ]
}

주요 권한 설명

• core:window:allow-minimize: 창 최소화 허용
• core:window:allow-toggle-maximize: 창 최대화/복원 허용
• core:window:allow-close: 창 닫기 허용
• core:window:allow-is-maximized: 최대화 상태 확인 허용

권한을 추가한 후 다시 빌드하면 정상적으로 동작합니다.

참고사항

Tauri v2의 권한 시스템은 보안을 위해 기본적으로 최소 권한만 부여합니다.

필요한 API를 사용하기 전에 src-tauri/gen/schemas/ 디렉토리의 스키마 파일을 확인하거나, 공식 문서에서 필요한 권한을 찾아서 추가해야 합니다.

Custom Title Bar를 구현할 때는 window 제어 관련 권한들을 미리 추가하는 것을 권장합니다.