docs.sheetjs.com/docz/docs/03-demos/19-desktop/03-wails.md

427 lines
12 KiB
Markdown
Raw Normal View History

2023-01-05 03:57:48 +00:00
---
2023-08-26 23:05:59 +00:00
title: Spreadsheet-Powered Wails Apps
2023-06-20 01:21:34 +00:00
sidebar_label: Wails
description: Build data-intensive desktop apps using Wails. Seamlessly integrate spreadsheets into your app using SheetJS. Modernize Excel-powered business processes with confidence.
2023-01-05 23:33:49 +00:00
pagination_prev: demos/mobile/index
2024-03-18 08:24:41 +00:00
pagination_next: demos/cli/index
2023-01-05 03:57:48 +00:00
sidebar_position: 3
sidebar_custom_props:
summary: Webview + Go Backend
---
2023-04-27 09:12:19 +00:00
import current from '/version.js';
2023-01-05 03:57:48 +00:00
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
2023-04-30 12:27:09 +00:00
import CodeBlock from '@theme/CodeBlock';
2023-01-05 03:57:48 +00:00
2023-06-20 01:21:34 +00:00
[Wails](https://wails.io/) is a modern toolkit for building desktop apps. Wails
apps pair a Go-powered backend with a JavaScript-powered frontend[^1].
[SheetJS](https://sheetjs.com) is a JavaScript library for reading and writing
data from spreadsheets.
This demo uses Wails and SheetJS to pull data from a spreadsheet and display the
data in the app. We'll explore how to load SheetJS in a Wails app and exchange
file data between the JavaScript frontend and Go backend.
2023-01-05 03:57:48 +00:00
2023-06-20 01:21:34 +00:00
The ["Complete Example"](#complete-example) section covers a complete desktop
app to read and write workbooks. The app will look like the screenshots below:
2023-01-05 03:57:48 +00:00
2023-01-09 05:08:30 +00:00
<table><thead><tr>
2023-06-20 01:21:34 +00:00
<th><a href="#complete-example">Windows</a></th>
2023-01-09 05:08:30 +00:00
<th><a href="#complete-example">macOS</a></th>
<th><a href="#complete-example">Linux</a></th>
</tr></thead><tbody><tr><td>
2023-01-05 03:57:48 +00:00
2023-12-02 08:39:35 +00:00
![Windows screenshot](pathname:///wails/win10.png)
2023-03-19 06:02:55 +00:00
</td><td>
2023-01-09 05:08:30 +00:00
![macOS screenshot](pathname:///wails/macos.png)
2023-01-05 03:57:48 +00:00
2023-01-09 05:08:30 +00:00
</td><td>
2023-01-05 03:57:48 +00:00
2023-01-09 05:08:30 +00:00
![Linux screenshot](pathname:///wails/linux.png)
2023-01-05 03:57:48 +00:00
2023-01-09 05:08:30 +00:00
</td></tr></tbody></table>
2023-01-05 03:57:48 +00:00
2023-08-26 23:05:59 +00:00
:::tip pass
This demo assumes familiarity with the Go programming language.
2023-06-20 01:21:34 +00:00
2023-08-26 23:05:59 +00:00
For a pure JavaScript solution, the [Electron](/docs/demos/desktop/electron)
2023-06-20 01:21:34 +00:00
platform provides many native features out of the box.
:::
2023-02-12 08:15:17 +00:00
## Integration Details
2023-01-05 03:57:48 +00:00
2023-06-20 01:21:34 +00:00
The [SheetJS NodeJS Module](/docs/getting-started/installation/nodejs) can be
installed in the `frontend` folder and imported in frontend scripts.
2023-01-05 03:57:48 +00:00
2023-08-26 23:05:59 +00:00
:::caution pass
2023-01-05 03:57:48 +00:00
2023-06-20 01:21:34 +00:00
Wails currently does not provide the equivalent of NodeJS `fs` module.
2023-01-05 03:57:48 +00:00
2023-08-26 23:05:59 +00:00
**Reading and writing raw file data must be implemented in native Go code.**
2023-01-05 03:57:48 +00:00
2023-01-09 05:08:30 +00:00
:::
2023-01-05 03:57:48 +00:00
2023-06-20 01:21:34 +00:00
This demo includes native Go code for showing dialogs and reading and writing
files. When sending data between Go and JavaScript code, the raw files are
encoded as Base64 strings.
2023-01-05 03:57:48 +00:00
### Reading Files
2023-06-20 01:21:34 +00:00
When the user clicks the "Import File" button, the frontend tells the Go backend
to read data. The user will be presented with a file picker to select a file to
read. The Go backend will read the data, encode as a Base64 string, and send the
result to the frontend.
The frontend will parse the data using the SheetJS `read` method[^2], generate
HTML tables with `sheet_to_html`[^3], and display the tables on the frontend.
The following diagram summarizes the steps:
2023-01-05 03:57:48 +00:00
2023-01-09 05:08:30 +00:00
```mermaid
sequenceDiagram
actor User
2023-06-20 01:21:34 +00:00
participant JS as Frontend (JS)
participant Go as Backend (Go)
2023-01-09 05:08:30 +00:00
User->>JS: click button
JS->>Go: ask for data
Note over Go: Show Open Dialog
Note over Go: Read File Bytes
Note over Go: Generate Base64
Go->>JS: return data
2023-06-20 01:21:34 +00:00
Note over JS: Parse Data<br/>`read`
Note over JS: Display Table<br/>`sheet_to_html`
2023-01-09 05:08:30 +00:00
JS->>User: app shows data
```
2023-01-05 03:57:48 +00:00
#### Go
2023-06-20 01:21:34 +00:00
The Wails runtime provides the cross-platform `OpenFileDialog` function[^4] to
show a file picker. The Go standard library provides methods for reading data
from the selected file[^5] and encoding in a Base64 string[^6]
2023-01-05 03:57:48 +00:00
```go
import (
"context"
// highlight-start
"encoding/base64"
2023-06-20 01:21:34 +00:00
"os"
2023-01-05 03:57:48 +00:00
"github.com/wailsapp/wails/v2/pkg/runtime"
// highlight-end
)
type App struct {
ctx context.Context
}
// ReadFile shows an open file dialog and returns the data as Base64 string
func (a *App) ReadFile() string {
// highlight-next-line
selection, err := runtime.OpenFileDialog(a.ctx, runtime.OpenDialogOptions{
Title: "Select File",
Filters: []runtime.FileFilter{
{ DisplayName: "Excel Workbooks (*.xlsx)", Pattern: "*.xlsx", },
// ... more filters for more file types
},
})
if err != nil { return "" } // The demo app shows an error message
// highlight-next-line
2023-06-20 01:21:34 +00:00
data, err := os.ReadFile(selection)
2023-01-05 03:57:48 +00:00
if err != nil { return "" } // The demo app shows an error message
// highlight-next-line
return base64.StdEncoding.EncodeToString(data)
}
```
#### JS
2023-06-20 01:21:34 +00:00
Wails will automatically create bindings for use in JS. The `App` binding module
will export the function `ReadFile`.
2023-01-05 03:57:48 +00:00
2023-08-26 23:05:59 +00:00
The following example uses the [SvelteJS](/docs/demos/frontend/svelte) framework:
2023-01-05 03:57:48 +00:00
```js title="frontend/src/App.svelte"
import { read, utils } from 'xlsx';
2023-01-09 05:08:30 +00:00
import { ReadFile } from '../wailsjs/go/main/App';
2023-01-05 03:57:48 +00:00
async function importFile(evt) {
// highlight-start
2023-06-20 01:21:34 +00:00
/* call the native Go function and receive a base64 string */
2023-01-09 05:08:30 +00:00
const b64 = await ReadFile();
2023-06-20 01:21:34 +00:00
/* parse the base64 string with SheetJS */
2023-01-05 03:57:48 +00:00
const wb = read(b64, { type: "base64" });
// highlight-end
2023-06-20 01:21:34 +00:00
2023-01-05 03:57:48 +00:00
const ws = wb.Sheets[wb.SheetNames[0]]; // get the first worksheet
2023-06-20 01:21:34 +00:00
return utils.sheet_to_html(ws); // generate HTML table
2023-01-05 03:57:48 +00:00
}
```
### Writing Files
2023-08-26 23:05:59 +00:00
:::info pass
2023-06-20 01:21:34 +00:00
The SheetJS `write` method[^7] can write spreadsheets in a number of formats[^8]
including XLSX, XLSB, XLS, and NUMBERS. It expects a `bookType` option. This
means the frontend needs to know the output file name before creating the file.
2023-01-05 03:57:48 +00:00
2023-06-20 01:21:34 +00:00
:::
2023-01-05 03:57:48 +00:00
2023-06-20 01:21:34 +00:00
When the user clicks the "Export File" button, the frontend asks the Go backend
for the output filename and path. The user will be presented with a file picker
to select the output folder and workbook type. The backend will send the name
to the frontend.
2023-01-05 03:57:48 +00:00
2023-06-20 01:21:34 +00:00
The frontend will generate a workbook object from the table using the SheetJS
`table_to_book` method[^9]. The SheetJS `write` method[^10] will generate a
Base64 string from the data.
The frontend will send the Base64 string to the backend. The backend will write
the data to a file in the selected folder.
2023-01-05 03:57:48 +00:00
2023-01-09 05:08:30 +00:00
```mermaid
sequenceDiagram
actor User
2023-06-20 01:21:34 +00:00
participant JS as Frontend (JS)
participant Go as Backend (Go)
2023-01-09 05:08:30 +00:00
User->>JS: click button
JS->>Go: ask for path
Note over Go: Show Save Dialog
Go->>JS: path to save file
2023-06-20 01:21:34 +00:00
Note over JS: Read from Table<br/>`table_to_book`
Note over JS: Write Workbook<br/>`write`
2023-01-09 05:08:30 +00:00
JS->>Go: base64-encoded bytes
2023-06-20 01:21:34 +00:00
Note over Go: Decode Data
Note over Go: Write to File
2023-01-09 05:08:30 +00:00
Go->>JS: write finished
JS->>User: alert
```
2023-01-05 03:57:48 +00:00
##### Go
Two Go functions will be exposed.
2023-06-20 01:21:34 +00:00
- `SaveFile` will show the file picker and return the path. It will use the
cross-platform `SaveFileDialog` function[^11].
2023-01-05 03:57:48 +00:00
```go
import (
"context"
2023-01-09 05:08:30 +00:00
// highlight-next-line
2023-01-05 03:57:48 +00:00
"github.com/wailsapp/wails/v2/pkg/runtime"
)
type App struct {
ctx context.Context
}
func (a *App) SaveFile() string {
// highlight-next-line
selection, err := runtime.SaveFileDialog(a.ctx, runtime.SaveDialogOptions{
Title: "Select File",
DefaultFilename: "SheetJSWails.xlsx",
Filters: []runtime.FileFilter{
{ DisplayName: "Excel Workbooks (*.xlsx)", Pattern: "*.xlsx", },
// ... more filters for more file types
},
})
if err != nil { return "" } // The demo app shows an error message
return selection
}
```
2023-06-20 01:21:34 +00:00
- `WriteFile` performs the file write given a Base64 string and file path. The
Go standard library provides methods for decoding Base64 strings[^12] and
writing data to the filesystem[^13]
2023-01-05 03:57:48 +00:00
```go
import (
"context"
// highlight-start
"encoding/base64"
2023-06-20 01:21:34 +00:00
"os"
2023-01-05 03:57:48 +00:00
// highlight-end
)
type App struct {
ctx context.Context
}
func (a *App) WriteFile(b64 string, path string) {
// highlight-start
buf, _ := base64.StdEncoding.DecodeString(b64);
2023-06-20 01:21:34 +00:00
_ = os.WriteFile(path, buf, 0644);
2023-01-05 03:57:48 +00:00
// highlight-end
}
```
#### JS
2023-06-20 01:21:34 +00:00
Wails will automatically create bindings for use in JS. The `App` binding module
2023-08-26 23:05:59 +00:00
will export the functions `SaveFile` and `WriteFile`.
The following example uses the [SvelteJS](/docs/demos/frontend/svelte) framework:
2023-01-05 03:57:48 +00:00
2023-06-20 01:21:34 +00:00
```js title="frontend/src/App.svelte"
2023-01-05 03:57:48 +00:00
import { utils, write } from 'xlsx';
2023-01-09 05:08:30 +00:00
import { SaveFile, WriteFile } from '../wailsjs/go/main/App';
2023-01-05 03:57:48 +00:00
2023-06-20 01:21:34 +00:00
async function exportFile(table_element) {
2023-01-05 03:57:48 +00:00
/* generate workbook */
2023-06-20 01:21:34 +00:00
const wb = utils.table_to_book(table_element);
2023-01-05 03:57:48 +00:00
/* show save picker and get path */
2023-01-09 05:08:30 +00:00
const path = await SaveFile();
2023-01-05 03:57:48 +00:00
2023-06-20 01:21:34 +00:00
/* get the file extension -> bookType */
const bookType = path.slice(path.lastIndexOf(".")+1);
/* generate base64 string */
const b64 = write(wb, { bookType: bookType, type: "base64" });
2023-01-05 03:57:48 +00:00
/* write to file */
2023-01-09 05:08:30 +00:00
await WriteFile(b64, path);
2023-01-05 03:57:48 +00:00
}
```
2023-01-09 05:08:30 +00:00
## Complete Example
2023-11-13 11:17:25 +00:00
:::note Tested Deployments
2023-02-12 08:15:17 +00:00
2023-08-26 23:05:59 +00:00
This demo was tested in the following environments:
2023-12-02 08:39:35 +00:00
| OS and Version | Architecture | Wails | Date |
|:---------------|:-------------|:---------|:-----------|
2024-03-16 16:04:18 +00:00
| macOS 14.4 | `darwin-x64` | `v2.8.0` | 2024-03-15 |
2024-05-28 05:20:05 +00:00
| macOS 14.5 | `darwin-arm` | `v2.8.2` | 2024-05-28 |
2024-03-25 04:13:01 +00:00
| Windows 10 | `win10-x64` | `v2.8.0` | 2024-03-24 |
2024-05-28 05:20:05 +00:00
| Windows 11 | `win11-arm` | `v2.8.2` | 2024-05-28 |
2024-03-22 04:45:40 +00:00
| Linux (HoloOS) | `linux-x64` | `v2.8.0` | 2024-03-21 |
2024-05-28 05:20:05 +00:00
| Linux (Debian) | `linux-arm` | `v2.8.2` | 2024-05-28 |
2023-01-09 05:08:30 +00:00
2023-02-12 08:15:17 +00:00
:::
2023-06-20 01:21:34 +00:00
0) Read the Wails "Getting Started" guide[^14] and install dependencies.
<details>
<summary><b>Installation Notes</b> (click to show)</summary>
2023-06-20 01:21:34 +00:00
Wails will require:
- A recent version of [Go](https://go.dev/doc/install).
- The "LTS" version of [NodeJS](https://nodejs.org/en/download).
After installing both, run the following command to install Wails:
```bash
go install github.com/wailsapp/wails/v2/cmd/wails@latest
```
Once that finishes, run the following command in a new terminal window:
```bash
wails doctor
```
2023-11-07 03:08:55 +00:00
:::note pass
On macOS and Linux, the `PATH` environment variable must include `~/go/bin`. If
`wails` cannot be found, run the following command in the terminal session:
2023-06-20 01:21:34 +00:00
2023-11-07 03:08:55 +00:00
```bash
2024-05-28 05:20:05 +00:00
export PATH="$PATH":~/go/bin
2023-06-20 01:21:34 +00:00
```
2023-11-07 03:08:55 +00:00
:::
The output will include a `# Diagnosis` section. It should display:
```
SUCCESS Your system is ready for Wails development!
2023-06-20 01:21:34 +00:00
```
If a required dependency is missing, it will be displayed.
2023-08-26 23:05:59 +00:00
:::note pass
2023-06-20 01:21:34 +00:00
None of the optional packages are required for building and running this demo.
:::
2023-08-26 23:05:59 +00:00
:::info pass
On the Steam Deck (HoloOS), some dependencies must be reinstalled:
```bash
2023-10-12 08:39:38 +00:00
sudo pacman -Syu base-devel gtk3 glib2 pango harfbuzz cairo gdk-pixbuf2 atk libsoup
2023-08-26 23:05:59 +00:00
```
:::
2023-06-20 01:21:34 +00:00
</details>
2023-01-09 05:08:30 +00:00
1) Create a new Wails app:
```bash
wails init -n sheetjs-wails -t svelte-ts
cd sheetjs-wails
```
2024-03-16 16:04:18 +00:00
2) Install front-end dependencies:
2023-01-09 05:08:30 +00:00
2023-04-30 12:27:09 +00:00
<CodeBlock language="bash">{`\
2023-01-09 05:08:30 +00:00
cd frontend
2023-09-25 07:30:54 +00:00
curl -o src/assets/logo.png https://sheetjs.com/sketch1024.png
2023-04-30 12:27:09 +00:00
npm i --save https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz
cd ..`}
</CodeBlock>
2023-01-09 05:08:30 +00:00
2024-03-16 16:04:18 +00:00
3) Download source files:
2023-01-09 05:08:30 +00:00
- Download [`app.go`](pathname:///wails/app.go) and replace `app.go`
- Download [`App.svelte`](pathname:///wails/App.svelte) and replace
`frontend/src/App.svelte`
```bash
2023-09-25 07:30:54 +00:00
curl -o app.go https://docs.sheetjs.com/wails/app.go
curl -o frontend/src/App.svelte https://docs.sheetjs.com/wails/App.svelte
2023-01-09 05:08:30 +00:00
```
2024-03-16 16:04:18 +00:00
4) Build the app:
2023-01-09 05:08:30 +00:00
```bash
wails build
```
2024-03-12 06:47:52 +00:00
It will print the path to the generated program (typically in `build/bin/`).
2023-10-12 08:39:38 +00:00
2024-03-16 16:04:18 +00:00
5) Run the generated application.
2023-06-20 01:21:34 +00:00
2023-08-26 23:05:59 +00:00
**Testing**
2024-04-26 04:16:13 +00:00
The program will download [`pres.xlsx`](https://docs.sheetjs.com/pres.xlsx) and
2024-03-16 16:04:18 +00:00
display the contents of the first worksheet in a table.
2023-08-26 23:05:59 +00:00
To test export features, click "Export XLSX". The app will ask for a file name
and location. After clicking Save, the app will export to XLSX. This file can be
opened in a spreadsheet editor such as Excel.
2023-06-20 01:21:34 +00:00
[^1]: See ["How does it Work?"](https://wails.io/docs/howdoesitwork) in the Wails documentation.
2023-06-25 09:36:58 +00:00
[^2]: See [`read` in "Reading Files"](/docs/api/parse-options)
2023-06-20 01:21:34 +00:00
[^3]: See [`sheet_to_html` in "Utilities"](/docs/api/utilities/html#html-table-output)
[^4]: See [`OpenFileDialog`](https://wails.io/docs/reference/runtime/dialog#openfiledialog) in the Wails documentation.
[^5]: See [`ReadFile`](https://pkg.go.dev/os#ReadFile) in the Go documentation
[^6]: See [`EncodeToString`](https://pkg.go.dev/encoding/base64#Encoding.EncodeToString) in the Go documentation
[^7]: See [`write` in "Writing Files"](/docs/api/write-options)
[^8]: See ["Supported Output Formats" type in "Writing Files"](/docs/api/write-options#supported-output-formats)
[^9]: See ["HTML Table Input" in "Utilities"](/docs/api/utilities/html#create-new-sheet)
[^10]: See [`write` in "Writing Files"](/docs/api/write-options)
[^11]: See [`SaveFileDialog`](https://wails.io/docs/reference/runtime/dialog#savefiledialog) in the Wails documentation.
[^12]: See [`DecodeString`](https://pkg.go.dev/encoding/base64#Encoding.DecodeString) in the Go documentation
[^13]: See [`WriteFile`](https://pkg.go.dev/os#WriteFile) in the Go documentation
[^14]: See ["Installation"](https://wails.io/docs/gettingstarted/installation) in the Wails documentation.