Panduan Events

CATATAN: Panduan ini masih dalam proses penyusunan

Panduan Events

Events adalah denyut nadi komunikasi di aplikasi Wails. Events memungkinkan berbagai bagian aplikasi Anda saling berkomunikasi tanpa ketergantungan yang ketat. Panduan ini akan memandu Anda melalui semua yang perlu diketahui tentang penggunaan events secara efektif di aplikasi Wails Anda.

Memahami Events Wails

Anggap events sebagai pesan yang disiarkan ke seluruh aplikasi Anda. Bagian mana pun dari aplikasi dapat mendengarkan pesan-pesan ini dan bereaksi sesuai kebutuhan. Ini sangat berguna untuk:

Merespons perubahan window: Mengetahui kapan window diminimalkan, dimaksimalkan, atau dipindahkan
Menangani system events: Bereaksi terhadap perubahan tema atau power events
Logika aplikasi kustom: Membuat events Anda sendiri untuk fitur seperti pembaruan data atau aksi pengguna
Komunikasi antar-komponen: Memungkinkan bagian berbeda dari aplikasi berkomunikasi tanpa ketergantungan langsung

Konvensi Penamaan Event

Semua events Wails mengikuti pola namespace untuk menunjukkan asalnya dengan jelas:

common: - Events lintas platform yang berfungsi di Windows, macOS, dan Linux
windows: - Events khusus Windows
mac: - Events khusus macOS
linux: - Events khusus Linux

Contoh:

common:WindowFocus - Window mendapat fokus (berfungsi di semua platform)
windows:APMSuspend - Sistem sedang suspend (hanya Windows)
mac:ApplicationDidBecomeActive - Aplikasi menjadi aktif (hanya macOS)

Memulai dengan Events

Mendengarkan Events (Frontend)

Kasus penggunaan paling umum adalah mendengarkan events di kode frontend Anda:

import { Events } from '@wailsio/runtime';

// Dengarkan saat window mendapat fokus
Events.On('common:WindowFocus', () => {
    console.log('Window is now focused!');
    // Mungkin refresh beberapa data atau lanjutkan animasi
});

// Dengarkan perubahan tema
Events.On('common:ThemeChanged', (event) => {
    console.log('Theme changed:', event.data);
    // Perbarui tema aplikasi Anda sesuai kebutuhan
});

// Dengarkan custom events dari backend Go Anda
Events.On('my-app:data-updated', (event) => {
    console.log('Data updated:', event.data);
    // Perbarui UI dengan data baru
});

Mengirim Events (Backend)

Dari kode Go Anda, Anda dapat mengirim events yang dapat didengarkan frontend:

package main

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

func (s *Service) UpdateData() {
    // Lakukan pemrosesan data...

    // Beri tahu frontend
    app := application.Get()
    app.Event.Emit("my-app:data-updated",
        map[string]interface{}{
            "timestamp": time.Now(),
            "count": 42,
        },
	)
}

Mengirim Events (Frontend)

Meskipun tidak seumum itu, Anda juga dapat mengirim events dari frontend yang dapat didengarkan kode Go:

import { Events } from '@wailsio/runtime';

// Event tanpa data
Events.Emit('myapp:close-window')

// Event dengan data
Events.Emit('myapp:disconnect-requested', 'id-123')

Jika Anda menggunakan TypeScript di frontend dan mendaftarkan events bertipe di kode Go, Anda akan mendapatkan autocomplete/pemeriksaan nama event dan pemeriksaan tipe data.

Menghapus Event Listener

Selalu bersihkan event listener saat sudah tidak diperlukan:

import { Events } from '@wailsio/runtime';

// Simpan referensi handler
const focusHandler = () => {
    console.log('Window focused');
};

// Tambahkan listener — tangkap fungsi unsubscribe yang dikembalikan
const unsubscribe = Events.On('common:WindowFocus', focusHandler);

// Nanti, hapus listener spesifik ini melalui unsubscribe yang dikembalikan
unsubscribe();

// Atau hapus SEMUA listener untuk satu (atau lebih) nama event — Events.Off hanya menerima string nama event
Events.Off('common:WindowFocus');
// Events.Off('common:WindowFocus', 'common:WindowLostFocus'); // variadic
// Events.OffAll(); // hapus setiap listener untuk setiap event (tanpa argumen)

Kasus Penggunaan Umum

1. Pause/Resume saat Window Fokus

Banyak aplikasi perlu menjeda aktivitas tertentu saat window kehilangan fokus:

import { Events } from '@wailsio/runtime';

let animationRunning = true;

Events.On('common:WindowLostFocus', () => {
    animationRunning = false;
    pauseBackgroundTasks();
});

Events.On('common:WindowFocus', () => {
    animationRunning = true;
    resumeBackgroundTasks();
});

2. Merespons Perubahan Tema

Jaga aplikasi Anda selaras dengan tema sistem:

import { Events } from '@wailsio/runtime';

Events.On('common:ThemeChanged', (event) => {
    const isDarkMode = event.data.isDarkMode;

    if (isDarkMode) {
        document.body.classList.add('dark-theme');
        document.body.classList.remove('light-theme');
    } else {
        document.body.classList.add('light-theme');
        document.body.classList.remove('dark-theme');
    }
});

3. Menangani File Drop

Buat aplikasi Anda menerima file yang di-drag:

import { Events } from '@wailsio/runtime';

Events.On('common:WindowFilesDropped', (event) => {
    const files = event.data.files;

    files.forEach(file => {
        console.log('File dropped:', file);
        // Proses file yang di-drop
        handleFileUpload(file);
    });
});

4. Manajemen Lifecycle Window

Tanggapi perubahan state window:

import { Events } from '@wailsio/runtime';

Events.On('common:WindowClosing', () => {
    // Simpan data pengguna sebelum menutup
    saveApplicationState();

    // Anda juga bisa mencegah penutupan dengan mengembalikan false
    // dari window close handler yang terdaftar
});

Events.On('common:WindowMaximise', () => {
    // Sesuaikan UI untuk tampilan maksimal
    adjustLayoutForMaximized();
});

Events.On('common:WindowRestore', () => {
    // Kembalikan UI ke state normal
    adjustLayoutForNormal();
});

5. Fitur Khusus Platform

Tangani events khusus platform saat diperlukan:

import { Events } from '@wailsio/runtime';

// Manajemen daya khusus Windows
Events.On('windows:APMSuspend', () => {
    console.log('System is going to sleep');
    saveState();
});

Events.On('windows:APMResumeSuspend', () => {
    console.log('System woke up');
    refreshData();
});

// Lifecycle aplikasi khusus macOS
Events.On('mac:ApplicationWillTerminate', () => {
    console.log('App is about to quit');
    performCleanup();
});

Membuat Custom Events

Anda dapat membuat events sendiri untuk kebutuhan spesifik aplikasi.

Backend (Go)

// Kirim custom event saat data berubah

func (s *Service) ProcessUserData(userData UserData) error {
    // Proses data...

    app := application.Get()
    // Beri tahu semua listener
    app.Event.Emit("user:data-processed",
        map[string]interface{}{
            "userId": userData.ID,
            "status": "completed",
            "timestamp": time.Now(),
        },
    )
    return nil
}

// Kirim pembaruan berkala
func (s *Service) StartMonitoring() {
    app := application.Get()
    ticker := time.NewTicker(5 * time.Second)
    go func() {
        for range ticker.C {
            stats := s.collectStats()
            app.Event.Emit("monitor:stats-updated", stats)
        }
    }()
}

Frontend (JavaScript)

import { Events } from '@wailsio/runtime';

// Dengarkan custom events Anda
Events.On('user:data-processed', (event) => {
    const { userId, status, timestamp } = event.data;

    showNotification(`User ${userId} processing ${status}`);
    updateUIWithNewData();
});

Events.On('monitor:stats-updated', (event) => {
    updateDashboard(event.data);
});

Event Bertipe dengan Type Safety

Wails v3 mendukung events bertipe dengan type safety TypeScript penuh melalui registrasi event dan pembuatan binding otomatis.

Mendaftarkan Custom Events

Panggil application.RegisterEvent saat init untuk mendaftarkan nama custom event beserta tipe datanya:

package main

import "github.com/wailsapp/wails/v3/pkg/application"

type UserLoginData struct {
    UserID   string
    Username string
    LoginTime string
}

type MonitorStats struct {
    CPUUsage    float64
    MemoryUsage float64
}

func init() {
    // Daftarkan events beserta tipe datanya
    application.RegisterEvent[UserLoginData]("user:login")
    application.RegisterEvent[MonitorStats]("monitor:stats")

    // Daftarkan events tanpa data (void events)
    application.RegisterEvent[application.Void]("app:ready")
}

Manfaat Registrasi Event

Setelah terdaftar, argumen data yang diteruskan ke Event.Emit diperiksa tipenya terhadap tipe yang ditentukan. Jika tidak cocok:

Error dikirim dan dicatat (atau diteruskan ke error handler yang terdaftar)
Event yang bermasalah tidak akan dipropagasi
Ini memastikan field data dari events terdaftar selalu dapat di-assign ke tipe yang dideklarasikan

Strict Mode

Gunakan build tag strictevents untuk mengaktifkan peringatan event yang belum terdaftar saat development:

bash

go build -tags strictevents

Dengan strict mode aktif, runtime mengirim paling banyak satu peringatan per nama event yang belum terdaftar untuk menghindari spam log.

Pembuatan Binding TypeScript

Generator binding menghasilkan definisi TypeScript dan glue code untuk dukungan event bertipe transparan di frontend.

1. Siapkan Vite Plugin

Di vite.config.ts Anda:

import { defineConfig } from 'vite'
import wails from '@wailsio/runtime/plugins/vite'

export default defineConfig({
  plugins: [wails()],
})

2. Generate Bindings

Jalankan generator binding:

bash

wails3 generate bindings

Ini membuat file TypeScript di direktori frontend Anda dengan event creator bertipe dan interface data.

3. Gunakan Event Bertipe di Frontend

import { Events } from '@wailsio/runtime'
import { UserLogin, MonitorStats } from './bindings/events'

// Emisi event type-safe dengan autocomplete
Events.Emit(UserLogin({
    UserID: "123",
    Username: "john_doe",
    LoginTime: new Date().toISOString()
}))

// Pendengaran event type-safe
Events.On(UserLogin, (event) => {
    // event.data bertipe UserLoginData
    console.log(`User ${event.data.Username} logged in`)
})

Events.On(MonitorStats, (event) => {
    // event.data bertipe MonitorStats
    updateDashboard({
        cpu: event.data.CPUUsage,
        memory: event.data.MemoryUsage
    })
})

Event bertipe menyediakan:

Autocomplete untuk nama event
Type checking untuk data event
Compile-time errors untuk tipe data yang tidak cocok
IntelliSense documentation

Referensi Event

Common Events (Lintas platform)

Events ini berfungsi di semua platform:

Event	Deskripsi	Kapan Digunakan
`common:ApplicationStarted`	Aplikasi telah sepenuhnya dimulai	Inisialisasi aplikasi, muat state tersimpan
`common:WindowRuntimeReady`	Runtime Wails siap	Mulai memanggil Wails API
`common:ThemeChanged`	Tema sistem berubah	Perbarui tampilan aplikasi
`common:SystemWillSleep`	Sistem akan suspend	Flush state, tutup socket
`common:SystemDidWake`	Sistem bangun dari suspend	Reconnect, refresh data yang sudah usang
`common:WindowFocus`	Window mendapat fokus	Lanjutkan aktivitas, refresh data
`common:WindowLostFocus`	Window kehilangan fokus	Jeda aktivitas, simpan state
`common:WindowMinimise`	Window diminimalkan	Jeda rendering, kurangi penggunaan resource
`common:WindowMaximise`	Window dimaksimalkan	Sesuaikan layout untuk layar penuh
`common:WindowRestore`	Window dipulihkan dari min/max	Kembali ke layout normal
`common:WindowClosing`	Window akan ditutup	Simpan data, bersihkan resource
`common:WindowFilesDropped`	File di-drop ke window	Tangani impor file
`common:WindowDidResize`	Window di-resize	Sesuaikan layout, render ulang chart
`common:WindowDidMove`	Window dipindahkan	Perbarui fitur yang bergantung posisi

Events Khusus Platform

Windows Events

Events penting untuk aplikasi Windows:

Event	Deskripsi	Kasus Penggunaan
`windows:SystemThemeChanged`	Tema Windows berubah	Perbarui warna aplikasi
`windows:APMSuspend`	Sistem suspend	Simpan state, jeda operasi
`windows:APMResumeAutomatic`	Sistem bangun (selalu fire saat resume)	Pulihkan state, refresh data
`windows:APMResumeSuspend`	Sistem bangun via input pengguna (setelah `APMResumeAutomatic`)	Bedakan wake yang dipicu pengguna
`windows:APMPowerStatusChange`	Status daya berubah	Sesuaikan pengaturan performa

macOS Events

Events aplikasi macOS penting:

Event	Deskripsi	Kasus Penggunaan
`mac:ApplicationDidBecomeActive`	Aplikasi menjadi aktif	Lanjutkan operasi
`mac:ApplicationDidResignActive`	Aplikasi menjadi tidak aktif	Jeda operasi
`mac:ApplicationWillTerminate`	Aplikasi akan quit	Pembersihan akhir
`mac:ApplicationWillSleep`	Sistem akan suspend	Simpan state, tutup socket
`mac:ApplicationDidWake`	Sistem bangun	Reconnect, refresh
`mac:ApplicationScreensDidSleep`	Display tidur	Jeda rendering (berbeda dari system sleep)
`mac:ApplicationScreensDidWake`	Display bangun	Lanjutkan rendering
`mac:WindowDidEnterFullScreen`	Masuk fullscreen	Sesuaikan UI untuk fullscreen
`mac:WindowDidExitFullScreen`	Keluar fullscreen	Pulihkan UI normal

Linux Events

Events window Linux inti:

Event	Deskripsi	Kasus Penggunaan
`linux:SystemThemeChanged`	Tema desktop berubah	Perbarui tema aplikasi
`linux:SystemWillSleep`	Sistem akan suspend (logind)	Simpan state
`linux:SystemDidWake`	Sistem bangun (logind)	Reconnect, refresh
`linux:WindowFocusIn`	Window mendapat fokus	Lanjutkan aktivitas
`linux:WindowFocusOut`	Window kehilangan fokus	Jeda aktivitas
`linux:WindowLoadStarted`	WebView mulai loading	Tampilkan indikator loading
`linux:WindowLoadRedirected`	WebView di-redirect	Lacak redirect navigasi
`linux:WindowLoadCommitted`	WebView committed load	Konten sedang diterima
`linux:WindowLoadFinished`	WebView selesai loading	Sembunyikan indikator loading, inject JS/CSS

Praktik Terbaik

1. Gunakan Event Namespace

Saat membuat custom events, gunakan namespace untuk menghindari konflik:

import { Events } from '@wailsio/runtime';

// Baik — events dengan namespace
Events.Emit('myapp:user:login');
Events.Emit('myapp:data:updated');
Events.Emit('myapp:network:connected');

// Hindari — nama generik yang mungkin konflik
Events.Emit('login');
Events.Emit('update');

2. Bersihkan Listener

Selalu hapus event listener saat komponen unmount:

import { Events } from '@wailsio/runtime';

// Contoh React
useEffect(() => {
    const handler = (event) => {
        // Tangani event
    };

    const off = Events.On('common:WindowDidResize', handler);

    // Cleanup — panggil unsubscribe yang dikembalikan Events.On
    return () => {
        off();
    };
}, []);

3. Tangani Perbedaan Platform

Periksa ketersediaan platform saat menggunakan events khusus platform:

import { Events } from '@wailsio/runtime';

// Events khusus platform dapat didaftarkan tanpa syarat;
// mereka hanya tidak akan pernah fire di platform yang tidak didukung.
Events.On('windows:APMSuspend', handleSuspend);
Events.On('mac:ApplicationWillTerminate', handleTerminate);

4. Jangan Berlebihan Menggunakan Events

Meskipun events sangat powerful, jangan gunakan untuk segalanya:

✅ Gunakan events untuk: Notifikasi sistem, perubahan lifecycle, broadcast update
❌ Hindari events untuk: Return fungsi langsung, update komponen tunggal, operasi sinkron

Debugging Events

Untuk debug masalah event:

import { Events } from '@wailsio/runtime';

// Log semua events (development saja)
if (isDevelopment) {
    const originalOn = Events.On;
    Events.On = function(eventName, handler) {
        console.log(`[Event Registered] ${eventName}`);
        return originalOn.call(this, eventName, function(event) {
            console.log(`[Event Fired] ${eventName}`, event);
            return handler(event);
        });
    };
}

Sumber Kebenaran

Daftar lengkap events yang tersedia dapat ditemukan di source code Wails:

Frontend events: v3/internal/runtime/desktop/@wailsio/runtime/src/event_types.ts
Backend events: v3/pkg/events/events.go

Selalu rujuk file-file ini untuk nama event dan ketersediaan terbaru.

Ringkasan

Events di Wails menyediakan cara yang powerful dan terdecouple untuk menangani komunikasi di aplikasi Anda. Dengan mengikuti pola dan praktik dalam panduan ini, Anda dapat membangun aplikasi responsif yang aware terhadap platform dan bereaksi mulus terhadap perubahan sistem serta interaksi pengguna.

Ingat: mulai dengan common events untuk kompatibilitas lintas platform, tambahkan events khusus platform saat diperlukan, dan selalu bersihkan event listener untuk mencegah memory leak.