Referência da API

Sobre esta referência

Esta é a referência completa da API do Wails v3. Ela documenta todos os tipos, métodos e opções públicos disponíveis no framework.

Organização:

• Aplicativo — APIs principais do aplicativo
• Janela — Criação e gerenciamento de janelas
• Menu — Menus do aplicativo, de contexto e da bandeja do sistema
• Eventos — Sistema de eventos e eventos integrados
• Caixas de diálogo — Caixas de diálogo de arquivos e mensagens
• Runtime do frontend — APIs do runtime do frontend
• CLI — Interface de linha de comando

Convenções da API

if err := app.Run(); err != nil {
    log.Fatal(err)
}

func (s *MyService) ServiceStartup(ctx context.Context, options application.ServiceOptions) error {
    // ctx is cancelled when the application is shutting down.
    return nil
}

app := application.New(application.Options{
    Name: "My App",
    Description: "A demo application",
    Services: []application.Service{
        application.NewService(&MyService{}),
    },
})

Convenções da API JavaScript

Nomenclatura

• Funções: camelCase (por exemplo, setTitle())
• Constantes: SCREAMINGSNAKECASE (por exemplo, WINDOW_EVENT_FOCUS)

Assíncrona por padrão

Todas as chamadas a métodos Go retornam Promises:

// Async/await (recommended)
const result = await MyService.DoSomething()

// Promise chain
MyService.DoSomething()
    .then(result => console.log(result))
    .catch(error => console.error(error))

Tratamento de erros

Erros do Go tornam-se exceções do JavaScript:

try {
    await MyService.MightFail()
} catch (error) {
    console.error('Go error:', error)
}

Segurança de tipos

As definições TypeScript são geradas automaticamente:

// Fully typed
import { Greet } from './bindings/GreetService'

const message: string = await Greet("World")

Estrutura dos pacotes

github.com/wailsapp/wails/v3/pkg/
├── application/          # Core application package
│   ├── application.go    # App type
│   ├── webview_window.go # Window management
│   ├── menu.go           # Menu types
│   ├── event_manager.go  # Event system
│   └── dialogs.go        # Dialog APIs
├── events/               # Event constants
└── services/             # Built-in services
    ├── dock/             # macOS dock (includes badge support)
    ├── fileserver/       # File-server service
    ├── kvstore/          # Key/value store
    ├── log/              # Structured logging service
    ├── notifications/    # Notifications service
    └── sqlite/           # SQLite service

Caminhos de importação

Go

import (
    "github.com/wailsapp/wails/v3/pkg/application"
    "github.com/wailsapp/wails/v3/pkg/events"
)

JavaScript

// Auto-generated bindings
import { MyMethod } from './bindings/MyService'

// Runtime APIs
import { Events, Window } from '@wailsio/runtime'

Referência de tipos

Tipos comuns

// Application
type App struct { /* ... */ }
type Options struct { /* ... */ }

// Window
type WebviewWindow struct { /* ... */ } // implements the Window interface
type WebviewWindowOptions struct { /* ... */ }

// Menu
type Menu struct { /* ... */ }
type MenuItem struct { /* ... */ }

// Events — there is no generic Event type; events are typed by source.
type ApplicationEvent struct { /* ... */ }
type WindowEvent struct { /* ... */ }
type CustomEvent struct { /* ... */ }
type EventListener struct { /* ... */ }

// Dialogs
type OpenFileDialogOptions struct { /* ... */ }
type SaveFileDialogOptions struct { /* ... */ }

// Window runtime
interface WindowOptions {
    title?: string
    width?: number
    height?: number
    // ...
}

// Events
type EventCallback = (data: any) => void

// Bindings (auto-generated)
export function MyMethod(arg: string): Promise<string>

Diferenças entre plataformas

Algumas APIs se comportam de maneiras diferentes dependendo da plataforma:

O comportamento específico de cada plataforma está documentado em cada seção da API.

Versionamento

O Wails v3 segue o versionamento semântico:

• Principal (v3.x.x): alterações incompatíveis
• Secundária (v3.x.x): novos recursos, com compatibilidade retroativa
• Correção (v3.x.x): correções de bugs, com compatibilidade retroativa

Status atual: Beta (API estável, aprimoramentos em andamento)

Política de descontinuação

Quando APIs são descontinuadas:

1. Marcadas na documentação com um aviso de descontinuação
2. Alternativa fornecida com um guia de migração
3. Mantidas por 1 versão principal antes da remoção
4. Avisos do compilador (quando possível)

Estabilidade da API

APIs estáveis ✅

Estas APIs são estáveis e seguras para uso em produção:

• APIs principais do aplicativo
• Gerenciamento de janelas
• Sistema de menus
• Sistema de eventos
• Caixas de diálogo de arquivos
• Bindings de serviços

APIs instáveis ⚠️

Estas APIs podem mudar antes da versão final:

• Algumas opções avançadas de janela
• Recursos específicos da plataforma
• Recursos experimentais

As APIs instáveis são identificadas na documentação.

Como obter ajuda

Dúvidas sobre a API

1. Consulte esta referência — Documentação completa da API
2. Consulte os exemplos — Exemplos no GitHub
3. Pesquise no Discord — Servidor do Discord
4. Pergunte à comunidade — Canal #help do Discord

Como relatar problemas na API

Encontrou um bug ou uma inconsistência?

1. Verifique os problemas existentes — Problemas no GitHub
2. Crie um relatório detalhado — Inclua o código, o erro e a plataforma
3. Forneça uma reprodução — Exemplo mínimo que demonstre o problema

Documentação relacionada

• Tutoriais — Aprenda criando aplicativos reais
• Guias — Guias orientados a tarefas para cenários comuns
• Recursos — Documentação de cada recurso
• Exemplos — Exemplos de código funcionais no GitHub

Navegue pela API: use a navegação à esquerda para explorar APIs específicas.