flutter_qjs
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 for quickjs engine
firstly, create a flutterqjs
object, then call dispatch
to dispatch event loop:
final engine = flutterqjs()
engine.dispatch();
use evaluate
method to run js script, now you can use it synchronously, or use await to resolve promise
:
try {
print(engine.evaluate(code ?? ''));
} catch (e) {
print(e.tostring());
}
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.
engine.port.close(); // stop dispatch loop
engine.close(); // close engine
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 |
jsfunction(…args) isolatejsfunction(…args) |
function(….args) |
future | promise |
notice: function
can only be sent from js to dart.
invoke dart function
a global javascript function channel
is presented to invoke dart function.
in constructor, pass handler function to manage javascript call. for example, you can use dio
to implement http in javascript:
final engine = flutterqjs(
methodhandler: (string method, list arg) {
switch (method) {
case "http":
return dio().get(arg[0]).then((response) => response.data);
default:
throw exception("no such method");
}
},
);
then, in java script you can use channel function to invoke methodhandler
, make sure the second parameter is a list:
channel("http", ["http://example.com/"]);
use modules
es6 module with import
function is supported and can be managed in dart with modulehandler
:
final engine = flutterqjs(
modulehandler: (string module) {
if(module == "hello")
return "export default (name) => `hello ${name}!`;";
throw exception("module not found");
},
);
then in javascript, import
function is used to get modules:
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
create a isolateqjs
object, pass handlers to implement js-dart interaction and resolving modules. the methodhandler
is used in isolate, so the handler function must be a top-level function or a static method. async function such as rootbundle.loadstring
can be used now to get modules:
dynamic methodhandler(string method, list arg) {
switch (method) {
case "http":
return dio().get(arg[0]).then((response) => response.data);
default:
throw exception("no such method");
}
}
final engine = isolateqjs(
methodhandler: methodhandler,
modulehandler: (string module) async {
return await rootbundle.loadstring(
"js/" + module.replacefirst(new regexp(r".js
quot;), "") + ".js"); }, ); // 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:
try {
print(await engine.evaluate(code ?? '', "<eval>"));
} catch (e) {
print(e.tostring());
}
method close
can destroy quickjs runtime that can be recreated again if you call evaluate
.
this example contains a complete demonstration on how to use this plugin.
for macos & ios developer
i am new to xcode and ios developing, and i cannot find a better way to support both simulators and real devices without combining the binary frameworks. to reduce build size, change the s.vendored_frameworks
in ios/flutter_qjs.podspec
to the specific framework.
for simulator, use:
s.vendored_frameworks = `build/debug-iphonesimulator/ffiquickjs.framework`
for real device, use:
s.vendored_frameworks = `build/debug-iphoneos/ffiquickjs.framework`
two additional notes:
- quickjs built with
release
config has bug in resolvingpromise
. please let me know if you know the solution. ios/make.sh
limits the build architectures to avoid combining conflicts. change themake.sh
to support another architectures.
Comments are closed.