nyne/flutter_qjs
1
0
Fork 0
mirror of https://github.com/wgh136/flutter_qjs.git synced 2025-09-27 05:27:23 +00:00
Code Issues Packages Projects Releases Wiki Activity

v0.3.3

Browse Source
This commit is contained in:
ekibun
2021-01-27 16:52:08 +08:00
parent 01ea420bd7
commit 0de94f12e2
12 changed files with 302 additions and 149 deletions
Download Patch File Download Diff File Expand all files Collapse all files

115
README.md
View File

@@ -10,13 +10,15 @@
![Pub](https://img.shields.io/pub/v/flutter_qjs.svg)
![Test](https://github.com/ekibun/flutter_qjs/workflows/Test/badge.svg)
[English](README.md) | [中文](README-CN.md)
This plugin is a simple js engine for flutter using the `quickjs` project with `dart:ffi`. Plugin currently supports all the platforms except web!
## Getting Started
### Basic usage
Firstly, create a `FlutterQjs` object, then call `dispatch` to dispatch event loop:
Firstly, create a `FlutterQjs` object, then call `dispatch` to establish event loop:
```dart
final engine = FlutterQjs(
@@ -25,7 +27,7 @@ final engine = FlutterQjs(
engine.dispatch();
```
Use `evaluate` method to run js script, now you can use it synchronously, or use await to resolve `Promise`:
Use `evaluate` method to run js script, it runs synchronously, you can use await to resolve `Promise`:
```dart
try {
@@ -35,7 +37,7 @@ try {
}
```
Method `close` can destroy quickjs runtime that can be recreated again if you call `evaluate`. Parameter `port` should be close to stop `dispatch` loop when you do not need it.
Method `close` can destroy quickjs runtime that can be recreated again if you call `evaluate`. Parameter `port` should be close to stop `dispatch` loop when you do not need it. **Reference leak exception will be thrown since v0.3.3**
```dart
try {
@@ -49,41 +51,21 @@ engine = null;
Data conversion between dart and js are implemented as follow:
| dart | js |
| ----------------------- | ------------------ |
| Bool | boolean |
| Int | number |
| Double | number |
| String | string |
| Uint8List | ArrayBuffer |
| List | Array |
| Map | Object |
| Function<br>JSInvokable | function(....args) |
| Future | Promise |
| JSError | Error |
| Object | DartObject |
| dart | js |
| ---------------------------- | ---------- |
| Bool | boolean |
| Int | number |
| Double | number |
| String | string |
| Uint8List | ArrayBuffer|
| List | Array |
| Map | Object |
| Function(arg1, arg2, ..., {thisVal})<br>JSInvokable.invoke(\[arg1, arg2, ...\], thisVal) | function.call(thisVal, arg1, arg2, ...) |
| Future | Promise |
| JSError | Error |
| Object | DartObject |
**notice:** `JSInvokable` does not extend `Function`, but can be used same as `Function`.
Dart function uses named argument `thisVal` to manage js function `this`:
```dart
func(arg1, arg2, {thisVal});
```
or use `invoke` method to pass list parameters:
```dart
(func as JSInvokable).invoke([arg1, arg2], thisVal);
```
`JSInvokable` returned by evaluation may increase reference of JS object.
You should manually call `free` to release JS reference:
```dart
(func as JSInvokable).free();
```
### Use modules
## Use Modules
ES6 module with `import` function is supported and can be managed in dart with `moduleHandler`:
@@ -105,9 +87,8 @@ import("hello").then(({default: greet}) => greet("world"));
**notice:** Module handler should be called only once for each module name. To reset the module cache, call `FlutterQjs.close` then `evaluate` again.
To use async function in module handler, try [Run on isolate thread](#Run-on-isolate-thread)
### Run on isolate thread
To use async function in module handler, try [run on isolate thread](#Run-on-Isolate-Thread)
## Run on Isolate Thread
Create a `IsolateQjs` object, pass handlers to resolving modules. Async function such as `rootBundle.loadString` can be used now to get modules:
@@ -121,7 +102,7 @@ final engine = IsolateQjs(
// not need engine.dispatch();
```
Same as run on main thread, use `evaluate` to run js script. In this way, `Promise` return by `evaluate` will be automatically tracked and return the resolved data:
Same as run on main thread, use `evaluate` to run js script. In isolate, everything returns asynchronously, use `await` to get the result:
```dart
try {
@@ -131,25 +112,49 @@ try {
}
```
Method `close` can destroy quickjs runtime that can be recreated again if you call `evaluate`.
Method `close` can destroy isolate thread that will be recreated again if you call `evaluate`.
**notice:** Make sure arguments passed to `IsolateJSFunction` are avaliable for isolate, such as primities and top level function.
Method `bind` can help to pass instance function to isolate:
## Use Dart Function (Breaking change in v0.3.0)
Js script returning function will be converted to `JSInvokable`. **It does not extend `Function`, use `invoke` method to invoke it**:
```dart
await jsFunc(await engine.bind(({thisVal}) {
// DO SOMETHING
}));
(func as JSInvokable).invoke([arg1, arg2], thisVal);
```
[This example](example/lib/main.dart) contains a complete demonstration on how to use this plugin.
## Breaking change in v0.3.0
`channel` function is no longer included by default.
Use js function to set dart object globally:
**notice:** evaluation returning `JSInvokable` may cause reference leak.
You should manually call `free` to release JS reference.
```dart
final setToGlobalObject = await engine.evaluate("(key, val) => this[key] = val;");
await setToGlobalObject("channel", methodHandler);
(obj as JSRef).free();
// or JSRef.freeRecursive(obj);
```
Arguments passed into `JSInvokable` will be freed automatically. Use `dup` to keep the reference.
```dart
(obj as JSRef).dup();
// or JSRef.dupRecursive(obj);
```
Since v0.3.0, you can pass a function to `JSInvokable` arguments, and `channel` function is no longer included by default. You can use js function to set dart object globally.
For example, use `Dio` to implement http in qjs:
```dart
final setToGlobalObject = await engine.evaluate("(key, val) => { this[key] = val; }");
await setToGlobalObject.invoke(["http", (String url) {
return Dio().get(url).then((response) => response.data);
}]);
setToGlobalObject.free();
```
In isolate, top level function passed in `JSInvokable` will be invoked in isolate thread. Use `IsolateFunction` to pass a instant function:
```dart
await setToGlobalObject.invoke([
"http",
IsolateFunction((String url) {
return Dio().get(url).then((response) => response.data);
}),
]);
```