使用说明
本字典整理 Wails v2 日常开发最常查的 API，版本锚点是 v2.9.2（2024 年 11 月时点的 v2 最新稳定版，v3 尚在 alpha，未收录）。Go 侧条目全部来自 github.com/wailsapp/wails/v2/pkg/runtime 包，前端条目来自 CLI 生成的 wailsjs/runtime 模块（同一套函数也挂在 window.runtime 上）。条目按”签名 → 什么时候用 → 最小示例 → 坑”组织，示例自包含可复制，这里只做查与抄，原理讲解看《Wails 框架要点》。
一、Go 侧运行时 API
组内共性：所有函数第一个参数都是 ctx context.Context——就是 OnStartup 回调里那个，丢了它所有运行时调用都不生效。易混点集中在事件家族：Emit 是发，On 是收，Off 是按名解绑，Once 是收一次就解绑。
EventsEmit
func EventsEmit(ctx context.Context, eventName string, optionalData ...interface{})向所有事件监听方广播一条事件，载荷跟在事件名后，数量不限。给前端推进度、状态变更用它。
runtime.EventsEmit(a.ctx, "download:progress", file, done, total)⚠️ OnDomReady 之前 emit，前端监听器还没注册，事件直接丢。初始状态用绑定方法拉取，事件只做增量通知。
EventsOn
func EventsOn(ctx context.Context, eventName string, callback func(optionalData ...interface{})) func()Go 侧订阅事件（多为前端发来的），返回值是取消函数，调它即解绑。与 JS 侧同名函数行为一致。
off := runtime.EventsOn(a.ctx, "ui:filter", func(optionalData ...interface{}) {
// JSON 边界：JS 发来的数字一律是 float64，断言 int 会失败
keyword, _ := optionalData[0].(string)
_ = keyword
})⚠️ 载荷是 []interface{}，数字是 float64、字符串才是 string；高频数据别走事件，走绑定方法，事件通道没有回执。
EventsOnce 与 EventsOnMultiple
func EventsOnce(ctx context.Context, eventName string, callback func(...interface{})) func()
func EventsOnMultiple(ctx context.Context, eventName string, callback func(...interface{}), counter int) func()Once 触发一次自动解绑；OnMultiple 限定最多触发 counter 次。适合”初始化完成即失效”的一次性握手。
⚠️ Once 的回调里如果再注册同名监听，注意解绑时机，避免前一次的残留监听还在收。
EventsOff 与 EventsOffAll
func EventsOff(ctx context.Context, eventName string, additionalEventNames ...string)
func EventsOffAll(ctx context.Context)按名批量解绑；OffAll 清空全部监听，页面整体刷新前用。
⚠️ 优先用 EventsOn 返回的取消函数精确解绑；Off 是按事件名一刀切，会把同名的其他监听一起干掉。
ClipboardGetText 与 ClipboardSetText
func ClipboardGetText(ctx context.Context) (string, error)
func ClipboardSetText(ctx context.Context, text string) error读、写系统剪贴板的纯文本。做剪贴板类工具、把导出结果一键塞进剪贴板都用它。
text, err := runtime.ClipboardGetText(a.ctx)
if err != nil {
// 剪贴板里可能是图片等非文本内容，按错误处理而不是当空串
runtime.LogDebug(a.ctx, "clipboard not text")
}⚠️ 剪贴板内容可能是图片、文件等非文本对象，GetText 会返回错误而不是空串，别把错误当”剪贴板为空”吞掉。
OpenFileDialog 与 SaveFileDialog
func OpenFileDialog(ctx context.Context, dialogOptions OpenDialogOptions) (string, error)
func SaveFileDialog(ctx context.Context, dialogOptions SaveDialogOptions) (string, error)单选文件打开框、保存框。OpenDialogOptions 常用字段：DefaultDirectory、DefaultFilename、Title、Filters（[]FileFilter，按 DisplayName/Pattern 过滤）。多选与目录用 OpenMultipleFilesDialog / OpenDirectoryDialog。
path, err := runtime.SaveFileDialog(a.ctx, runtime.SaveDialogOptions{
DefaultFilename: "export.json",
Title: "保存导出文件",
})⚠️ 用户取消选择时返回空串与 nil error，两个返回值都要判：只判 err 不判空串，后面拿空路径去写文件必炸。
MessageDialog
func MessageDialog(ctx context.Context, dialogOptions MessageDialogOptions) (string, error)原生消息框，替代网页 alert——生产构建里没有浏览器弹窗能力，系统级确认框用它。Type 常量有 InfoDialog / WarningDialog / ErrorDialog / QuestionDialog；Buttons 自定义按钮文字，返回点中的按钮文字。
choice, _ := runtime.MessageDialog(a.ctx, runtime.MessageDialogOptions{
Type: runtime.QuestionDialog,
Title: "清空历史",
Message: "确定要清空全部记录吗？",
Buttons: []string{"确定", "取消"},
})
if choice != "确定" {
return nil
}⚠️ 返回值是按钮文字字符串，改了 Buttons 数组记得同步改判断，最好用常量。
BrowserOpenURL
func BrowserOpenURL(ctx context.Context, url string)用系统默认浏览器打开链接，而不是在 WebView 里导航走——”关于页”、”帮助文档”这类外部链接的规范出口。
⚠️ 让 WebView 内部导航到外部网站会把应用变成”浏览器”，且脱离了应用上下文；外部 URL 一律走这个函数。
日志家族：LogTrace / LogDebug / LogInfo / LogWarning / LogError / LogFatal
runtime.LogInfo(a.ctx, "config loaded")分级日志，dev 模式打到控制台。LogFatal 记录后直接终止进程，只用于”活不下去”的启动失败。
⚠️ LogFatal 在绑定方法里等于”点一下按钮应用就退”，绑定方法里的失败应该走 error 返回值。
Environment
func Environment(ctx context.Context) EnvironmentInfo // BuildType / Platform / ArchBuildType 取值 “dev” 或 “production”，用来在运行时开关调试行为；Platform/Arch 打日志定位用户环境。
⚠️ BuildType 是编译期决定的运行时事实，不要用它做需要编译期裁剪的事（那该用 build tag）。
Show、Hide 与 Quit
func Show(ctx context.Context)
func Hide(ctx context.Context)
func Quit(ctx context.Context)显示/隐藏窗口（常驻应用的核心组合）、退出应用。配合 HideWindowOnClose 选项做”点关闭只是藏起来”。
⚠️ Hide 之后用户没有任何入口唤回（v2 没有系统托盘），要么留绑定按钮，要么用 SingleInstanceLock 让二次启动唤回主窗口。
OnFileDrop
func OnFileDrop(ctx context.Context, callback func(x, y int, paths []string))
func OnFileDropOff(ctx context.Context)接收文件拖入，回调拿到落点坐标与绝对路径列表。需在 options.App 里配 DragAndDrop: &options.DragAndDrop{EnableFileDrop: true}（v2.9.0 起提供）。
⚠️ 不配 DragAndDrop 选项时回调永远不触发；WebView 自己的 drop 行为想关掉用 DisableWebViewDrop，否则拖图进窗口会当资源打开。
窗口函数速记
WindowSetSize / WindowGetSize / WindowSetPosition / WindowGetPosition / WindowSetMinSize / WindowSetMaxSize / WindowCenter / WindowShow / WindowHide / WindowMaximise / WindowUnminimise / WindowSetAlwaysOnTop / WindowSetTitle / WindowFullscreen——签名统一是 func WindowXxx(ctx context.Context, ...)，Get 类返回值。窗口置顶常驻小面板的用法：runtime.WindowSetAlwaysOnTop(a.ctx, true)。
⚠️ v2 是单窗口模型，这些函数都作用于唯一主窗口；WindowSetAlwaysOnTop 是 v2.6.0 起的能力，更早版本没有。
二、options.App 关键字段
组内共性：全部在 wails.Run(&options.App{...}) 里一次性传入，运行时改不了。易混点：StartHidden 是”启动时藏”，HideWindowOnClose 是”点关闭改藏”，两个是不同行为。
| 字段 | 类型与语义 | 什么时候用 |
|---|---|---|
| Bind | []interface{}，要暴露给前端的结构体实例 | 几乎所有应用必配 |
| AssetServer | *assetserver.Options，Assets 指内嵌 fs.FS | 单文件产物的基础，配合 go:embed |
| OnStartup / OnDomReady / OnBeforeClose / OnShutdown | 生命周期回调 | 存 ctx / 发首屏事件 / 拦截关闭 / 清理 |
| StartHidden | bool，启动时不显示窗口 | 常驻工具的静默启动 |
| HideWindowOnClose | bool，点关闭改为隐藏 | 常驻应用替代 OnBeforeClose 拦截 |
| WindowStartState | options.Normal / Maximised / Minimised / Fullscreen | 控制初始窗口状态 |
| AlwaysOnTop | bool，窗口置顶 | 小面板、悬浮工具 |
| SingleInstanceLock | *options.SingleInstanceLock，单实例锁（v2.7.0+） | 防止多开；二次启动唤回主窗口 |
| DragAndDrop | *options.DragAndDrop，文件拖入（v2.9.0+） | 接收文件路径的应用 |
| EnableDefaultContextMenu | bool，生产构建启用默认右键菜单 | 需要”复制粘贴”右键操作时 |
Bind 展开示例
app := NewApp()
Bind: []interface{}{app}, // 换行写在 options.App 里；绑定的实例方法均暴露⚠️ 绑定的是实例：同一个结构体 New 两份、只绑了一份，另一份的状态前端永远看不到，症状是”方法能调但字段都是零值”。
SingleInstanceLock 展开示例
SingleInstanceLock: &options.SingleInstanceLock{
UniqueId: "e8f2b3c0-7d1a-4b9e-9c3f-demo-app-uuid", // 用 UUID，全局唯一
OnSecondInstanceLaunch: app.onSecondInstanceLaunch,
},
// 第二次双击 exe 时走到这里：唤起已存在的主窗口
func (a *App) onSecondInstanceLaunch(data options.SecondInstanceData) {
runtime.WindowUnminimise(a.ctx)
runtime.Show(a.ctx)
}⚠️ 官方文档明确：该回调不会自动聚焦窗口，必须自己调 WindowUnminimise + Show；且从第二实例传来的参数按不可信输入对待。Linux 上窗口管理器可能拒绝抢焦点，这是平台行为不是 bug。
三、前端 JS 运行时
组内共性：import 自 wailsjs/runtime（CLI 生成），也全局挂在 window.runtime 上；与 Go 侧同名函数语义一致，只是没有 ctx 参数。
EventsOn（JS 侧）
import { EventsOn, EventsEmit, EventsOff } from '../wailsjs/runtime';
// 返回取消函数，组件卸载时调用，防止监听越积越多
const off = EventsOn('download:progress', (file, done, total) => {
bar.style.width = (done / total) * 100 + '%';
});
EventsEmit('ui:filter', 'invoice'); // 前端也能发，Go 侧 EventsOn 收⚠️ 最常见的内存泄漏来源：组件每次挂载都 EventsOn、从不解绑，同一事件收到 N 次回调。取消函数要么存起来在卸载时调，要么用 EventsOff 按名清理。
ClipboardGetText 与 ClipboardSetText（JS 侧）
import { ClipboardSetText } from '../wailsjs/runtime';
const ok = await ClipboardSetText('已复制的文本');⚠️ 这套函数走的是 Wails 的运行时通道，与浏览器 navigator.clipboard 的权限模型无关；但在 WebView 里 navigator.clipboard 常受限制，要稳定读写优先用 runtime 版。
其他 JS 侧函数
WindowSetTitle / WindowCenter / WindowFullscreen / WindowSetSize 等窗口组、LogInfo 等日志组、BrowserOpenURL、ScreenGetAll、Quit / Show / Hide、Environment——全部与 Go 侧同名同语义。要在”非绑定场景”（如模板事件）里快速用就用 window.runtime.xxx。
⚠️ JS 侧没有对话框函数：文件选择、消息确认在 v2 里只有 Go 侧 runtime.Dialog 系列能做，封装成绑定方法给前端调。
四、CLI 与项目配置
组内共性：命令都不钉版本号（@latest 或项目内固定版本）；wails.json 是 CLI 与项目构建的单一事实来源，手写 npm 命令绕过它迟早出构建顺序问题。
| 命令 | 一句话用途 | 常用参数 |
|---|---|---|
| wails init | 从模板生成项目 | -n 项目名，-t 模板（vue-ts/react-ts/svelte-ts/vanilla 等） |
| wails dev | 开发模式：热更新 + 生成绑定 | -browser 用浏览器开调试页 |
| wails build | 生产构建，产出单文件可执行程序 | -platform 目标平台，-tags 追加构建标签 |
| wails doctor | 体检平台依赖是否齐全 | 装完环境先跑一次 |
| wails generate module | 重新生成 wailsjs 绑定模块 | 绑定类型报错时刷新 |
| wails update | 升级 CLI | 不钉版本号，升级前看 changelog |
| wails.json 字段 | 一句话用途 | 有什么坑 |
|---|---|---|
| frontend:install | 构建前安装前端依赖的命令 | 改了包管理器（pnpm/yarn）要同步改这里 |
| frontend:build | wails build 时构建前端产物的命令 | 产物没进 dist 目录时 embed 会编译失败 |
| wailsjsdir | 自动生成绑定模块的输出目录 | 默认在项目根 wailsjs，前端 import 路径以此为锚 |
| outputfilename | 二进制产物文件名 | Windows 产物自动加 .exe |
| devServer | dev 服务器地址，默认 localhost:34115 | 端口被占时浏览器调试页起不来 |
| assetdir | dev 模式静态资产目录 | 与 AssetServer.Assets 是两套事：前者 dev 用，后者打进二进制 |
速查表
| 条目 | 一句话用途 | 有什么坑 |
|---|---|---|
| EventsEmit | 广播事件给前端 | DomReady 前发等于白发 |
| EventsOn | 订阅事件，返回取消函数 | JS 数字到 Go 是 float64 |
| EventsOnce | 订阅一次即解绑 | 适合握手，别做常驻监听 |
| EventsOff | 按名批量解绑 | 会误杀同名的其他监听 |
| ClipboardGetText / SetText | 读写剪贴板文本 | 非文本内容返回 error 不是空串 |
| OpenFileDialog / SaveFileDialog | 文件选择框 | 取消时是空串 + nil error |
| MessageDialog | 原生消息/确认框 | 返回值是按钮文字字符串 |
| BrowserOpenURL | 系统浏览器打开链接 | 别让 WebView 导航去外站 |
| Log 家族 | 分级日志 | LogFatal 会直接退出进程 |
| Environment | dev/production 与平台信息 | 运行时事实，别当编译期开关 |
| Show / Hide / Quit | 窗口显隐与退出 | Hide 后要有唤回入口 |
| OnFileDrop | 接收文件拖入 | 必须先配 DragAndDrop 选项 |
| WindowSetAlwaysOnTop | 窗口置顶（v2.6.0+） | v2 单窗口，只作用于主窗口 |
| Bind | 暴露 Go 结构体方法给前端 | 绑实例不是绑类型 |
| AssetServer.Assets | 内嵌前端资产 | dist 为空编译失败 |
| HideWindowOnClose | 点关闭改为隐藏 | 与 OnBeforeClose 拦截二选一 |
| SingleInstanceLock | 单实例锁 + 二次启动回调（v2.7.0+） | 回调不自动聚焦，要手动 Show |
| DragAndDrop 选项 | 启用文件拖入（v2.9.0+） | 不开 EnableFileDrop 拖入无回调 |
| JS EventsOn | 前端订阅事件 | 不解绑是泄漏源头 |
| wails dev / build | 开发热更新 / 生产单文件产物 | 改前端必须重新 build 才进产物 |
| wails generate module | 重新生成 wailsjs 绑定 | 类型对不上时先跑它 |
相关阅读：安装与第一个窗口见《Wails 入门》；绑定与事件的原理展开见《Wails 框架要点》；这些 API 组合起来能做什么，看实战篇《用 Wails 做一个剪贴板历史工具》。Go 侧函数的签名风格（ctx 第一参、多返回值、error 收尾）是标准 Go 惯例，不熟悉的先补《Go内置函数详解》。
版本核实（以官方文档为准）：本字典基于 Wails v2.9.2（2024 年 11 月时点的 v2 最新稳定版）核对，含 v2.7.0 起的 SingleInstanceLock、v2.9.0 起的 DragAndDrop、v2.6.0 起的 WindowSetAlwaysOnTop 等版本敏感条目；各签名以 GitHub 仓库 v2.9.2 标签源码与 wails.io 文档为准。