Справочник по API

Об этом справочнике

Это полный справочник по API Wails v3. В нём документированы все общедоступные типы, методы и параметры, имеющиеся во фреймворке.

Структура:

• Приложение — основные API приложения
• Окно — создание окон и управление ими
• Меню — меню приложения, контекстные меню и меню в области уведомлений
• События — система событий и встроенные события
• Диалоговые окна — диалоговые окна для работы с файлами и сообщениями
• Среда выполнения фронтенда — API среды выполнения фронтенда
• CLI — интерфейс командной строки

Соглашения 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{}),
    },
})

Соглашения API JavaScript

Именование

• Функции: camelCase (например, setTitle())
• Константы: SCREAMINGSNAKECASE (например, WINDOW_EVENT_FOCUS)

Асинхронность по умолчанию

Все вызовы методов Go возвращают Promise:

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

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

Обработка ошибок

Ошибки Go преобразуются в исключения JavaScript:

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

Безопасность типов

Определения TypeScript создаются автоматически:

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

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

Структура пакетов

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

Пути импорта

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'

Справочник типов

Общие типы

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

Различия между платформами

Поведение некоторых API различается в зависимости от платформы:

Особенности поведения на разных платформах документированы в каждом разделе API.

Управление версиями

Wails v3 следует правилам семантического версионирования:

• Мажорная версия (v3.x.x): изменения, нарушающие обратную совместимость
• Минорная версия (v3.x.x): новые возможности с сохранением обратной совместимости
• Патч-версия (v3.x.x): исправления ошибок с сохранением обратной совместимости

Текущий статус: бета-версия (API стабилен, доработка продолжается)

Политика устаревания

Когда API объявляются устаревшими:

1. Помечаются в документации уведомлением об устаревании
2. Предоставляется альтернатива с руководством по переходу
3. Поддерживаются в течение 1 основной версии перед удалением
4. Предупреждения компилятора (где возможно)

Стабильность API

Стабильные API ✅

Эти API стабильны и подходят для использования в рабочей среде:

• Основные API приложения
• Управление окнами
• Система меню
• Система событий
• Диалоговые окна выбора файлов
• Привязки сервисов

Нестабильные API ⚠️

Эти API могут измениться до финального выпуска:

• Некоторые расширенные параметры окон
• Возможности, зависящие от платформы
• Экспериментальные возможности

Нестабильные API помечены в документации.

Получение помощи

Вопросы об API

1. Ознакомьтесь с этим справочником — полной документацией по API
2. Изучите примеры — примеры на GitHub
3. Выполните поиск в Discord — сервер Discord
4. Задайте вопрос сообществу — в канале Discord #help

Сообщение о проблемах с API

Обнаружили ошибку или несоответствие?

1. Проверьте существующие обращения — обращения на GitHub
2. Составьте подробный отчёт — укажите код, ошибку и платформу
3. Предоставьте способ воспроизведения — минимальный пример, демонстрирующий проблему

Связанная документация

• Учебные материалы — обучение на примере создания реальных приложений
• Руководства — практические инструкции для типовых сценариев
• Возможности — документация по каждой возможности
• Примеры — рабочие примеры кода на GitHub

Просмотр API: используйте навигацию слева, чтобы изучить конкретные API.