검색
기여하기

이 문서 편집

문서를 번역하거나 컴퓨터에서 전체 프로젝트를 여세요.

작업을 제출하기 전까지는 아무것도 게시되지 않습니다.

API 참조

Wails v3의 전체 API 문서

이 참조 문서 소개

이 문서는 Wails v3의 전체 API 참조입니다. 프레임워크에서 사용할 수 있는 모든 공개 형식, 메서드 및 옵션을 설명합니다.

구성:

API 규칙

Go API 규칙 - Go를 처음 접하는 개발자용

명명 규칙

  • 타입: PascalCase(예: WebviewWindow)
  • 메서드: PascalCase(예: SetTitle())
  • 옵션: PascalCase 구조체(예: WindowOptions)
  • 상수: PascalCase(예: WindowStartStateMaximised)

오류 처리

실패할 수 있는 대부분의 메서드는 마지막 반환값으로 error를 반환합니다. app.Run()은 애플리케이션이 종료될 때까지 실행을 차단하고 시작 과정에서 발생한 오류를 반환합니다:

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

창 생성은 오류를 반환하지 않습니다. app.Window.New()은 *WebviewWindow을 직접 반환합니다.

컨텍스트

서비스 수명 주기 메서드는 context.Context를 전달받습니다:

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

애플리케이션의 수명 주기 컨텍스트는 app.Context()을 통해 사용할 수 있습니다. RunWithContext은 없으므로 app.Run()을 호출하세요.

옵션 패턴

구성에는 옵션 구조체를 사용합니다:

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

JavaScript API 규칙

명명 규칙

  • 함수: camelCase(예: setTitle())
  • 상수: SCREAMINGSNAKECASE(예: WINDOW_EVENT_FOCUS)

기본 비동기 처리

모든 Go 메서드 호출은 Promise를 반환합니다.

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

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

오류 처리

Go 오류는 JavaScript 예외로 변환됩니다.

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

형식 안전성

TypeScript 정의는 자동으로 생성됩니다.

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

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

패키지 구조

text
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

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

JavaScript

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

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

형식 참조

공통 형식

go
// 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 { /* ... */ }

플랫폼별 차이

일부 API는 플랫폼에 따라 다르게 동작합니다.

기능 Windows macOS Linux
애플리케이션 메뉴 창 메뉴 모음 전역 메뉴 모음 창 메뉴 모음
시스템 트레이 알림 영역 메뉴 모음 시스템 트레이
Dock 해당 없음 ✅ 사용 가능 해당 없음
파일 대화 상자 네이티브 네이티브 네이티브(GTK)
투명도 ✅ 완전 지원 private_mac_apis 필요 ⚠️ 제한적

플랫폼별 동작은 각 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를 살펴보세요.

페이지 편집

마지막 업데이트: