wails运行时功能介绍

记录一些运行时的功能，方便开发的时候，及时查看，详细的功能请查阅官网

应用程序

JavaScript 库可通过 window.runtime 提供给前端。 使用 开发 模式时会生成一个运行时包，该包为运行时提供 TypeScript 声明。 这应该位于您的前端目录的wailsjs目录中。

隐藏

Go: Hide(ctx context.Context)
JS: Hide()

隐藏应用程序。

注意

Hide 在 Mac 上，这将以与标准 Mac 应用程序中的菜单项相同的方式隐藏应用程序。 这与隐藏窗口不同，但应用程序仍处于前台。 对于 Windows 和 Linux，这与 WindowHide 相同。

显示

显示应用程序。

注意

在 Mac 上，这会将应用程序带回前台。 对于 Windows 和 Linux，这目前与 WindowShow 相同。

Go: Show(ctx context.Context)
JS: Show()

退出

退出应用程序。

Go: Quit(ctx context.Context)
JS: Quit()

环境

返回当前环境的详细信息。

Go: Environment(ctx context.Context) EnvironmentInfo
JS: Environment(): Promise<EnvironmentInfo>

环境信息

Go:

type EnvironmentInfo struct {
    BuildType string
    Platform  string
    Arch      string
}

JS:

interface EnvironmentInfo {
  buildType: string;
  platform: string;
  arch: string;
}

Events 事件

Wails 运行时提供了一个统一的事件系统，其中事件可以由 Go 或 JavaScript 发出或接收。 可选地，数据可以与事件一起传递。 侦听器将接收本地数据类型中的数据。

EventsOn 添加事件侦听器

此方法为给定的事件名称设置一个侦听器。 当 触发指定事件 名为 eventName 类型的事件时，将触发回调。 与触发事件一起发送的任何其他数据都将传递给回调。 它返回 一个函数来取消侦听器。

Go: EventsOn(ctx context.Context, eventName string, callback func(optionalData ...interface{})) func()
JS: EventsOn(eventName string, callback function(optionalData?: any)): () => void

EventsOff 移除事件侦听器

此方法取消注册给定事件名称的侦听器，可选地，可以通过 additionalEventNames 取消注册多个侦听器。

Go: EventsOff(ctx context.Context, eventName string, additionalEventNames ...string)
JS: EventsOff(eventName string, ...additionalEventNames)

EventsOnce 添加只触发一次的事件侦听器

此方法为给定的事件名称设置一个侦听器，但只会触发一次。 它返回 一个函数来取消侦听器。

Go: EventsOnce(ctx context.Context, eventName string, callback func(optionalData ...interface{})) func()
JS: EventsOnce(eventName string, callback function(optionalData?: any)): () => void

EventsOnMultiple 添加指定对多触发次数的事件侦听器

此方法为给定的事件名称设置一个侦听器，但最多只能触发 counter 次。 它返回 一个函数来取消侦听器。

Go: EventsOnMultiple(ctx context.Context, eventName string, callback func(optionalData ...interface{}), counter int) func()
JS: EventsOnMultiple(eventName string, callback function(optionalData?: any), counter int): () => void

EventsEmit 触发指定事件

此方法触发指定的事件。 可选数据可以与事件一起传递。 这将触发任意事件侦听器。

Go: EventsEmit(ctx context.Context, eventName string, optionalData ...interface{})
JS: EventsEmit(eventName: string, ...optionalData: any)

Log 日志

Wails 运行时提供了一种可以从 Go 或 JavaScript 调用日志记录的机制。 像大多数记录器一样，有许多日志级别：

• Trace（追踪）
• Debug（调试）
• Info（信息）
• Warning（警告）
• Error（错误）
• Fatal（致命）

记录器将输出当前或更高日志级别的任何日志消息。 示例：Debug日志级别将输出除Trace消息之外的所有消息。

LogPrint Print 日志

将给定的消息记录为原始消息。

Go: LogPrint(ctx context.Context, message string)
JS: LogPrint(message: string)

LogPrintf 格式化 Print 日志

将给定的消息记录为原始消息。

Go: LogPrintf(ctx context.Context, format string, args ...interface{})

LogTrace Trace 日志

在 Trace 日志级别记录给定的消息。

Go: LogTrace(ctx context.Context, message string)
JS: LogTrace(message: string)

LogTracef 格式化 Trace 日志

在 Trace 日志级别记录给定的消息。

Go: LogTracef(ctx context.Context, format string, args ...interface{})

LogDebug Debug 日志

在 Debug 日志级别记录给定的消息。

Go: LogDebug(ctx context.Context, message string)
JS: LogDebug(message: string)

LogDebugf 格式化 Debug 日志

在 Debug 日志级别记录给定的消息。

Go: LogDebugf(ctx context.Context, format string, args ...interface{})

LogInfo Info 日志

在Info日志级别记录给定的消息。

Go: LogInfo(ctx context.Context, message string)
JS: LogInfo(message: string)

LogInfof 格式化 Info 日志

在Info日志级别记录给定的消息。

Go: LogInfof(ctx context.Context, format string, args ...interface{})

LogWarning Warning 日志

在 Warning 日志级别记录给定的消息。

Go: LogWarning(ctx context.Context, message string)
JS: LogWarning(message: string)

LogWarningf 格式化 Warning 日志

在 Warning 日志级别记录给定的消息。

Go: LogWarningf(ctx context.Context, format string, args ...interface{})

LogError Error 日志

在 Error 日志级别记录给定的消息。

Go: LogError(ctx context.Context, message string)
JS: LogError(message: string)

LogErrorf 格式化 Error 日志

在 Error 日志级别记录给定的消息。

Go: LogErrorf(ctx context.Context, format string, args ...interface{})

LogFatal Fatal 日志

在 Fatal 日志级别记录给定的消息。

Go: LogFatal(ctx context.Context, message string)
JS: LogFatal(message: string)

LogFatalf 格式化 Fatal 日志

在 Fatal 日志级别记录给定的消息。

Go: LogFatalf(ctx context.Context, format string, args ...interface{})

LogSetLogLevel 设置日志级别

设置日志级别。 在 JavaScript 中，该数字与以下日志级别有关：

值	日志等级
1	Trace（追踪）
2	Debug（调试）
3	Info（信息）
4	Warning（警告）
5	Error（错误）

Go: LogSetLogLevel(ctx context.Context, level logger.LogLevel)
JS: LogSetLogLevel(level: number)

使用自定义日志

可以通过使用应用程序参数选项 日志 提供自定义记录器来使用它。 唯一的要求是记录器实现在 github.com/wailsapp/wails/v2/pkg/logger 里 logger.Logger 定义的接口：

logger.go

type Logger interface {
    Print(message string)
    Trace(message string)
    Debug(message string)
    Info(message string)
    Warning(message string)
    Error(message string)
    Fatal(message string)
}

Window 窗口

这些方法可以控制应用程序窗口。

WindowSetTitle 窗口标题

设置窗口标题栏中的文本。

Go: WindowSetTitle(ctx context.Context, title string)
JS: WindowSetTitle(title: string)

WindowFullscreen 窗口全屏

使窗口全屏。

Go: WindowFullscreen(ctx context.Context)
JS: WindowFullscreen()

WindowUnfullscreen 窗口取消全屏

恢复全屏之前的先前窗口尺寸和位置。

Go: WindowUnfullscreen(ctx context.Context)
JS: WindowUnfullscreen()

WindowIsFullscreen 窗口是否全屏

如果窗口是全屏的，则返回 true。

Go: WindowIsFullscreen(ctx context.Context) bool
JS: WindowIsFullscreen() bool

WindowCenter 窗口居中

使窗口在当前窗口所在的监视器上居中。

Go: WindowCenter(ctx context.Context)
JS: WindowCenter()

WindowExecJS 窗口执行JS代码

在窗口中执行任意 JS 代码。

此方法在浏览器中异步运行代码并立即返回。 如果脚本导致任何错误，它们将只在浏览器控制台中可用。

Go: WindowExecJS(ctx context.Context, js string)

WindowReload 窗口重新加载

执行“重新加载”（重新加载当前页面）。

Go: WindowReload(ctx context.Context)
JS: WindowReload()

WindowReloadApp 重新加载应用程序前端

重新加载应用程序前端。

Go: WindowReloadApp(ctx context.Context)
JS: WindowReloadApp()

WindowSetSystemDefaultTheme 窗口设置系统默认主题

仅限 Windows。

Go: WindowSetSystemDefaultTheme(ctx context.Context)
JS: WindowSetSystemDefaultTheme()

将窗口主题设置为系统默认值（暗/亮）。

WindowSetLightTheme 窗口设置浅色主题

仅限 Windows。

Go: WindowSetLightTheme(ctx context.Context)
JS: WindowSetLightTheme()

将窗口主题设置为浅色。

WindowSetDarkTheme 窗口设置深色主题

仅限 Windows。

Go: WindowSetDarkTheme(ctx context.Context)
JS: WindowSetDarkTheme()

将窗口主题设置为深色。

WindowShow 显示窗口

显示窗口，如果它当前是隐藏的。

Go: WindowShow(ctx context.Context)
JS: WindowShow()

WindowHide 隐藏窗口

如果当前可见，则隐藏窗口。

Go: WindowHide(ctx context.Context)
JS: WindowHide()

WindowIsNormal 窗口是否为正常

如果窗口未最小化、最大化或全屏，则返回 true。

Go: WindowIsNormal(ctx context.Context) bool
JS: WindowIsNormal() bool

WindowSetSize 设置窗口尺寸

设置窗口的宽度和高度。

Go: WindowSetSize(ctx context.Context, width int, height int)
JS: WindowSetSize(width: number, height: number)

WindowGetSize 获取窗口尺寸

获取窗口的宽度和高度。

Go: WindowGetSize(ctx context.Context) (width int, height int)
JS: WindowGetSize() : Size

WindowSetMinSize 设置窗口最小尺寸

设置窗口最小尺寸。 如果窗口当前小于给定尺寸，将调整窗口大小。

设置大小 0,0 将禁用此约束。

Go: WindowSetMinSize(ctx context.Context, width int, height int)
JS: WindowSetMinSize(width: number, height: number)

WindowSetMaxSize 设置窗口最大尺寸

设置窗口最大尺寸。 如果窗口当前大于给定尺寸，将调整窗口大小。

设置大小 0,0 将禁用此约束。

Go: WindowSetMaxSize(ctx context.Context, width int, height int)
JS: WindowSetMaxSize(width: number, height: number)

WindowSetAlwaysOnTop 设置窗口置顶

设置窗口置顶或取消置顶。

Go: WindowSetAlwaysOnTop(ctx context.Context, b bool)
JS: WindowSetAlwaysOnTop(b: Boolen)

WindowSetPosition 设置窗口位置

设置相对于窗口当前所在监视器的窗口位置。

Go: WindowSetPosition(ctx context.Context, x int, y int)
JS: WindowSetPosition(x: number, y: number)

WindowGetPosition 获取窗口位置

获取相对于窗口当前所在监视器的窗口位置。

Go: WindowGetPosition(ctx context.Context) (x int, y int)
JS: WindowGetPosition() : Position

WindowMaximise 窗口最大化

最大化窗口以填满屏幕。

Go: WindowMaximise(ctx context.Context)
JS: WindowMaximise()

WindowUnmaximise 窗口取消最大化

将窗口恢复到最大化之前的尺寸和位置。

Go: WindowUnmaximise(ctx context.Context)
JS: WindowUnmaximise()

WindowIsMaximised 窗口是否最大化

如果窗口最大化，则返回 true。

Go: WindowIsMaximised(ctx context.Context) bool
JS: WindowIsMaximised() bool

WindowToggleMaximise 窗口最大化切换

在最大化和未最大化之间切换。

Go: WindowToggleMaximise(ctx context.Context)
JS: WindowToggleMaximise()

WindowMinimise 窗口最小化。

最小化窗口。

Go: WindowMinimise(ctx context.Context)
JS: WindowMinimise()

WindowUnminimise 窗口取消最小化

将窗口恢复到最小化之前的尺寸和位置。

Go: WindowUnminimise(ctx context.Context)
JS: WindowUnminimise()

WindowIsMinimised 窗口是否最小化

如果窗口最小化，则返回 true。

Go: WindowIsMinimised(ctx context.Context) bool
JS: WindowIsMinimised() bool

WindowSetBackgroundColour 窗口设置背景色

将窗口的背景颜色设置为给定的 RGBA 颜色定义。 这种颜色将显示所有透明像素。

R、G、B 和 A 的有效值为 0-255。

Windows

在 Windows 上，仅支持 0 或 255 的 alpha 值。 任何非 0 的值都将被视为 255。

Go: WindowSetBackgroundColour(ctx context.Context, R, G, B, A uint8)
JS: WindowSetBackgroundColour(R, G, B, A)

WindowPrint

Opens tha native print dialog.

Go: WindowPrint(ctx context.Context)
JS: WindowPrint()

TypeScript 对象定义

Position（位置）

interface Position {
  x: number;
  y: number;
}

Size（尺寸）

interface Size {
  w: number;
  h: number;
}

Dialog 对话框：

运行时的这一部分提供对原生对话框的调用，例如文件选择器和消息框。

JavaScript

JS 运行时当前不支持对话框。

OpenDirectoryDialog 打开选择目录对话框

打开一个对话框，提示用户选择目录。 可以使用 打开选择文件对话框参数选项 进行自定义。

Go: OpenDirectoryDialog(ctx context.Context, dialogOptions OpenDialogOptions) (string, error)

返回值: 所选目录（如果用户取消则为空白）或错误

OpenFileDialog 打开选择文件对话框

打开一个对话框，提示用户选择文件。 可以使用 打开选择文件对话框参数选项 进行自定义。

Go: OpenFileDialog(ctx context.Context, dialogOptions OpenDialogOptions) (string, error)

返回值: 所选文件（如果用户取消则为空白）或错误

OpenMultipleFilesDialog 打开选择多文件对话框

打开一个对话框，提示用户选择多个文件。 可以使用 打开选择文件对话框参数选项 进行自定义。

Go: OpenMultipleFilesDialog(ctx context.Context, dialogOptions OpenDialogOptions) ([]string, error)

返回值: 选定的文件（如果用户取消则为 nil）或错误

SaveFileDialog 保存文件对话框

打开一个对话框，提示用户选择文件名以进行保存。 可以使用 保存文件对话框参数选项 自定义。

Go: SaveFileDialog(ctx context.Context, dialogOptions SaveDialogOptions) (string, error)

返回值: 所选文件（如果用户取消则为空白）或错误

MessageDialog 消息对话框

使用消息对话框显示消息。 可以使用 消息对话框参数选项 进行自定义。

Go: MessageDialog(ctx context.Context, dialogOptions MessageDialogOptions) (string, error)

返回值: 所选按钮的文本或错误

参数选项

打开选择文件对话框参数选项

type OpenDialogOptions struct {
    DefaultDirectory           string
    DefaultFilename            string
    Title                      string
    Filters                    []FileFilter
    ShowHiddenFiles            bool
    CanCreateDirectories       bool
    ResolvesAliases            bool
    TreatPackagesAsDirectories bool
}

字段	描述	Win	Mac	Lin
DefaultDirectory	对话框打开时显示的目录	✅	✅	✅
DefaultFilename	默认文件名	✅	✅	✅
Title	对话框的标题	✅	✅	✅
Filters	文件过滤器列表	✅	✅	✅
ShowHiddenFiles	显示系统隐藏的文件		✅	✅
CanCreateDirectories	允许用户创建目录		✅
ResolvesAliases	如果为 true，则返回文件而不是别名		✅
TreatPackagesAsDirectories	允许导航到包		✅

保存文件对话框参数选项

type SaveDialogOptions struct {
    DefaultDirectory           string
    DefaultFilename            string
    Title                      string
    Filters                    []FileFilter
    ShowHiddenFiles            bool
    CanCreateDirectories       bool
    TreatPackagesAsDirectories bool
}

字段	描述	Win	Mac	Lin
DefaultDirectory	对话框打开时显示的目录	✅	✅	✅
DefaultFilename	默认文件名	✅	✅	✅
Title	对话框的标题	✅	✅	✅
Filters	文件过滤器列表	✅	✅	✅
ShowHiddenFiles	显示系统隐藏的文件		✅	✅
CanCreateDirectories	允许用户创建目录		✅
TreatPackagesAsDirectories	允许导航到包		✅

消息对话框参数选项

type MessageDialogOptions struct {
    Type          DialogType
    Title         string
    Message       string
    Buttons       []string
    DefaultButton string
    CancelButton  string
}

字段	描述	Win	Mac	Lin
类型	消息对话框的类型，例如问题、信息…	✅	✅	✅
Title	对话框的标题	✅	✅	✅
Message	向用户显示的消息	✅	✅	✅
Buttons	按钮标题列表		✅
DefaultButton	带有此文本的按钮应被视为默认按钮。 必定 return。	✅*	✅
CancelButton	带有此文本的按钮应被视为取消。 必定 escape		✅

Windows

Windows 具有标准对话框类型，其中的按钮不可自定义。 返回的值将是以下之一：“Ok”、“Cancel”、“Abort”、“Retry”、“Ignore”、“Yes”、“No”、“Try Again"或"Continue”。

对于问题对话框，默认按钮是 “是”，取消按钮是 “否”。 可以通过将 默认按钮 值设置为 "否" 来改变这一点。

示例：

    result, err := runtime.MessageDialog(a.ctx, runtime.MessageDialogOptions{
        Type:          runtime.QuestionDialog,
        Title:         "Question",
        Message:       "Do you want to continue?",
        DefaultButton: "No",
    })

Linux

Linux 有标准的对话框类型，其中的按钮是不可定制的。 返回的值将是以下之一：“Ok”、“Cancel”、“Yes”、“No”

Mac

Mac 上的消息对话框最多可以指定 4 个按钮。 如果没有 DefaultButton 或 CancelButton 给出，第一个按钮被认为是默认的并绑定到 return 键。

对于以下代码：

selection, err := runtime.MessageDialog(b.ctx, runtime.MessageDialogOptions{
    Title:        "It's your turn!",
    Message:      "Select a number",
    Buttons:      []string{"one", "two", "three", "four"},
})

第一个按钮显示为默认值：

Menu 菜单

这些方法与应用程序菜单相关。

JavaScript

JS 运行时当前不支持菜单。

MenuSetApplicationMenu 设置应用程序菜单

将应用程序菜单设置为给定的 菜单。

Go: MenuSetApplicationMenu(ctx context.Context, menu *menu.Menu)

MenuUpdateApplicationMenu 更新应用程序菜单

获取传递给 MenuSetApplicationMenu 的菜单的任意更改更新应用程序菜单。

Go: MenuUpdateApplicationMenu(ctx context.Context)

Browser 浏览器：

这些方法与系统浏览器相关。

BrowserOpenURL 浏览器打开 URL

使用系统默认浏览器打开给定的 URL。

Go: BrowserOpenURL(ctx context.Context, url string)
JS: BrowserOpenURL(url string)

Clipboard 剪贴板：

运行时的这一部分提供了对操作系统剪贴板的访问。
当前实现仅处理文本。

ClipboardGetText 剪贴板获取文本

从剪切板读取当前存储的文本。

Go: ClipboardGetText(ctx context.Context) (string, error)
返回: 一个字符串（如果剪贴板为空，将返回一个空字符串）或一个错误。

JS: ClipboardGetText(): Promise<string>
返回: 带有字符串结果的 Promise（如果剪贴板为空，将返回空字符串）。

ClipboardSetText 剪贴板设置文本

将文本写入剪切板。

Go: ClipboardSetText(ctx context.Context, text string) error
返回: 如果存在错误，则会出现错误。

JS: ClipboardSetText(text: string): Promise<boolean>
返回值: 一个Promise，如果文本成功地设置在剪贴板上，结果为 true，否则为 false。

屏幕方法：

这些方法提供有关当前连接的屏幕的信息。

• ScreenGetAll：返回当前连接的屏幕列表。

  Go:

  ScreenGetAll(ctx context.Context) []screen
  

  返回值：一个包含所有连接屏幕信息的切片。

  JS:

  ScreenGetAll()
  

  返回值：一个包含所有连接屏幕信息的数组。

屏幕结构体：

Go 结构体：

type Screen struct {
    IsCurrent bool  // 是否是当前显示屏
    IsPrimary bool  // 是否是主屏
    Width     int   // 屏幕宽度（像素）
    Height    int   // 屏幕高度（像素）
}

Typescript 接口：

interface Screen {
    isCurrent: boolean;  // 是否是当前显示屏
    isPrimary: boolean;  // 是否是主屏
    width: number;       // 屏幕宽度（像素）
    height: number;      // 屏幕高度（像素）
}

这些结构体/接口表示有关屏幕的基本信息，例如是否为主屏幕或当前使用的屏幕，以及屏幕的宽度和高度。

拖放功能：

此部分的运行时处理将文件或文件夹拖放到窗口中的操作。要启用此功能，您需要在应用程序选项中将 EnableFileDrop 设置为 true。

• OnFileDrop：此方法处理窗口上的拖放事件。

  Go:

  OnFileDrop(ctx context.Context, callback func(x, y int, paths []string))
  

  调用回调函数，传递在窗口内释放鼠标时的坐标和一个包含绝对文件路径的切片。

  JS:

  OnFileDrop(callback: (x: number, y: number, paths: string[]) => void, useDropTarget: boolean): void
  

  调用回调函数，传递在窗口内释放鼠标时的坐标和一个包含绝对文件路径的切片。当 useDropTarget 为 true 时，除了在发生拖放时调用回调外，还会在窗口上注册事件监听器，监听拖拽的坐标，并检查鼠标是否悬停在具有 CSSDropProperty 样式的元素上。如果该元素具有该样式，则会向元素的类列表中添加 wails-drop-target-active 类，并在鼠标移开时移除该类。

• OnFileDropOff：此方法移除所有注册的拖放事件监听器和处理程序。

  Go:

  OnFileDropOff(ctx context.Context)
  

  返回值：无。

  JS:

  OnFileDropOff(): void
  

  返回值：无。