跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
设计与 UI

wails3

Build, debug, and package Wails v3 desktop apps (module github.com/wailsapp/wails/v3, a prerelease) that pair a Go backend with a web frontend: application.New and its Options, services registered with application.NewService and their startup and shutdown hooks, bindings from wails3 generate bindings, errors and panics as rejected promises, typed events, dialogs, windows, embedded assets, the wails3 CLI and Taskfile, server mode, and cgo with GTK4 and WebKitGTK 6.0 on Linux. Use when writing or changing a Wails v3 app, adding a service method, or debugging a v3 build, binding, or blank window. Not for Wails v2 (module github.com/wailsapp/wails/v2; use the wails2 skill), Electron or Tauri apps, or Go web servers.

tpscloud · 已有静态检查记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add tpscloud/gophers --skill wails3

技能说明


name: wails3 description: "Build, debug, and package Wails v3 desktop apps (module github.com/wailsapp/wails/v3, a prerelease) that pair a Go backend with a web frontend: application.New and its Options, services registered with application.NewService and their startup and shutdown hooks, bindings from wails3 generate bindings, errors and panics as rejected promises, typed events, dialogs, windows, embedded assets, the wails3 CLI and Taskfile, server mode, and cgo with GTK4 and WebKitGTK 6.0 on Linux. Use when writing or changing a Wails v3 app, adding a service method, or debugging a v3 build, binding, or blank window. Not for Wails v2 (module github.com/wailsapp/wails/v2; use the wails2 skill), Electron or Tauri apps, or Go web servers." license: "MIT"

Wails v3

Wails v3 runs a Go backend and a web frontend in native windows. You create the app with application.New, register Go structs as services, open windows through app.Window, and reach dialogs and events through managers on the app (app.Dialog, app.Event). The exported methods of each service become promise-returning functions in generated TypeScript or JavaScript. v3 is a prerelease, its API changes between betas, and it shares almost no API with v2, so most bugs come from code written for v2 or for a different beta.

Workflow

  1. Read go.mod. If it requires github.com/wailsapp/wails/v2, stop and use the wails2 skill; without it, read the pinned v2 module source. v2 and v3 APIs do not mix, so do not migrate between majors, or move to another v3 beta, unless asked. If the project pins a v3 version other than the one in Sources, read that version's source before trusting a detail here: go doc github.com/wailsapp/wails/v3/pkg/application, or the module cache under $(go env GOMODCACHE)/github.com/wailsapp/wails/v3@<version>.
  2. Find application.New(application.Options{...}), the services, the windows, the //go:embed asset directory, and how the project builds: Taskfile.yml with the wails3 CLI, or plain go build from a script. Keep the existing workflow.
  3. Change the Go side first, following The service contract. For generated bindings, the JavaScript runtime, and frontend tests, see references/frontend.md.
  4. For build tags, cgo, Linux libraries, the Taskfile, and server mode, see references/building.md.
  5. Before finishing, run Verify.

Telling v3 from v2

ConcernWails v3Wails v2 (never in v3 code)
Entry pointapplication.New(application.Options{...}), then app.Run()wails.Run(&options.App{...})
Exposing GoServices: []application.Service{application.NewService(&T{})}Bind: []any{&T{}}
LifecycleServiceStartup(ctx, application.ServiceOptions) error and ServiceShutdown() error on the service; Options.OnShutdownOnStartup, OnDomReady, OnShutdown, OnBeforeClose in options.App
Runtime callsapp.Event.Emit, app.Dialog.SaveFile(), app.Window.NewWithOptionsruntime.EventsEmit(ctx, ...), runtime.SaveFileDialog(ctx, ...)
Frontendfrontend/bindings/<import path>/ and @wailsio/runtimewailsjs/go/... and window.go
Toolingwails3 CLI, Taskfile.yml, build/config.ymlwails CLI, wails.json
Linuxgtk4 and webkitgtk-6.0; -tags gtk3 for GTK3gtk+-3.0 and webkit2gtk-4.0 or -4.1

Imports from github.com/wailsapp/wails/v2/..., a runtime. call that takes a context, or a wailsjs path in a v3 project is a mixing mistake.

The service contract

Keep each service thin, its exported methods the whole frontend API, and everything native behind an interface the tests can replace:

// examples/wails3/notes/service.go (trimmed: storage and the other methods omitted)
type Native interface {
	SaveFile(defaultName string) (string, error) // "" when cancelled
	Emit(event string, data any)
}

type Service struct {
	mu     sync.Mutex // bound calls can run concurrently
	notes  []Note
	native Native
}

func NewService(native Native) *Service { return &Service{native: native} }

func (s *Service) SaveNote(in NoteInput) (Note, error) {
	in, err := validate(in)
	if err != nil {
		return Note{}, err // rejects the frontend promise
	}
	return s.store(Note(in)) // locks s.mu and emits EventNotesChanged
}

The app wires it up in main:

// examples/wails3/main.go (trimmed: init, window size, Mac options, Emit, and the file filter omitted)
// assets is the //go:embed all:frontend/dist filesystem (see Assets below).
func main() {
	app := application.New(application.Options{
		Name:   "Notes",
		Assets: application.AssetOptions{Handler: application.AssetFileServerFS(assets)},
	})
	app.RegisterService(application.NewService(notes.NewService(desktop{app})))
	app.Window.NewWithOptions(application.WebviewWindowOptions{Title: "Notes", URL: "/"})
	if err := app.Run(); err != nil {
		log.Fatal(err)
	}
}

// desktop implements notes.Native; the service's tests use a fake instead.
type desktop struct{ app *application.App }

func (d desktop) SaveFile(name string) (string, error) {
	return d.app.Dialog.SaveFile().SetFilename(name).PromptForSingleSelection()
}

Both blocks are trimmed from complete files that build and pass their tests: examples/wails3/main.go and examples/wails3/notes/service.go. Copy those for a runnable starting point; the desktop build needs cgo (see references/building.md).

  • application.NewService takes a pointer to a named, non-generic struct. Register one instance per type, in Options.Services or with app.RegisterService before Run. A service registered after Run starts is dropped and the error goes to `Options.
阅读完整来源 ↗