diff --git a/MIGRATION_GUIDE.md b/MIGRATION_GUIDE.md new file mode 100644 index 0000000..1072359 --- /dev/null +++ b/MIGRATION_GUIDE.md @@ -0,0 +1,607 @@ +# Wails v3 API 迁移指南：alpha.27 → alpha.74 + +> 本文档基于对 [wailsapp/wails](https://github.com/wailsapp/wails) 仓库 `v3-alpha` 分支最新源码的全面分析。 + +--- + +## 总结 + +**好消息：你当前项目中使用的所有 API 在最新版本中基本保持向后兼容。** 大多数变更是新增功能和选项，而非破坏性更改。唯一需要关注的是 `app.Event.Emit()` 方法可能的签名变化。 + +--- + +## 1. `application.New()` 和 `application.Options{}` + +### 状态：✅ 向后兼容（新增字段，无破坏性变更） + +**你的当前代码：** +```go +app := application.New(application.Options{ + Name: "main", + Description: "A demo of using raw HTML & CSS", + Services: []application.Service{...}, + Assets: application.AssetOptions{...}, + Mac: application.MacOptions{...}, +}) +``` + +**变更内容：** + +`Options` 结构体新增了大量可选字段，但原有字段完全保留： + +| 新增字段 | 类型 | 说明 | +|---------|------|------| +| `Icon` | `[]byte` | 应用图标（用于默认关于框） | +| `Logger` | `*slog.Logger` | 自定义日志记录器 | +| `LogLevel` | `slog.Level` | 日志级别 | +| `MarshalError` | `func(error) []byte` | 自定义服务方法错误序列化 | +| `BindAliases` | `map[uint32]uint32` | 绑定方法别名 ID | +| `Flags` | `map[string]any` | 传递给前端的键值对 | +| `PanicHandler` | `func(*PanicDetails)` | panic 处理器 | +| `KeyBindings` | `map[string]func(window Window)` | 全局键绑定 | +| `OnShutdown` | `func()` | 关闭前回调（阻塞） | +| `PostShutdown` | `func()` | 关闭后回调 | +| `ShouldQuit` | `func() bool` | 控制是否允许退出 | +| `RawMessageHandler` | `func(window Window, message string, originInfo *OriginInfo)` | 自定义前端消息处理 | +| `WarningHandler` | `func(string)` | 警告处理器 | +| `ErrorHandler` | `func(err error)` | 错误处理器 | +| `FileAssociations` | `[]string` | 文件关联（如 `[".txt", ".md"]`） | +| `SingleInstance` | `*SingleInstanceOptions` | 单实例模式配置 | +| `Transport` | `Transport` | 自定义 IPC 传输层 | +| `Server` | `ServerOptions` | HTTP 服务器模式配置 | +| `DisableDefaultSignalHandler` | `bool` | 禁用默认信号处理 | +| `IOS` | `IOSOptions` | iOS 平台配置 | +| `Android` | `AndroidOptions` | Android 平台配置 | + +新增 `WindowsOptions` 字段： +```go +Windows: application.WindowsOptions{ + WndClass: "MyApp", + DisableQuitOnLastWindowClosed: true, + WebviewUserDataPath: "", + WebviewBrowserPath: "", + EnabledFeatures: []string{}, + DisabledFeatures: []string{}, + AdditionalBrowserArgs: []string{}, + WndProcInterceptor: nil, +}, +``` + +新增 `LinuxOptions` 字段： +```go +Linux: application.LinuxOptions{ + DisableQuitOnLastWindowClosed: true, + ProgramName: "my-app", +}, +``` + +**迁移建议：** 无需修改。可根据需要使用新增字段。 + +--- + +## 2. `application.Service` 和 `application.NewService()` 注册 API + +### 状态：✅ 向后兼容（新增 `NewServiceWithOptions`） + +**你的当前代码：** +```go +Services: []application.Service{ + application.NewService(appService), + application.NewService(&GreetService{}), +}, +``` + +**变更内容：** + +- `NewService[T any](instance *T) Service` — **签名不变** +- 新增 `NewServiceWithOptions[T any](instance *T, options ServiceOptions) Service` + +`ServiceOptions` 结构体： +```go +type ServiceOptions struct { + Name string // 服务名称 + Route string // HTTP 路由前缀，挂载 http.Handler + MarshalError func(error) []byte // 单服务的错误序列化 +} +``` + +新增 `DefaultServiceOptions` 变量。 + +**新增可选接口：** +```go +// 可选：自定义服务名称 +type ServiceName interface { + ServiceName() string +} +``` + +**示例：使用新 API** +```go +// 旧方式（仍然有效） +application.NewService(appService) + +// 新方式：带选项 +application.NewServiceWithOptions(appService, application.ServiceOptions{ + Name: "app-service", + Route: "/api/app", +}) +``` + +**迁移建议：** 无需修改。如需自定义服务路由或名称，可使用 `NewServiceWithOptions`。 + +--- + +## 3. `ServiceStartup` 方法签名 + +### 状态：✅ 完全相同，无变更 + +**你的当前代码：** +```go +func (a *App) ServiceStartup(ctx context.Context, options application.ServiceOptions) error { + a.ctx = ctx + return nil +} +``` + +**分析：** 签名完全一致：`ServiceStartup(ctx context.Context, options ServiceOptions) error` + +**新增可选生命周期接口：** +```go +// 可选：服务关闭时调用 +type ServiceShutdown interface { + ServiceShutdown() error +} +``` + +**示例：添加关闭钩子** +```go +func (a *App) ServiceShutdown() error { + log.Println("App service shutting down") + return nil +} +``` + +**迁移建议：** 无需修改。可选择实现 `ServiceShutdown()` 接口。 + +--- + +## 4. `app.Window.NewWithOptions()` / `WebviewWindowOptions` + +### 状态：✅ 向后兼容（大量新增选项） + +**你的当前代码：** +```go +mainWindow := app.Window.NewWithOptions(application.WebviewWindowOptions{ + Title: "Window 1", + Mac: application.MacWindow{ + InvisibleTitleBarHeight: 50, + Backdrop: application.MacBackdropTranslucent, + TitleBar: application.MacTitleBarHiddenInset, + }, + BackgroundColour: application.NewRGB(27, 38, 54), + URL: "/", + Width: 1240, + Height: 850, +}) +``` + +**变更内容：** + +`app.Window` 类型为 `*WindowManager`（之前已是类似的管理器模式），API 不变： +- `Window.New() *WebviewWindow` +- `Window.NewWithOptions(WebviewWindowOptions) *WebviewWindow` +- 新增 `Window.GetByName(name string) (Window, bool)` +- 新增 `Window.GetByID(id uint) (Window, bool)` +- 新增 `Window.Current() Window` +- 新增 `Window.GetAll() []Window` +- 新增 `Window.OnCreate(callback func(Window))` — 窗口创建回调 + +`WebviewWindowOptions` 新增字段： + +| 新增字段 | 类型 | 说明 | +|---------|------|------| +| `KeyBindings` | `map[string]func(window Window)` | 窗口级键绑定 | +| `IgnoreMouseEvents` | `bool` | 忽略鼠标事件（Windows + Mac） | +| `ContentProtectionEnabled` | `bool` | 内容保护（防截屏） | +| `HideOnFocusLost` | `bool` | 失去焦点时隐藏 | +| `HideOnEscape` | `bool` | 按 Esc 键隐藏 | +| `UseApplicationMenu` | `bool` | 使用应用全局菜单 | +| `DefaultContextMenuDisabled` | `bool` | 禁用默认右键菜单 | +| `DevToolsEnabled` | `bool` | 启用开发者工具 | + +`MacWindow` 新增字段： + +| 新增字段 | 类型 | 说明 | +|---------|------|------| +| `EventMapping` | `map[events.WindowEventType]events.WindowEventType` | 事件映射 | +| `EnableFraudulentWebsiteWarnings` | `bool` | 欺诈网站警告 | +| `WebviewPreferences` | `MacWebviewPreferences` | WebView 偏好设置 | +| `WindowLevel` | `MacWindowLevel` | 窗口层级 | +| `CollectionBehavior` | `MacWindowCollectionBehavior` | Spaces 和全屏行为 | +| `LiquidGlass` | `MacLiquidGlass` | Liquid Glass 效果（macOS 15.0+） | + +`WindowsWindow` 新增字段： +- `HiddenOnTaskbar` — 从任务栏隐藏 +- `EnableSwipeGestures` — 触控滑动手势 +- `Menu *Menu` — 窗口菜单 +- `Permissions` — WebView2 权限控制 +- `ExStyle` — 扩展窗口样式 +- `GeneralAutofillEnabled` / `PasswordAutosaveEnabled` +- `WindowDidMoveDebounceMS` / `ResizeDebounceMS` + +新增 `LinuxWindow` 结构体： +```go +Linux: application.LinuxWindow{ + Icon: []byte{}, + WindowIsTranslucent: false, + WebviewGpuPolicy: application.WebviewGpuPolicyOnDemand, + Menu: myMenu, + MenuStyle: application.LinuxMenuStylePrimaryMenu, +}, +``` + +**迁移建议：** 无需修改。可利用 `HideOnFocusLost` 和 `HideOnEscape` 简化你的系统托盘窗口逻辑。 + +--- + +## 5. `events.Common.WindowClosing` 和 `RegisterHook` + +### 状态：✅ 完全相同，无变更 + +**你的当前代码：** +```go +mainWindow.RegisterHook(events.Common.WindowClosing, func(event *application.WindowEvent) { + mainWindow.Hide() + event.Cancel() +}) +``` + +**分析：** +- `events.Common.WindowClosing` — 仍然存在（值 `1028`） +- `RegisterHook` 签名不变：`RegisterHook(eventType events.WindowEventType, callback func(event *WindowEvent)) func()` +- `WindowEvent.Cancel()` 方法不变 +- 现在 `RegisterHook` 返回一个 `func()` 取消函数（alpha.27 可能也是如此） + +**补充：`OnWindowEvent` 方法** +```go +// OnWindowEvent 用于注册窗口事件监听器（非 Hook） +mainWindow.OnWindowEvent(events.Common.WindowClosing, func(event *application.WindowEvent) { + // Hook 可以取消事件，OnWindowEvent 不能 +}) +``` + +**迁移建议：** 无需修改。 + +--- + +## 6. `app.SystemTray.New()` 系统托盘 API + +### 状态：✅ 向后兼容（大量功能增强） + +**你的当前代码：** +```go +systray := app.SystemTray.New() +systray.SetMenu(trayMenu) +systray.OnClick(func() { + mainWindow.Show() + mainWindow.Focus() +}) +``` + +**变更内容：** + +原有 API 完全保留，新增以下方法： + +| 新增方法 | 说明 | +|---------|------| +| `OnRightClick(func())` | 右键点击处理 | +| `OnDoubleClick(func())` | 双击处理 | +| `OnRightDoubleClick(func())` | 右键双击处理 | +| `OnMouseEnter(func())` | 鼠标进入处理 | +| `OnMouseLeave(func())` | 鼠标离开处理 | +| `AttachWindow(window Window)` | 绑定窗口到托盘（自动切换显示/隐藏） | +| `WindowOffset(offset int)` | 设置窗口与托盘的间距 | +| `WindowDebounce(debounce time.Duration)` | Windows 上防抖设置 | +| `Show()` / `Hide()` | 显示/隐藏托盘图标 | +| `OpenMenu()` | 打开托盘菜单 | +| `ShowWindow()` / `HideWindow()` / `ToggleWindow()` | 窗口操作 | +| `SetDarkModeIcon(icon []byte)` | 深色模式图标 | +| `SetTemplateIcon(icon []byte)` | macOS 模板图标 | +| `SetTooltip(tooltip string)` | 设置提示文本 | +| `SetLabel(label string)` | 设置标签文本 | +| `SetIconPosition(IconPosition)` | 设置图标位置 | +| `Destroy()` | 销毁托盘 | + +**推荐：使用 `AttachWindow` 简化代码** + +你当前手动实现的"点击托盘显示/隐藏窗口"逻辑，现在可以用内置的 `AttachWindow` 替代： + +```go +// 新方式（推荐） +systray := app.SystemTray.New() +systray.SetMenu(trayMenu) +systray.AttachWindow(mainWindow).WindowOffset(10) +// AttachWindow 自动处理点击切换显示/隐藏 +``` + +**迁移建议：** 无需修改。推荐使用 `AttachWindow` 简化托盘-窗口绑定逻辑。 + +--- + +## 7. `app.Event.Emit()` 事件 API + +### 状态：⚠️ 需要验证（可能有方法名变更） + +**你的当前代码：** +```go +app.Event.Emit("time", now) +``` + +**分析：** + +`app.Event` 类型为 `*EventManager`。在最新源码中： + +- `WebviewWindow.EmitEvent(name string, data ...any) bool` — 窗口级事件发射 +- 内部调用 `globalApplication.Event.EmitEvent(event *CustomEvent)` + +`EventManager` 上的方法可能从 `Emit(name, data...)` 更名为 `EmitEvent`，或两者共存。 + +**可能的迁移方式：** +```go +// 如果 Emit 仍然存在（最可能的情况） +app.Event.Emit("time", now) + +// 如果需要使用 EmitEvent +app.EmitEvent(&application.CustomEvent{ + Name: "time", + Data: now, +}) +``` + +**新增事件 API 特性：** +- 严格事件模式：构建标签 `strictevents` 启用事件注册检查 +- `OnApplicationEvent` — 监听应用级事件 +- 事件发射现在返回 `bool`，指示事件是否被 Hook 取消 + +**迁移建议：** 升级后编译测试。如果 `Emit` 编译失败，尝试改用 `EmitEvent` 或查看最新文档。 + +--- + +## 8. `application.AssetOptions` 和 `AssetFileServerFS` + +### 状态：✅ 完全兼容（新增 `BundledAssetFileServer`） + +**你的当前代码：** +```go +Assets: application.AssetOptions{ + Handler: application.AssetFileServerFS(assets), +}, +``` + +**变更内容：** + +`AssetOptions` 结构体字段不变： +```go +type AssetOptions struct { + Handler http.Handler // 不变 + Middleware Middleware // 不变 + DisableLogging bool // 不变 +} +``` + +`AssetFileServerFS` 函数签名不变： +```go +func AssetFileServerFS(assets fs.FS) http.Handler +``` + +**新增：`BundledAssetFileServer`** +```go +func BundledAssetFileServer(assets fs.FS) http.Handler +``` + +与 `AssetFileServerFS` 的区别：`BundledAssetFileServer` 额外在 `/wails/runtime.js` 路径提供编译后的运行时 JS 文件。 + +**新增：中间件链** +```go +Assets: application.AssetOptions{ + Handler: application.AssetFileServerFS(assets), + Middleware: application.ChainMiddleware( + myAuthMiddleware, + myLoggingMiddleware, + ), + DisableLogging: true, +}, +``` + +**迁移建议：** 无需修改。如果需要运行时 JS 内置服务，可考虑切换到 `BundledAssetFileServer`。 + +--- + +## 9. `MacOptions`, `MacWindow`, `MacTitleBarHiddenInset`, `MacBackdropTranslucent` + +### 状态：✅ 完全兼容（新增选项） + +**你的当前代码：** +```go +Mac: application.MacOptions{ + ApplicationShouldTerminateAfterLastWindowClosed: true, +}, +// ... +Mac: application.MacWindow{ + InvisibleTitleBarHeight: 50, + Backdrop: application.MacBackdropTranslucent, + TitleBar: application.MacTitleBarHiddenInset, +}, +``` + +**分析：** + +所有使用的类型和常量均未更改： + +- `MacOptions.ApplicationShouldTerminateAfterLastWindowClosed` — ✅ 存在 +- `MacOptions.ActivationPolicy` — ✅ 存在 +- `MacWindow.InvisibleTitleBarHeight` — ✅ 存在 +- `MacWindow.Backdrop` (类型 `MacBackdrop`) — ✅ 存在 +- `MacWindow.TitleBar` (类型 `MacTitleBar`) — ✅ 存在 +- `MacBackdropTranslucent` 常量 — ✅ 存在 +- `MacTitleBarHiddenInset` 预定义变量 — ✅ 存在 + +**新增 `MacBackdrop` 值：** +```go +const ( + MacBackdropNormal MacBackdrop = iota // 不变 + MacBackdropTransparent // 不变 + MacBackdropTranslucent // 不变 + MacBackdropLiquidGlass // 新增：macOS 15.0+ Liquid Glass +) +``` + +**新增 `MacTitleBar` 预定义变量：** +```go +var MacTitleBarHiddenInsetUnified = MacTitleBar{...} // 新增 +``` + +**新增 `MacWindow` 功能：** +- `MacWindowLevel` — 控制窗口层级（`normal`, `floating`, `modalPanel` 等） +- `MacWindowCollectionBehavior` — 控制 Spaces 和全屏行为 +- `MacLiquidGlass` — Liquid Glass 效果配置 +- `MacWebviewPreferences` — WebView 偏好设置 + +**Liquid Glass 示例（macOS 15.0+）：** +```go +Mac: application.MacWindow{ + Backdrop: application.MacBackdropLiquidGlass, + LiquidGlass: application.MacLiquidGlass{ + Style: application.LiquidGlassStyleAutomatic, + CornerRadius: 12, + TintColor: &application.RGBA{Red: 255, Green: 255, Blue: 255, Alpha: 128}, + }, +}, +``` + +**迁移建议：** 无需修改。 + +--- + +## 10. `application.Context` 类型（菜单点击处理器） + +### 状态：✅ 完全相同，无变更 + +**你的当前代码：** +```go +trayMenu.Add("显示主窗口").OnClick(func(ctx *application.Context) { + mainWindow.Show() + mainWindow.Focus() +}) +``` + +**分析：** + +- `Context` 结构体不变 +- `MenuItem.OnClick(func(*Context)) *MenuItem` — 签名不变 +- `Context.ClickedMenuItem() *MenuItem` — 不变 +- `Context.IsChecked() bool` — 不变 +- `Context.ContextMenuData() string` — 不变 + +`Menu.Add(label string) *MenuItem` — 不变 + +**迁移建议：** 无需修改。 + +--- + +## 其他重要新增功能 + +### 窗口接口 `Window` +最新版本定义了 `Window` 接口，`*WebviewWindow` 实现该接口。这允许更灵活的窗口操作。 + +### 新增 Manager 模式 +所有子系统现在通过 Manager 模式访问： +```go +app.Window // *WindowManager +app.SystemTray // *SystemTrayManager +app.Event // *EventManager +app.Menu // *MenuManager +app.Dialog // *DialogManager +app.Screen // *ScreenManager +app.Clipboard // *ClipboardManager +app.Browser // *BrowserManager +app.Env // *EnvironmentManager +app.KeyBinding // *KeyBindingManager +app.ContextMenu // *ContextMenuManager +``` + +### 运行时服务注册 +```go +app.RegisterService(application.NewService(myService)) +``` + +### HTTP Transport +```go +Transport: application.NewHTTPTransport(), +``` + +### Server 模式 +使用 `server` 构建标签，应用可作为 HTTP 服务器运行： +```go +Server: application.ServerOptions{ + Host: "0.0.0.0", + Port: 8080, +}, +``` + +### 新增平台支持 +- **iOS** — `IOSOptions` 包含 WebView 偏好、原生标签栏等 +- **Android** — `AndroidOptions` 包含 WebView 配置 + +--- + +## 迁移步骤 + +1. **更新依赖版本：** + ```bash + go get github.com/wailsapp/wails/v3@v3.0.0-alpha.74 + go mod tidy + ``` + +2. **编译测试：** + ```bash + go build . + ``` + +3. **检查 `app.Event.Emit()` 是否编译通过。** 如果失败，尝试： + - 使用 `app.EmitEvent(name, data...)` 或 + - 查看 `EventManager` 的最新方法列表 + +4. **可选优化：** + - 使用 `systray.AttachWindow(mainWindow)` 替代手动托盘-窗口切换逻辑 + - 考虑使用 `BundledAssetFileServer` 替代 `AssetFileServerFS` + - 利用 `WebviewWindowOptions.HideOnEscape` 和 `HideOnFocusLost` 简化窗口行为 + - 实现 `ServiceShutdown()` 接口处理优雅关闭 + +5. **更新前端绑定：** + ```bash + # 如果使用 Wails CLI 生成绑定 + wails3 generate bindings + ``` + +--- + +## 你的项目兼容性矩阵 + +| API 使用点 | 当前代码 | 兼容性 | 操作 | +|-----------|---------|--------|------| +| `application.New(Options{})` | ✅ | 兼容 | 无需修改 | +| `application.NewService()` | ✅ | 兼容 | 无需修改 | +| `ServiceStartup(ctx, opts)` | ✅ | 兼容 | 无需修改 | +| `app.Window.NewWithOptions()` | ✅ | 兼容 | 无需修改 | +| `events.Common.WindowClosing` | ✅ | 兼容 | 无需修改 | +| `RegisterHook()` | ✅ | 兼容 | 无需修改 | +| `app.SystemTray.New()` | ✅ | 兼容 | 无需修改 | +| `app.Event.Emit()` | ⚠️ | 需验证 | 编译测试 | +| `AssetFileServerFS()` | ✅ | 兼容 | 无需修改 | +| `MacBackdropTranslucent` | ✅ | 兼容 | 无需修改 | +| `MacTitleBarHiddenInset` | ✅ | 兼容 | 无需修改 | +| `MacOptions{}` | ✅ | 兼容 | 无需修改 | +| `*application.Context` | ✅ | 兼容 | 无需修改 | +| `app.NewMenu()` | ✅ | 兼容 | 无需修改 | +| `app.Quit()` | ✅ | 兼容 | 无需修改 | diff --git a/frontend/app/components/HelloWorld.vue b/frontend/app/components/HelloWorld.vue index 3c7c085..7aea575 100644 --- a/frontend/app/components/HelloWorld.vue +++ b/frontend/app/components/HelloWorld.vue @@ -1,5 +1,5 @@