wails的运行时

运行时是一个为应用程序提供实用方法的库

wails目前运行时实现的功能有：程序控制、窗口控制、对话框、事件监听、菜单控制、日志操作、剪切板操作、浏览器操作等功能

wails同时提供了Go和JavaScript两个运行时，也就是说针对同一个功能，wails同时提供了Go方法和js方法两种实现

Go方法通过"github.com/wailsapp/wails/v2/pkg/runtime"包来实现

JS方法通过window.runtime的相关方法来实现

如控制窗口隐藏的方法Hide()方法

Go调用：runtime.Hide(ctx)
JS调用：window.runtime.Hide()

Go的所有运行时相关方法都将context作为第一个参数，用来表示程序运行时上下文，而JS相关方法则无需提供程序运行时的上下文

这是因为Go程序是一个静态编译语言，无法在程序还没有运行时就获取到运行时上下文，一般是通过应用配置中的OnDomReady字段在前端DOM加载完毕后运行回调函数来获取此时的运行时上下文

OnStartup字段表示在前端创建之后且index.html加载之前调，此时不能保证运行时将在此方法中工作，因为窗口正在不同的线程中初始化

所以推荐使用OnDomReady字段在前端加载完毕index.html及其资源后调用

而作为动态脚本语言的JS则可以方便的自动获取到运行时上下文而无需手动提供

为了尽可能同步Go运行时和JS运行时方法的实现，两者方法名均相同，参数也仅仅为Go方法第一个为ctx，JS方法省略了该参数，其余参数均相同

Go获取运行时上下文的方式

官方的做法：
type App struct{
    ctx context.Context
}
    // 定义一个结构体用于存储运行时上下文

func (app *App) domready(ctx context.Context){
    app.ctx = ctx
}
    // 定义一个用于回调的方法

func (app *App) ...  // 其他方法

app:=&App{}

wails.Run(&options.App{
    OnDomReady:app.startup,  // 设置回调函数
    Bind:[]any{
        app,
    }
    ..., // 其他配置项
})
这样我们就可以通过App结构体的相关方法来操作了

我们也可以定义一个全局变量，通过回调函数来在运行时修改该全局变量的值，然后后续所有方法都可以使用该全局变量来操作了

在以下运行时方法的介绍中，为了节省篇幅，我们仅介绍JS的方法，如果需要使用对应的Go方法，仅需在参数中增加一个ctx且位于第一个参数位即可，如果有方法的参数会返回格式不同会同时列出两种方法

程序控制

隐藏程序：    Hide()
显示程序：    Show()
退出程序：    Quit()
获取系统信息：Environment()
获取系统屏幕列表：ScreenGetAll() ([]Screen, error)

窗口控制

重新加载窗口      WindowReload()
重新加载程序前端  WindowReloadApp()

设置默认主题    WindowSetSystemDefaultTheme()
设置浅色主题    WindowSetLightTheme()
设置深色主题    WindowSetDarkTheme()

设置窗口标题    WindowSetTitle(title: string)

显示窗口        WindowShow()
隐藏窗口        WindowHide()

窗口居中        WindowCenter()
设置窗口位置    WindowSetPosition(x: number, y: number)
获取窗口位置    WindowGetPosition() : Position
               WindowGetPosition(ctx context.Context) (x int, y int)

设置窗口尺寸    WindowSetSize(width: number, height: number)
获取窗口尺寸    WindowGetSize() : Size
               WindowGetSize(ctx context.Context) (width int, height int)
设置最小尺寸    WindowSetMinSize(width: number, height: number)
               设为 0,0 禁用此约束
设置最大尺寸    WindowSetMaxSize(width: number, height: number)
               设为 0,0 禁用此约束

全屏           WindowFullscreen()
取消全屏       WindowUnfullscreen()
是否全屏       WindowIsFullscreen() bool
最大化         WindowMaximise()
取消最大化     WindowUnmaximise()
是否最大化     WindowIsMaximised() bool
最大化切换：   WindowToggleMaximise()
最小化        WindowMinimise()
取消最小化    WindowUnminimise()
是否最小化    WindowIsMinimised() bool
窗口是否正常  WindowIsNormal() bool
             窗口未最小化、最大化或全屏返回true

设置窗口置顶   WindowSetAlwaysOnTop(b: Boolen)

设置窗口背景色 WindowSetBackgroundColour(R, G, B, A)
              Windows仅支持0或255的alpha。任何非0的值都被视为255
打开打印窗口   WindowPrint()

执行JS代码     WindowExecJS(ctx context.Context, js string)
    仅有Go版本，在浏览器中异步运行代码并立即返回
    如果脚本导致任何错误，将只在浏览器控制台中可用

对话框

当前wails的JS运行时暂不支持对话框相关功能，此功能目前仅有Go方法且未暴露至前端

目录选择   OpenDirectoryDialog(ctx , opts OpenDialogOptions) (string, error)
文件选择   OpenFileDialog(ctx , opts OpenDialogOptions) (string, error)
多文件选择 OpenMultipleFilesDialog(ctx , opts OpenDialogOptions) ([]string, error)
    type OpenDialogOptions struct {
        DefaultDirectory           string   // 默认打开目录
        DefaultFilename            string   // 默认文件名
        Title                      string   // 对话框标题
        Filters                    []FileFilter  // 文件过滤器列表
        ShowHiddenFiles            bool     // 显示系统隐藏文件
        CanCreateDirectories       bool     // 允许用户创建目录
        ResolvesAliases            bool     // 返回文件而不是别名
        TreatPackagesAsDirectories bool     // 允许导航到包
    }
    type FileFilter struct {
        DisplayName string         // 显示文本，如"Image Files (*.jpg, *.png)"
        Pattern     string         // 使用分号(;)分割的文件名匹配规则，如"*.jpg;*.png"
    }

文件保存   SaveFileDialog(ctx , opts SaveDialogOptions) (string, error)
    type SaveDialogOptions struct{
        字段相比OpenDialogOptions少了ResolvesAliases，其余完全相同
    }

消息对话框 MessageDialog(ctx , opts MessageDialogOptions) (string, error)
    返回所选按钮的文本或错误
    type MessageDialogOptions struct {
        Type          DialogType
        Title         string    // 对话框标题
        Message       string    // 显示的信息
        DefaultButton string    // 设定默认按钮
        Icon          []byte
    }
    type DialogType string
    const (
        InfoDialog     DialogType = "info"
        WarningDialog  DialogType = "warning"
        ErrorDialog    DialogType = "error"
        QuestionDialog DialogType = "question"
    )
    在windows中，除question有两个按钮，左边返回Yes，右边返回No，其余三种类型均只有一个按钮，返回Yes

事件监听

添加事件监听器   EventsOn(eventName string, callback (...data)=>void ): ()=>void
    设置一个指定事件名称的监听器
    当触发事件名为eventName的事件时，将触发回调
    返回一个函数来取消侦听器
    callback中的函数参数可以根据需要自行设定，但无需提供返回值

移除事件监听器   EventsOff(eventName1 string, ... , eventNameN)
    删除若干个指定的事件名称的监听器

移除所有监听器   EventsOffAll()

单次事件监听器   EventsOnce(eventName string, callback (...data)=>void ): ()=>void
    只会触发1次的事件监听器

多次事件监听器  EventsOnMultiple(eventName string, callback (...data)=>void, counter int):  ()=>void
    最多只会触发counter次的事件监听器

触发指定事件    EventsEmit(eventName: string, ...optionalData: any)
    触发指定事件，通过后续的参数将回调函数的自定义参数数据传递给回调函数

日志操作

wails运行时提供了一种可以从Go或JS调用日志记录的机制

通过日志级别区分不同程度的日志记录，记录器将输出不低于当前设定的日志级别的日志消息

日志相关定义在"github.com/wailsapp/wails/v2/pkg/logger"包中，该包对于日志级别的定义

type LogLevel uint8
const (
    TRACE   LogLevel = 1
    DEBUG   LogLevel = 2
    INFO    LogLevel = 3
    WARNING LogLevel = 4
    ERROR   LogLevel = 5
)

日志操作的相关方法

设定日志级别
    Go：LogSetLogLevel(ctx context.Context, level int)
    JS：SetLogLevel(level: number)
    唯一的方法名不同的方法，不知道是官方导出时写错了还是故意的

针对每种日志级别分别设置了2个Go方法和1个JS方法用于记录对应级别的日志
    LogTrace(ctx context.Context, message string)
    LogTrace(message: string)
    LogTracef(ctx context.Context, format string, args ...interface{})
其他级别的类似

最后还有一个记录原始信息的
    LogPrinf(ctx context.Context, message string)
    LogPrinf(message: string)
    LogPrinff(ctx context.Context, format string, args ...interface{})

拖放操作

处理将文件和/或文件夹拖放到窗口中的操作

要启用此功能，必须在应用配置中将EnableFileDrop字段设置为true

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
    使用释放时鼠标在窗口内的坐标和绝对文件路径切片调用回调函数
    在JS方法中，当useDropTarget为true时
        会在窗口上注册监听名称为"wails:file-drop"的拖动坐标的事件监听器
        并检查鼠标是否位于具有CSSDropProperty样式且值为CSSDragValue的元素上
        如果元素具有required属性，会将wails-drop-target-active类添加到元素的类列表中，并在鼠标离开它时将其删除

OnFileDropOff()  ：删除名称为"wails:file-drop"的已注册监听器

剪切板操作

当前wails针对剪切板的操作仅实现了处理文本相关功能

读取剪切板文本
    ClipboardGetText(ctx context.Context) (string, error)
    ClipboardGetText(): Promise

设置剪切板文本
    ClipboardSetText(ctx context.Context, text string) error
    ClipboardSetText(text: string): Promise

菜单控制

当前wails的JS运行时暂不支持菜单相关功能，此功能目前仅有Go方法且未暴露至前端

MenuSetApplicationMenu(ctx context.Context, menu *menu.Menu)
    将程序菜单设置为给定的menu

MenuUpdateApplicationMenu(ctx context.Context)
    更新程序菜单

浏览器操作

仅实现了使用系统默认浏览器打开指定网址的功能

BrowserOpenURL(url string)