github/wails
5
0
Fork 0
mirror of https://github.com/wailsapp/wails.git synced 2025-05-02 17:39:58 +08:00
Code Projects Activity

feat(website): correct and optimize documents

Browse Source
This commit is contained in:
misitebao 2021-10-05 22:24:31 +08:00
parent 2d551cd019
commit a11a75fa12
2 changed files with 108 additions and 103 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

42
website/docs/gettingstarted/installation.mdx
View File

@ -6,16 +6,16 @@ sidebar_position: 1
## Supported Platforms ## Supported Platforms
- Windows 10 - Windows 10
- MacOS x64 & arm64 (due October '21) - MacOS x64 & arm64 (due October '21)
- Linux (due December '21) - Linux (due December '21)
## Dependencies ## Dependencies
Wails has a number of common dependencies that are required before installation: Wails has a number of common dependencies that are required before installation:
- Go 1.17+ - Go 1.17+
- npm (Node 14+) - npm (Node 14+)
### Go ### Go
@ -23,8 +23,8 @@ Download Go from the [Go Downloads Page](https://golang.org/dl/).
Ensure that you follow the official [Go installation instructions](https://golang.org/doc/install#install). You will also need to ensure that your `PATH` environment variable also includes the path to your `~/go/bin` directory. Restart your terminal and do the following checks: Ensure that you follow the official [Go installation instructions](https://golang.org/doc/install#install). You will also need to ensure that your `PATH` environment variable also includes the path to your `~/go/bin` directory. Restart your terminal and do the following checks:
* Check Go is installed correctly: `go version` - Check Go is installed correctly: `go version`
* Check "~/go/bin" is in your PATH variable: `echo $PATH | grep go/bin` - Check "~/go/bin" is in your PATH variable: `echo $PATH | grep go/bin`
### npm ### npm
@ -36,31 +36,29 @@ Run `npm --version` to verify.
You will also need to install platform specific dependencies: You will also need to install platform specific dependencies:
import Tabs from '@theme/Tabs'; import Tabs from "@theme/Tabs";
import TabItem from '@theme/TabItem'; import TabItem from "@theme/TabItem";
<Tabs <Tabs
defaultValue="Windows" defaultValue="Windows"
values={[ values={[
{label: 'Windows', value: 'Windows'}, { label: "Windows", value: "Windows" },
{label: 'MacOS', value: 'MacOS'}, { label: "MacOS", value: "MacOS" },
{label: 'Linux', value: 'Linux'}, { label: "Linux", value: "Linux" },
]}> ]}
<TabItem value="MacOS"> >
Coming Soon... <TabItem value="MacOS">Coming Soon...</TabItem>
</TabItem>
<TabItem value="Windows"> <TabItem value="Windows">
Wails requires that the <a href='https://developer.microsoft.com/en-us/microsoft-edge/webview2/'>WebView2</a> runtime is installed. Wails requires that the <a href="https://developer.microsoft.com/en-us/microsoft-edge/webview2/">WebView2</a>{" "}
Some Windows installations will already have this installed. You can check using the `wails doctor` command (see below). runtime is installed. Some Windows installations will already have this installed. You can check using the{" "}
</TabItem> <code>wails doctor</code> command (see below).
<TabItem value="Linux">
Coming Soon...
</TabItem> </TabItem>
<TabItem value="Linux">Coming Soon...</TabItem>
</Tabs> </Tabs>
## Optional Dependencies ## Optional Dependencies
- [UPX](https://upx.github.io/) for compressing your applications. - [UPX](https://upx.github.io/) for compressing your applications.
## Installing Wails ## Installing Wails

169
website/docs/howdoesitwork.mdx
View File

@ -11,12 +11,13 @@ version of the runtime library. Finally, it is possible to bind Go methods to th
Javascript methods that can be called, just as if they were local Javascript methods. Javascript methods that can be called, just as if they were local Javascript methods.
<div className="text--center"> <div className="text--center">
<img src="/img/architecture.svg" width='75%'/> <img src="/img/architecture.svg" width="75%" />
</div> </div>
## The Main Application ## The Main Application
### Overview ### Overview
The main application consists of a single call to `wails.Run()`. It accepts the The main application consists of a single call to `wails.Run()`. It accepts the
application configuration which describes the size of the application window, the window title, application configuration which describes the size of the application window, the window title,
what assets to use, etc. A basic application might look like this: what assets to use, etc. A basic application might look like this:
@ -75,12 +76,12 @@ func (b *App) Greet(name string) string {
This example has the following options set: This example has the following options set:
- `Title` - The text that should appear in the window's title bar - `Title` - The text that should appear in the window's title bar
- `Width` & `Height` - The dimensions of the window - `Width` & `Height` - The dimensions of the window
- `Assets` - The application's frontend assets - `Assets` - The application's frontend assets
- `OnStartup` - A callback for when the window is created and is about to start loading the frontend assets - `OnStartup` - A callback for when the window is created and is about to start loading the frontend assets
- `OnShutdown` - A callback for when the application is about to quit - `OnShutdown` - A callback for when the application is about to quit
- `Bind` - A slice of struct instances that we wish to expose to the frontend - `Bind` - A slice of struct instances that we wish to expose to the frontend
A full list of application options can be found in the [Options Reference](/docs/reference/options). A full list of application options can be found in the [Options Reference](/docs/reference/options).
@ -94,7 +95,7 @@ there is no requirement on where in the `embed.FS` the files live. It is likely
directory relative to your main application code, such as `frontend/dist`: directory relative to your main application code, such as `frontend/dist`:
```go title="main.go" ```go title="main.go"
// go:embed frontend/dist //go:embed frontend/dist
var assets embed.FS var assets embed.FS
``` ```
@ -117,7 +118,7 @@ Just before the frontend is about to load `index.html`, a callback is made to th
A standard Go context is passed to this method. This context is required when calling the runtime so a standard pattern is to save A standard Go context is passed to this method. This context is required when calling the runtime so a standard pattern is to save
a reference to in this method. Just before the application shuts down, the [OnShutdown](/docs/reference/options#OnShutdown) callback is called in the same way, a reference to in this method. Just before the application shuts down, the [OnShutdown](/docs/reference/options#OnShutdown) callback is called in the same way,
again with the context. There is also an [OnDomReady](/docs/reference/options#OnDomReady) callback for when the frontend again with the context. There is also an [OnDomReady](/docs/reference/options#OnDomReady) callback for when the frontend
has completed loading all assets in `index.html` and is equivalent of the [`body onload`](https://www.w3schools.com/jsref/event_onload.asp) event in Javascript. has completed loading all assets in `index.html` and is equivalent of the [`body onload`](https://www.w3schools.com/jsref/event_onload.asp) event in Javascript.
#### Method Binding #### Method Binding
@ -133,7 +134,7 @@ These methods return a promise. A successful call will result in the first retur
to the resolve handler. An unsuccessful call is when a Go method that has an error type as it's second return value, to the resolve handler. An unsuccessful call is when a Go method that has an error type as it's second return value,
passes an error instance back to the caller. This is passed back via the reject handler. passes an error instance back to the caller. This is passed back via the reject handler.
In the example above, `Greet` only returns a `string` so the Javascript call will never reject - unless invalid data In the example above, `Greet` only returns a `string` so the Javascript call will never reject - unless invalid data
is passed to it. is passed to it.
All data types are correctly translated between Go and Javascript. Even structs. If you return a struct from a Go call, All data types are correctly translated between Go and Javascript. Even structs. If you return a struct from a Go call,
it will be returned to your frontend as a Javascript map. Note: If you wish to use structs, you **must** define `json` struct it will be returned to your frontend as a Javascript map. Note: If you wish to use structs, you **must** define `json` struct
@ -148,14 +149,17 @@ section of the [Application Development Guide](/docs/guides/application-developm
## The Frontend ## The Frontend
### Overview ### Overview
The frontend is a collection of files rendered by webkit. It's like a browser and webserver in one. The frontend is a collection of files rendered by webkit. It's like a browser and webserver in one.
There is virtually[^1] no limit to which frameworks or libraries you can use. The main points of interaction between There is virtually[^1] no limit to which frameworks or libraries you can use. The main points of interaction between
the frontend and your Go code are: the frontend and your Go code are:
- Calling bound Go methods
- Calling runtime methods
[^1]: There is a very small subset of libraries that use features unsupported in WebViews. There are often alternatives and - Calling bound Go methods
workarounds for such cases. - Calling runtime methods
[^1]:
There is a very small subset of libraries that use features unsupported in WebViews. There are often alternatives and
workarounds for such cases.
### Calling bound Go methods ### Calling bound Go methods
@ -163,11 +167,11 @@ All bound Go methods are available at `window.go.<package>.<struct>.<method>`. A
the previous section, these return a Promise where a successful call returns a value to the the previous section, these return a Promise where a successful call returns a value to the
resolve handler and an error returns a value to the reject handler. resolve handler and an error returns a value to the reject handler.
```go title="mycode.js" ```go title="mycode.js"
window.go.main.App.Greet("Bill").then((result) => { window.go.main.App.Greet("Bill").then((result) => {
console.log("The greeting is: " + result); console.log("The greeting is: " + result);
}) })
``` ```
When running the application in `dev` mode, a javascript module is generated that wraps these When running the application in `dev` mode, a javascript module is generated that wraps these
methods with JSDoc annotations. This really help with development, especially as most methods with JSDoc annotations. This really help with development, especially as most
@ -178,19 +182,18 @@ following code:
```js title="bindings.js" ```js title="bindings.js"
const go = { const go = {
"main": { main: {
"App": { App: {
/** /**
* Greet * Greet
* @param {Person} arg1 - Go Type: string * @param {Person} arg1 - Go Type: string
* @returns {Promise<string>} - Go Type: string * @returns {Promise<string>} - Go Type: string
*/ */
"Greet": (arg1) => { Greet: (arg1) => {
return window.go.main.App.Greet(arg1); return window.go.main.App.Greet(arg1);
}, },
} },
} },
}; };
export default go; export default go;
``` ```
@ -221,93 +224,97 @@ func (a *App) Greet(p Person) string {
return fmt.Sprintf("Hello %s (Age: %d)!", p.Name, p.Age) return fmt.Sprintf("Hello %s (Age: %d)!", p.Name, p.Age)
} }
``` ```
Our `bindings.js` file has now been updated to reflect the change: Our `bindings.js` file has now been updated to reflect the change:
```js title="bindings.js" ```js title="bindings.js"
const go = { const go = {
"main": { main: {
"App": { App: {
/** /**
* Greet * Greet
* @param {Person} arg1 - Go Type: main.Person * @param {Person} arg1 - Go Type: main.Person
* @returns {Promise<string>} - Go Type: string * @returns {Promise<string>} - Go Type: string
*/ */
"Greet": (arg1) => { Greet: (arg1) => {
return window.go.main.App.Greet(arg1); return window.go.main.App.Greet(arg1);
}, },
} },
} },
}; };
export default go; export default go;
``` ```
Alongside `bindings.js`, there is a file called `models.ts`. This contains our Go structs in TypeScript form: Alongside `bindings.js`, there is a file called `models.ts`. This contains our Go structs in TypeScript form:
```ts title="models.ts" ```ts title="models.ts"
export class Address { export class Address {
street: string; street: string;
postcode: string; postcode: string;
static createFrom(source: any = {}) { static createFrom(source: any = {}) {
return new Address(source); return new Address(source);
} }
constructor(source: any = {}) { constructor(source: any = {}) {
if ('string' === typeof source) source = JSON.parse(source); if ("string" === typeof source) source = JSON.parse(source);
this.street = source["street"]; this.street = source["street"];
this.postcode = source["postcode"]; this.postcode = source["postcode"];
} }
} }
export class Person { export class Person {
name: string; name: string;
age: number; age: number;
address?: Address; address?: Address;
static createFrom(source: any = {}) { static createFrom(source: any = {}) {
return new Person(source); return new Person(source);
}
constructor(source: any = {}) {
if ("string" === typeof source) source = JSON.parse(source);
this.name = source["name"];
this.age = source["age"];
this.address = this.convertValues(source["address"], Address);
}
convertValues(a: any, classs: any, asMap: boolean = false): any {
if (!a) {
return a;
} }
if (a.slice) {
constructor(source: any = {}) { return (a as any[]).map((elem) => this.convertValues(elem, classs));
if ('string' === typeof source) source = JSON.parse(source); } else if ("object" === typeof a) {
this.name = source["name"]; if (asMap) {
this.age = source["age"]; for (const key of Object.keys(a)) {
this.address = this.convertValues(source["address"], Address); a[key] = new classs(a[key]);
}
return a;
}
return new classs(a);
} }
return a;
convertValues(a: any, classs: any, asMap: boolean = false): any { }
if (!a) {
return a;
}
if (a.slice) {
return (a as any[]).map(elem => this.convertValues(elem, classs));
} else if ("object" === typeof a) {
if (asMap) {
for (const key of Object.keys(a)) {
a[key] = new classs(a[key]);
}
return a;
}
return new classs(a);
}
return a;
}
} }
``` ```
So long as you have TypeScript as part of your frontend build configuration, you can use these models in So long as you have TypeScript as part of your frontend build configuration, you can use these models in
the following way: the following way:
```js title="mycode.js" ```js title="mycode.js"
import go from "./wailsjs/go/bindings"; import go from "./wailsjs/go/bindings";
import {Person} from "./wailsjs/go/models"; import { Person } from "./wailsjs/go/models";
let name = ""; let name = "";
function greet(name) { function greet(name) {
let p = new Person(); let p = new Person();
p.name = name; p.name = name;
p.age = 42; p.age = 42;
go.main.App.Greet(p).then((result) => { go.main.App.Greet(p).then((result) => {
console.log(result); console.log(result);
}); });
} }
``` ```
The combination of JSDoc and TypeScript generated models makes for a powerful development environment. The combination of JSDoc and TypeScript generated models makes for a powerful development environment.