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 권한(core:window:default)은 is-maximized, inner-size 같은 상태 조회 위주예요. 최소화, 최대화, 닫기처럼 창을 바꾸는 명령은 들어 있지 않아서, 기능별로 권한을 직접 추가해야 해요.

해결 방법

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: 최대화 상태 확인 허용 (core:default에 이미 들어 있어서 빼도 돼요)

권한을 추가한 뒤 다시 빌드하니 정상적으로 동작했어요.

참고사항

Tauri v2의 권한 시스템은 기본적으로 최소 권한만 줘요.

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

Custom Title Bar로 창을 끌어서 옮기려면 data-tauri-drag-region을 쓰거나 startDragging()을 호출하는데, 이때는 core:window:allow-start-dragging도 필요해요.