窗口配置完全指南

窗口配置写在哪

在 Tauri 2，启动窗口的定义放在 tauri.conf.json 的 app.windows 数组里。注意是 app.windows，不是 1.x 的 tauri.windows——这是 2.x 配置重组后统一的位置。每个数组元素是一个窗口对象，应用启动时按数组依次创建；放一个就是单窗口，放多个就是多窗口。

{
  "app": {
    "windows": [
      {
        "label": "main",
        "title": "我的 Tauri 应用"
      }
    ]
  }
}

label 是窗口的「身份证」，在整个应用里必须唯一。后面用 Rust 代码操作窗口、用事件通信，都要靠这个 label 去定位。所以起名要有意义，比如 main、settings、about。

基础尺寸字段

最常用的一组就是标题和初始尺寸：

• title：窗口标题栏显示的文字。
• width / height：初始宽高，单位像素，默认值分别是 800 和 600。
• x / y：窗口左上角在屏幕上的坐标。一般留空或设 null，让系统自动摆放。

{
  "app": {
    "windows": [
      {
        "label": "main",
        "title": "我的 Tauri 应用",
        "width": 1024,
        "height": 768
      }
    ]
  }
}

这组字段决定应用一打开长什么样，是每张配置必写的。

尺寸约束

除了初始大小，你还能给窗口设「活动范围」，防止用户把窗口拉得过小或过大：

• minWidth / minHeight：最小宽高。
• maxWidth / maxHeight：最大宽高。
• 不写或写 null 表示不限制。

{
  "label": "main",
  "width": 1024,
  "height": 768,
  "minWidth": 480,
  "minHeight": 320,
  "maxWidth": 1600,
  "maxHeight": 1000
}

行为与按钮控制

这一组决定窗口「能做什么」：

• resizable：能否拖拽边框改大小，默认 true。
• minimizable：能否最小化，默认 true。
• maximizable：能否最大化，默认 true。
• closable：能否关闭，默认 true。
• fullscreen：启动时是否全屏，默认 false。
• maximized：启动时是否直接最大化，默认 false。
• visible：启动时是否可见，默认 true（做启动闪屏时常临时设为 false）。
• focus：创建时是否抢焦点，默认 true。

{
  "label": "main",
  "resizable": true,
  "minimizable": true,
  "maximizable": true,
  "closable": true,
  "fullscreen": false,
  "maximized": false
}

位置与层级

控制窗口出现在哪、浮在多高：

• center：启动时是否在屏幕中央，默认 false。
• x / y：指定坐标（与 center 二选一，写了坐标 center 就失效）。
• alwaysOnTop：始终置顶，默认 false（做悬浮工具条很有用）。
• alwaysOnBottom：始终置底，默认 false。
• skipTaskbar：不在任务栏显示，默认 false（配合置顶做迷你浮窗）。

{
  "label": "main",
  "center": true,
  "alwaysOnTop": false,
  "skipTaskbar": false
}

外观与主题

这一组影响窗口「长什么样」：

• decorations：是否显示系统标题栏和边框，默认 true。设 false 就变成无边框窗口，下一章细讲。
• transparent：是否透明，默认 false。配合前端透明背景可做毛玻璃、圆角等效果。
• shadow：是否显示窗口阴影，默认 true（无边框时关掉阴影可避免矩形残影）。
• backgroundColor：窗口底色，用十六进制如 #ffffff 或带透明通道的 #rrggbbaa。
• theme：窗口主题，取值 "Light"、"Dark" 或 null（跟随系统）。

{
  "label": "main",
  "decorations": true,
  "transparent": false,
  "shadow": true,
  "backgroundColor": "#ffffff",
  "theme": null
}

其他常用字段

还有一些按需使用的项：

• url：窗口加载的页面路径，默认是 index.html，也可指向 settings.html 等。
• contentProtected：防止截图/录屏，部分平台支持，默认 false。
• dragDropEnabled：是否允许往窗口拖文件，默认 true。
• acceptFirstMouse：macOS 上点击未聚焦窗口时是否立即响应，默认 false。
• titleBarStyle：macOS 专属，"Visible"、"Transparent" 或 "Overlay"，控制标题栏样式。
• hiddenTitle：macOS 上是否隐藏标题文字，默认 false。

{
  "label": "main",
  "url": "index.html",
  "contentProtected": false,
  "dragDropEnabled": true,
  "titleBarStyle": "Visible"
}

一个配置里放多个窗口

app.windows 是数组，自然能写多个对象，每个对象是一个独立窗口，各自带自己的 label 和配置：

{
  "app": {
    "windows": [
      { "label": "main", "title": "主窗口", "width": 1024, "height": 768 },
      { "label": "about", "title": "关于", "width": 400, "height": 300, "resizable": false }
    ]
  }
}

这样应用一启动就同时开两个窗口。如果窗口要在用户操作后才出现，而不是启动时就有，请看第 28 章的运行时创建。

另外，平台差异可以用专属配置文件覆盖：放一个 tauri.windows.conf.json（macOS 对应 tauri.macos.conf.json，Linux 对应 tauri.linux.conf.json），它会按合并规则覆盖主配置里的同名字段。例如 Windows 上想要不同的起始尺寸，就写 tauri.windows.conf.json 去覆盖 windows 数组即可。

一个完整窗口配置示例

把上面字段合起来，一个典型的单窗口配置长这样：

{
  "app": {
    "windows": [
      {
        "label": "main",
        "title": "我的 Tauri 应用",
        "width": 1024,
        "height": 768,
        "minWidth": 480,
        "minHeight": 320,
        "resizable": true,
        "minimizable": true,
        "maximizable": true,
        "closable": true,
        "fullscreen": false,
        "maximized": false,
        "center": true,
        "decorations": true,
        "transparent": false,
        "shadow": true,
        "theme": null
      }
    ]
  }
}

小结

本章系统梳理了 app.windows 的全部常用配置字段：标题与初始尺寸、minWidth/maxWidth 等尺寸约束、resizable/minimizable 等行为开关、center/alwaysOnTop 等位置层级控制，以及 decorations/transparent/theme 等外观主题设置，还介绍了多窗口配置和平台专属覆盖文件的用法。记住：字段都是可选的，只写你关心的即可。Tauri 对没写的项用默认值。这个示例把常用项都列出来，方便你按需删改，不必一次记全。