Tauri笔记

官方文档

tauri - Rust

AppConfig

WindowConfig 对象属性说明

WindowConfig 是 Tauri 配置文件中 app.windows 数组中的对象，用于定义窗口的外观和行为。以下是所有属性的详细说明，按字母顺序排列，并附上平台特定的信息和默认值。

---

1. acceptFirstMouse (布尔值)

• 描述: 在 macOS 上，决定当窗口未激活时，点击窗口是否会同时触发 Webview 的点击事件。
• 用途: 如果设置为 true，用户点击未激活窗口时，点击会直接传递到 Webview（类似网页内容的交互）。如果设置为 false，需要先激活窗口才能交互。
• 平台特定: 仅适用于 macOS。
• 默认值: 未指定（通常为 false）。
• 示例: acceptFirstMouse: true

---

2. additionalBrowserArgs (字符串或 null)

• 描述: 在 Windows 上，为 Webview 指定额外的浏览器参数。
• 用途: 默认情况下，Tauri 使用一些参数（如 --disable-features=msWebOOUI,msPdfOOUI,msSmartScreenProtection）来禁用特定功能。如果自定义此参数，需要手动处理这些功能的禁用。
• 平台特定: 仅适用于 Windows。
• 默认值: null
• 注意: 使用时需谨慎，确保不会破坏 Webview 的默认行为。
• 示例: additionalBrowserArgs: "--disable-gpu"

---

3. alwaysOnBottom (布尔值)

• 描述: 窗口是否始终位于其他窗口下方。
• 用途: 如果设置为 true，窗口将始终保持在最底层，无法被其他窗口覆盖。
• 平台特定: 支持 Windows 和 macOS，Linux 可能有限支持。
• 默认值: false
• 示例: alwaysOnBottom: true

---

4. alwaysOnTop (布尔值)

• 描述: 窗口是否始终位于其他窗口之上。
• 用途: 如果设置为 true，窗口将始终保持在最顶层，覆盖其他窗口。
• 平台特定: 支持 Windows 和 macOS，Linux 可能有限支持。
• 默认值: false
• 示例: alwaysOnTop: true

---

5. backgroundColor (颜色值或 null)

• 描述: 设置窗口和 Webview 的背景颜色。

• 格式: 使用颜色值（如 #RRGGBBAA 或 Color 对象）。

• 平台特定:

  • Windows: 窗口层的 alpha 通道（透明度）会被忽略；Windows 7 的 Webview 层忽略 alpha 通道；Windows 8 及以上版本如果 alpha 值为 0，则 Webview 层忽略 alpha。

• 默认值: null（使用系统默认背景）。

• 示例: backgroundColor: "#FF0000FF"（红色不透明）

---

6. browserExtensionsEnabled (布尔值)

• 描述: 是否允许为 Webview 进程安装浏览器扩展。

• 用途: 如果启用，Webview 支持安装浏览器扩展（如 Chrome 扩展）。

• 平台特定:

  • Windows: 控制 WebView2 的 AreBrowserExtensionsEnabled 设置。
  • macOS/Linux/iOS/Android: 不支持。

• 默认值: false

• 示例: browserExtensionsEnabled: true

---

7. center (布尔值)

• 描述: 窗口启动时是否居中显示。
• 用途: 如果设置为 true，窗口将自动在屏幕中心打开。
• 默认值: false
• 示例: center: true

---

8. closable (布尔值)

• 描述: 窗口的原生关闭按钮是否启用。

• 用途: 如果设置为 false，窗口的关闭按钮（通常是窗口右上角的 “X”）会被禁用。

• 平台特定:

  • Linux: GTK+ 会尝试说服窗口管理器不显示关闭按钮，但效果取决于系统。
  • iOS/Android: 不支持。

• 默认值: true

• 示例: closable: false

---

9. contentProtected (布尔值)

• 描述: 防止窗口内容被其他应用捕获（如屏幕录制）。
• 用途: 如果设置为 true，其他应用无法截屏或录制窗口内容，增强隐私保护。
• 默认值: false
• 示例: contentProtected: true

---

10. create (布尔值)

• 描述: 是否在应用程序启动时自动创建此窗口。
• 用途: 如果设置为 false，需要在代码中手动使用 WebviewWindowBuilder::from_config 创建窗口。
• 默认值: true
• 示例: create: false

---

11. decorations (布尔值)

• 描述: 窗口是否显示边框和标题栏。
• 用途: 如果设置为 false，窗口将无边框和标题栏，适合自定义界面设计。
• 默认值: true
• 示例: decorations: false

---

12. devtools (布尔值或 null)

• 描述: 是否启用浏览器开发者工具（Web 调试工具）。

• 用途: 如果启用，用户可以打开浏览器开发者工具（如 F12 打开的调试窗口）。

• 平台特定:

  • macOS: 调用私有 API。
  • Android: 不支持 Wry 的开发者工具 API，需通过 Chrome 的 chrome://inspect/#devices 打开。
  • iOS: 通过 Safari 的“开发 > 设备 > Webview”打开。

• 默认值: true（调试模式下默认启用，发布模式需启用 devtools 功能标志）。

• 示例: devtools: true

---

13. dragDropEnabled (布尔值)

• 描述: 是否在 Webview 上启用拖放功能。
• 用途: 如果禁用（false），可以支持前端的 HTML5 拖放功能（Windows 上需要禁用）。
• 默认值: true
• 示例: dragDropEnabled: false

---

14. focus (布尔值)

• 描述: 窗口启动时是否自动获得焦点。
• 用途: 如果设置为 true，窗口打开后会自动成为活跃窗口。
• 默认值: true
• 示例: focus: false

---

15. fullscreen (布尔值)

• 描述: 窗口启动时是否全屏显示。
• 默认值: false
• 示例: fullscreen: true

---

16. height (双精度浮点数)

• 描述: 窗口的高度（单位：像素）。
• 默认值: 600
• 示例: height: 700（如您的配置）

---

17. hiddenTitle (布尔值)

• 描述: 在 macOS 上，是否隐藏窗口标题。
• 用途: 如果设置为 true，窗口标题不会显示在标题栏中。
• 平台特定: 仅适用于 macOS。
• 默认值: false
• 示例: hiddenTitle: true

---

18. incognito (布尔值)

• 描述: 是否以无痕模式（Incognito）启动 Webview。
• 用途: 无痕模式下，Webview 不会保存浏览数据（如 cookie、缓存）。
• 平台特定: Android 不支持。
• 默认值: false
• 示例: incognito: true

---

19. label (字符串)

• 描述: 窗口的唯一标识符，必须是字母数字。
• 用途: 用于在代码中引用特定窗口。
• 默认值: "main"
• 示例: label: "main"

---

20. maxHeight (双精度浮点数或 null)

• 描述: 窗口的最大高度。
• 默认值: null（无限制）
• 示例: maxHeight: 1000

---

21. maximizable (布尔值)

• 描述: 窗口的原生最大化按钮是否启用。

• 用途: 如果设置为 false，最大化按钮会被禁用。如果 resizable 为 false，此设置会被忽略。

• 平台特定:

  • macOS: 禁用标题栏中的“缩放”按钮（也用于进入全屏）。
  • Linux/iOS/Android: 不支持。

• 默认值: true

• 示例: maximizable: false

---

22. maximized (布尔值)

• 描述: 窗口启动时是否最大化。
• 默认值: false
• 示例: maximized: true

---

23. maxWidth (双精度浮点数或 null)

• 描述: 窗口的最大宽度。
• 默认值: null（无限制）
• 示例: maxWidth: 1200

---

24. minHeight (双精度浮点数或 null)

• 描述: 窗口的最小高度。
• 默认值: null（无限制）
• 示例: minHeight: 400

---

25. minimizable (布尔值)

• 描述: 窗口的原生最小化按钮是否启用。
• 平台特定: Linux/iOS/Android 不支持。
• 默认值: true
• 示例: minimizable: false

---

26. minWidth (双精度浮点数或 null)

• 描述: 窗口的最小宽度。
• 默认值: null（无限制）
• 示例: minWidth: 600

---

27. parent (字符串或 null)

• 描述: 设置与此窗口关联的父窗口的标签（label）。

• 用途: 用于创建子窗口，子窗口会与父窗口关联。

• 平台特定:

  • Windows: 子窗口始终位于父窗口之上，父窗口销毁时子窗口自动销毁，父窗口最小化时子窗口隐藏。
  • Linux: 子窗口被设置为父窗口的“瞬态”窗口（transient）。
  • macOS: 子窗口被添加为父窗口的子节点。

• 默认值: null

• 示例: parent: "main"

---

28. proxyUrl (字符串或 null，URI 格式)

• 描述: 为 Webview 的所有网络请求设置代理 URL。
• 格式: 必须是 http:// 或 socks5:// 开头的 URL。
• 平台特定: macOS 需启用 macos-proxy 功能标志，仅支持 macOS 14+。
• 默认值: null
• 示例: proxyUrl: "proxy.example.com"

---

29. resizable (布尔值)

• 描述: 窗口是否可以调整大小。
• 用途: 如果设置为 false，用户无法拖动窗口边缘调整大小，且最大化按钮会自动禁用。
• 默认值: true
• 示例: resizable: false

---

30. shadow (布尔值)

• 描述: 窗口是否显示阴影。

• 平台特定:

  • Windows: 如果 decorations 为 true，阴影始终开启；如果 decorations 为 false，启用阴影会添加 1px 白色边框，且在 Windows 11 上有圆角效果。
  • Linux: 不支持。

• 默认值: true

• 示例: shadow: false

---

31. skipTaskbar (布尔值)

• 描述: 是否在 Windows 和 Linux 的任务栏中隐藏窗口图标。
• 用途: 如果设置为 true，窗口不会在任务栏显示图标。
• 默认值: false
• 示例: skipTaskbar: true

---

32. tabbingIdentifier (字符串或 null)

• 描述: 在 macOS 上设置窗口的标签标识符，用于分组窗口。
• 用途: 具有相同 tabbingIdentifier 的窗口会被分组为一个标签页组。
• 平台特定: 仅适用于 macOS。
• 默认值: null（禁用自动标签分组）
• 示例: tabbingIdentifier: "my-app-tabs"

---

33. theme (字符串或 null)

• 描述: 设置窗口的初始主题，默认为系统主题。
• 可选值: "light", "dark", 或 null（跟随系统主题）。
• 平台特定: 仅支持 Windows 和 macOS 10.14+。
• 默认值: null
• 示例: theme: "dark"

---

34. title (字符串)

• 描述: 窗口的标题，显示在标题栏中。
• 默认值: "Tauri App"
• 示例: title: "my-app"（如您的配置）

---

35. titleBarStyle (字符串)

• 描述: 设置 macOS 标题栏的样式。
• 可选值: "Visible"（默认），或其他 macOS 支持的样式。
• 平台特定: 仅适用于 macOS。
• 默认值: "Visible"
• 示例: titleBarStyle: "Visible"

---

36. transparent (布尔值)

• 描述: 窗口是否透明。

• 用途: 如果启用，窗口背景可以设置为透明，适合创建自定义形状或透明效果的界面。

• 平台特定:

  • macOS: 需要启用 macos-private-api 功能标志，且使用私有 API 会导致应用无法上架 macOS App Store。

• 默认值: false

• 示例: transparent: true

---

37. url (字符串)

• 描述: 窗口 Webview 加载的 URL。
• 默认值: "index.html"
• 示例: url: "example.com"

---

38. useHttpsScheme (布尔值)

• 描述: 是否为自定义协议使用 https://.localhost 而不是默认的 http://.localhost。

• 用途: 影响 Windows 和 Android 上的协议行为。

• 注意:

  • 使用 https 不会允许混合内容（mixed content），与 macOS 和 Linux 的行为不一致。
  • 更改此值会影响 IndexedDB、cookie 和 localStorage 的存储位置，导致无法访问旧数据。

• 默认值: false

• 示例: useHttpsScheme: true

---

39. userAgent (字符串或 null)

• 描述: 设置 Webview 的用户代理字符串。
• 用途: 用于自定义 Webview 的浏览器标识。
• 默认值: null
• 示例: userAgent: "MyApp/1.0"

---

40. visible (布尔值)

• 描述: 窗口启动时是否可见。
• 用途: 如果设置为 false，窗口将隐藏，直到通过代码显式显示。
• 默认值: true
• 示例: visible: false

---

41. visibleOnAllWorkspaces (布尔值)

• 描述: 窗口是否在所有工作区或虚拟桌面显示。
• 平台特定: Windows/iOS/Android 不支持。
• 默认值: false
• 示例: visibleOnAllWorkspaces: true

---

42. width (双精度浮点数)

• 描述: 窗口的宽度（单位：像素）。
• 默认值: 800
• 示例: width: 960（如您的配置）

---

43. windowClassname (字符串或 null)

• 描述: 在 Windows 上创建窗口时使用的窗口类名。
• 平台特定: 仅适用于 Windows。
• 默认值: null
• 示例: windowClassname: "MyAppWindow"

---

44. windowEffects (WindowEffectsConfig 或 null)

• 描述: 设置窗口效果（如模糊、亚克力效果等），需启用透明窗口（transparent: true）。

• 可选值:

  • macOS（10.10+ 或 10.14+）:

    • "appearanceBased": 基于系统外观的默认材质。
    • "light", "dark", "mediumLight", "ultraDark", "titlebar", "selection", "menu", "popover", "sidebar", "headerView", "sheet", "windowBackground", "hudWindow", "fullScreenUI", "tooltip", "contentBackground", "underWindowBackground", "underPageBackground"

  • Windows（7/10/11）:

    • "mica": 匹配系统深色模式的 Mica 效果（Windows 11）。
    • "micaDark": 深色 Mica 效果（Windows 11，需系统启用深色模式）。
    • "micaLight": 浅色 Mica 效果（Windows 11）。
    • "tabbed", "tabbedDark", "tabbedLight": 标签效果（Windows 11）。
    • "blur": 模糊效果（Windows 7/10/11，22H1 性能较差）。
    • "acrylic": 亚克力效果（Windows 10/11，性能较差）。

• 平台特定:

  • Windows: 如果使用装饰或阴影，需参考 GitHub 上的解决方法（tao issue #72）。
  • Linux: 不支持。

• 默认值: null

• 示例: windowEffects: { effects: ["mica"] }

---

45. x (双精度浮点数或 null)

• 描述: 窗口左上角的水平位置（相对于屏幕）。
• 默认值: null（由系统决定）
• 示例: x: 100

---

46. y (双精度浮点数或 null)

• 描述: 窗口左上角的垂直位置（相对于屏幕）。
• 默认值: null（由系统决定）
• 示例: y: 100

---

47. zoomHotkeysEnabled (布尔值)

• 描述: 是否启用页面缩放快捷键。

• 用途: 允许通过快捷键（如 Ctrl + - 或 Command + =）缩放 Webview 内容。

• 平台特定:

  • Windows: 控制 WebView2 的 IsZoomControlEnabled 设置。
  • macOS/Linux: 注入 polyfill，支持 20%-1000% 缩放范围，需 webview:allow-set-webview-zoom 权限。
  • Android/iOS: 不支持。

• 默认值: false

• 示例: zoomHotkeysEnabled: true

---

您配置文件中的 WindowConfig 示例

在您的 tauri.conf.json 文件中，app.windows 部分定义了一个窗口：

json

"windows": [
  {
    "title": "my-app",
    "width": 960,
    "height": 700
  }
]

• title: "my-app": 窗口标题为 “my-app”，显示在窗口标题栏。
• width: 960: 窗口宽度为 960 像素。
• height: 700: 窗口高度为 700 像素。

其他未指定的属性将使用默认值，例如 resizable: true、visible: true 等。

---

查找更多信息

• 官方文档: 所有 WindowConfig 属性的详细说明都在 Tauri 配置文档 中。建议直接访问此页面，搜索特定属性（如 center 或 windowEffects）以获取更多细节。
• JSON Schema: 您的配置文件使用 $schema: "schema.tauri.app/config/2"，可… JSON Schema 的编辑器（如 VS Code）中获得自动补全和验证。
• 社区资源: 如果有疑问，可以在 Tauri GitHub Discussions 或 Tauri 的 Discord 社区提问。

---

常见问题解答

• 如何选择合适的属性？ 根据您的应用需求选择。例如：

  • 如果需要无边框窗口，设置 decorations: false 和 transparent: true。
  • 如果需要全屏应用，设置 fullscreen: true。
  • 如果需要多窗口分组（macOS），使用 tabbingIdentifier。

• 如何调试配置？ 使用 tauri dev 运行应用时，Tauri CLI 会验证配置文件并提示错误。检查终端输出以定位问题。

• 特定属性不生效怎么办？ 确认是否涉及平台特定限制。例如，windowEffects 在 Linux 上无效，proxyUrl 在 macOS 需额外功能标志。