mirror of
https://github.com/wailsapp/wails.git
synced 2025-05-05 19:59:43 +08:00
186 lines
6.1 KiB
Markdown
186 lines
6.1 KiB
Markdown
# 介绍
|
||
|
||
!!! note 这个指南仍在制作中。
|
||
|
||
感谢您想要帮助开发Wails！本指南将帮助您入门。
|
||
|
||
## 入门指南
|
||
|
||
- Git 克隆此存储库。切换到 `v3-alpha` 分支。
|
||
- 安装 CLI：`cd v3/cmd/wails3 && go install`
|
||
|
||
- 可选：如果您想要使用构建系统构建前端代码，您需要安装
|
||
[npm](https://nodejs.org/en/download)。
|
||
|
||
## 构建
|
||
|
||
对于简单的程序，您可以使用标准的 `go build` 命令。也可以使用 `go run`。
|
||
|
||
Wails 还配备了一个构建系统，可用于构建更复杂的项目。它使用了强大的
|
||
[Task](https://taskfile.dev) 构建系统。要了解更多信息，请查看任务主页或运行
|
||
`wails task --help`。
|
||
|
||
## 项目结构
|
||
|
||
该项目具有以下结构：
|
||
|
||
```
|
||
v3
|
||
├── cmd/wails3 // CLI
|
||
├── examples // Wails 应用示例
|
||
├── internal // 内部包
|
||
| ├── runtime // Wails JS 运行时
|
||
| └── templates // 支持的项目模板
|
||
├── pkg
|
||
| ├── application // 核心 Wails 库
|
||
| └── events // 事件定义
|
||
| └── mac // 由插件使用的 macOS 特定代码
|
||
| └── w32 // Windows 特定代码
|
||
├── plugins // 支持的插件
|
||
├── tasks // 通用任务
|
||
└── Taskfile.yaml // 开发任务配置
|
||
```
|
||
|
||
## 开发
|
||
|
||
### 添加窗口功能
|
||
|
||
添加窗口功能的首选方法是在 `pkg/application/webview_window.go` 文件中添加一个新
|
||
函数。这应该实现所有平台所需的功能。任何特定于平台的代码都应通过
|
||
`webviewWindowImpl` 接口方法调用。该接口由每个目标平台实现，以提供平台特定的功
|
||
能。在某些情况下，这可能不执行任何操作。添加接口方法后，请确保每个平台都实现了
|
||
它。一个很好的例子是 `SetMinSize` 方法。
|
||
|
||
- Mac: `webview_window_darwin.go`
|
||
- Windows: `webview_window_windows.go`
|
||
- Linux: `webview_window_linux.go`
|
||
|
||
大多数，如果不是全部，特定于平台的代码应在主线程上运行。为了简化这一点，在
|
||
`application.go` 中定义了一些 `invokeSync` 方法。
|
||
|
||
### 更新运行时
|
||
|
||
运行时位于 `v3/internal/runtime`。更新运行时时，需要执行以下步骤：
|
||
|
||
```shell
|
||
wails3 task runtime:build
|
||
```
|
||
|
||
### 事件
|
||
|
||
事件定义在 `v3/pkg/events` 中。当添加新事件时，需要执行以下步骤：
|
||
|
||
- 将事件添加到 `events.txt` 文件中
|
||
- 运行 `wails3 task events:generate`
|
||
|
||
有几种类型的事件：特定于平台的应用程序和窗口事件 + 通用事件。通用事件对于跨平台
|
||
事件处理很有用，但您不必局限于“最低公共分母”。如果需要，可以使用特定于平台的事
|
||
件。
|
||
|
||
添加通用事件时，请确保映射了特定于平台的事件。一个示例是在
|
||
`window_webview_darwin.go` 中：
|
||
|
||
```go
|
||
// 将 ShouldClose 转化为通用的 WindowClosing 事件
|
||
w.parent.On(events.Mac.WindowShouldClose, func(_ *WindowEventContext) {
|
||
w.parent.emit(events.Common.WindowClosing)
|
||
})
|
||
```
|
||
|
||
注意：我们可能会尝试通过将映射添加到事件定义中来自动化此过程。
|
||
|
||
### 插件
|
||
|
||
插件是扩展 Wails 应用功能的一种方式。
|
||
|
||
#### 创建插件
|
||
|
||
插件是符合以下接口的标准 Go 结构：
|
||
|
||
```go
|
||
type Plugin interface {
|
||
Name() string
|
||
Init(*application.App) error
|
||
Shutdown()
|
||
CallableByJS() []string
|
||
InjectJS() string
|
||
}
|
||
```
|
||
|
||
`Name()` 方法返回插件的名称。这用于日志记录。
|
||
|
||
`Init(*application.App) error` 方法在加载插件时调用。`*application.App` 参数是加
|
||
载插件的应用程序。任何错误都将阻止应用程序启动。
|
||
|
||
`Shutdown()` 方法在应用程序关闭时调用。
|
||
|
||
`CallableByJS()` 方法返回可以从前端调用的导出函数列表。这些方法的名称必须与插件
|
||
导出的方法的名称完全匹配。
|
||
|
||
`InjectJS()` 方法返回应注入到所有窗口中的 JavaScript。这对于添加与插件相补充的自
|
||
定义 JavaScript 函数非常有用。
|
||
|
||
内置插件可以在 `v3/plugins` 目录中找到。参考它们以获得灵感。
|
||
|
||
## 任务
|
||
|
||
Wails CLI 使用 [Task](https://taskfile.dev) 构建系统。它作为库导入并用于运行
|
||
`Taskfile.yaml` 中定义的任务。与 Task 的主要交互发生在
|
||
`v3/internal/commands/task.go` 中。
|
||
|
||
### 升级 Taskfile
|
||
|
||
要检查是否有 Taskfile 的升级，请运行 `wails3 task -version` 并检查 Task 网站。
|
||
|
||
要升级使用的 Taskfile 版本，请运行：
|
||
|
||
```shell
|
||
wails3 task taskfile:upgrade
|
||
```
|
||
|
||
如果存在不兼容性，则应在 `v3/internal/commands/task.go` 文件中显示。
|
||
|
||
通常，修复不兼容性的最佳方法是克隆 `https://github.com/go-task/task` 上的任务存
|
||
储库，并查看 git 历史记录以确定发生了什么变化以及原因。
|
||
|
||
要检查所有更改是否正确工作，请重新安装 CLI 并再次检查版本：
|
||
|
||
```shell
|
||
wails3 task cli:install
|
||
wails3 task -version
|
||
```
|
||
|
||
## 打开 PR
|
||
|
||
确保所有 PR 都有与之关联的工单，以提供更改的上下文。如果没有工单，请先创建一个。
|
||
确保所有 PR 都已使用所做的更改更新了 CHANGELOG.md 文件。CHANGELOG.md 文件位于
|
||
`mkdocs-website/docs` 目录中。
|
||
|
||
## 其他任务
|
||
|
||
### 升级 Taskfile
|
||
|
||
Wails CLI 使用 [Task](https://taskfile.dev) 构建系统。它作为库导入并用于运行
|
||
`Taskfile.yaml` 中定义的任务。与 Task 的主要交互发生在
|
||
`v3/internal/commands/task.go` 中。
|
||
|
||
要检查是否有 Taskfile 的升级，请运行 `wails3 task -version` 并检查 Task 网站。
|
||
|
||
要升级使用的 Taskfile 版本，请运行：
|
||
|
||
```shell
|
||
wails3 task taskfile:upgrade
|
||
```
|
||
|
||
如果存在不兼容性，则应在 `v3/internal/commands/task.go` 文件中显示。
|
||
|
||
通常，修复不兼容性的最佳方法是克隆 `https://github.com/go-task/task` 上的任务存
|
||
储库，并查看 git 历史记录以确定发生了什么变化以及原因。
|
||
|
||
要检查所有更改是否正确工作，请重新安装 CLI 并再次检查版本：
|
||
|
||
```shell
|
||
wails3 task cli:install
|
||
wails3 task -version
|
||
```
|