Référence de l’API

À propos de cette référence

Voici la référence complète de l’API de Wails v3. Elle documente chaque type, méthode et option publics disponibles dans le framework.

Organisation :

• Application — API principales de l’application
• Fenêtre — Création et gestion des fenêtres
• Menu — Menus d’application, contextuels et de la zone de notification
• Événements — Système d’événements et événements intégrés
• Boîtes de dialogue — Boîtes de dialogue de fichiers et de messages
• Runtime frontend — API du runtime frontend
• CLI — Interface en ligne de commande

Conventions de l’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{}),
    },
})

Conventions de l’API JavaScript

Nommage

• Fonctions : camelCase (par exemple, setTitle())
• Constantes : SCREAMINGSNAKECASE (par exemple, WINDOW_EVENT_FOCUS)

Asynchrone par défaut

Tous les appels de méthodes Go renvoient des promesses :

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

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

Gestion des erreurs

Les erreurs Go deviennent des exceptions JavaScript :

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

Sécurité des types

Les définitions TypeScript sont générées automatiquement :

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

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

Structure des paquets

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

Chemins d’importation

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'

Référence des types

Types courants

// 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>

Différences entre les plateformes

Certaines API se comportent différemment selon la plateforme :

Le comportement propre à chaque plateforme est documenté dans chaque section de l’API.

Gestion des versions

Wails v3 suit la gestion sémantique des versions :

• Majeure (v3.x.x) : changements incompatibles
• Mineure (v3.x.x) : nouvelles fonctionnalités rétrocompatibles
• Corrective (v3.x.x) : corrections de bogues rétrocompatibles

État actuel : bêta (API stable, améliorations en cours)

Politique d’obsolescence

Lorsque des API deviennent obsolètes :

1. Signalées dans la documentation par un avis d’obsolescence
2. Une solution de remplacement est fournie avec un guide de migration
3. Maintenues pendant 1 version majeure avant leur suppression
4. Avertissements du compilateur (lorsque cela est possible)

Stabilité des API

API stables ✅

Ces API sont stables et peuvent être utilisées en production en toute sécurité :

• API principales de l’application
• Gestion des fenêtres
• Système de menus
• Système d’événements
• Boîtes de dialogue de fichiers
• Liaisons de services

API instables ⚠️

Ces API peuvent changer avant la version finale :

• Certaines options avancées des fenêtres
• Fonctionnalités propres à chaque plateforme
• Fonctionnalités expérimentales

Les API instables sont signalées dans la documentation.

Obtenir de l’aide

Questions sur les API

1. Consultez cette référence – Documentation complète des API
2. Consultez les exemples – Exemples sur GitHub
3. Effectuez une recherche sur Discord – Serveur Discord
4. Interrogez la communauté – Canal Discord #help

Signaler des problèmes liés aux API

Vous avez trouvé un bogue ou une incohérence ?

1. Consultez les problèmes existants – Problèmes GitHub
2. Créez un rapport détaillé – Incluez le code, l’erreur et la plateforme
3. Fournissez une procédure de reproduction – Un exemple minimal qui illustre le problème

Documentation associée

• Tutoriels – Apprenez en créant de véritables applications
• Guides – Guides axés sur les tâches pour les scénarios courants
• Fonctionnalités – Documentation détaillée par fonctionnalité
• Exemples – Exemples de code fonctionnels sur GitHub

Parcourir les API : utilisez la navigation à gauche pour explorer des API spécifiques.