jsf는 높은 성능을 갖춘 JavaScript 엔진으로, Flutter에 직접 통합되어 여러 플랫폼에서 JavaScript 코드를 원활하게 실행할 수 있게 해줍니다. 효율성과 사용 편의성을 고려해 설계되었으며, 외부 종속성 없이 Flutter 앱 내에서 JavaScript를 실행할 수 있도록 합니다. 완전한 JavaScript 상호 운용성을 지원하여 스크립트 삽입, 동적 로직 실행 또는 기존 JavaScript 라이브러리와의 통합에 이상적입니다. 실시간 스크립트 평가나 크로스플랫폼 호환성이 필요한 경우 특히 유용합니다. Android, iOS, Web, macOS, Windows, Linux를 지원하며, 다양한 환경에서 일관된 동작을 보장합니다.
사용 사례
Flutter 앱에서 동적 JavaScript 코드 실행
레거시 자바스크립트 라이브러리 통합
스크립트 가능한 UI 컴포넌트 활성화
실시간 코드 평가
크로스플랫폼 자바스크립트 실행
주요 기능
고성능 자바스크립트 엔진
네이티브 플러터 통합
다중 플랫폼 지원 (Android, iOS, Web, macOS, Windows, Linux)
Owned JsValue handles must be disposed. Handles received inside registerHandleFunction are borrowed and only valid for the callback duration. Call duplicate() if you need to keep one.
Dart Calls JavaScript
final add = js.evalValue('(function(a, b) { return a + b; })');
try {
final result = js.callValue(add, [20, 22]);
try {
print(result.toDart()); // 42
} finally {
result.dispose();
}
} finally {
add.dispose();
}
Use registerFunction() to expose a Dart function on the JavaScript global
object. JavaScript calls it like a normal function. Arguments are converted to
Dart values, and the return value is converted back to JavaScript:
js.registerFunction('dartSum', (args) {
return args.cast<num>().reduce((a, b) => a + b);
});
print(js.eval('dartSum(4, 5, 6)')); // 15
Callbacks can receive multiple arguments and return convertible values such as
Map, List, BigInt, and DateTime:
js.registerFunction('receiveMessage', (args) {
final name = args[0] asString;
final payload = args[1] asMap;
return {
'ok': true,
'message': '$name:${payload['count']}',
};
});
print(js.eval('receiveMessage("counter", {count: 3}).message')); // counter:3
Callbacks may return Future; JavaScript receives a Promise, so JS can use
await or .then() directly:
js.registerFunction('loadUser', (args) async {
return {'id': 1, 'name': 'Ada'};
});
final user = await js.evalAsync('loadUser().then((user) => user.name)');
With JavaScript async/await:
final name = await js.evalAsync('''
(async () => {
const user = await loadUser();
return user.name;
})()
''');
print(name); // Ada
registerFunction() converts JavaScript objects into Dart snapshots. Use
registerHandleFunction() when you need to preserve JavaScript object identity
or work with functions, class instances, circular objects, or host objects. It
passes arguments to Dart as JsValue handles:
js.registerHandleFunction('readModel', (args) {
final model = args.first;
final count = model.getPropertyValue('count');
try {
return count.toDart();
} finally {
count.dispose();
}
});
Arguments received by registerHandleFunction() are borrowed handles and are
only valid for the callback duration. Call duplicate() if you need to keep one
outside the callback, and dispose the owned handle when finished.
Promise
When JavaScript returns a Promise, evalAsync() gives you the resolved Dart
value:
final value = await js.evalAsync('Promise.resolve({ok: true})');
print(value); // {'ok': true}
evalAsync() is also the normal way to call async function:
final result = await js.evalAsync('''
async function compute() {
const value = await Promise.resolve(21);
return value * 2;
}
compute()
''');
print(result); // 42
Native platforms use the QuickJS module loader. Web includes JSF's registry
loader behind the same Dart API and supports in-memory modules, import maps,
relative resolution, module caching, static import, named/default/namespace
exports, re-exports, and literal dynamic import("module").
evalAsync(..., module: true) and dynamic import() on Web use the browser's
native ES Module/Blob loader, so browser-supported ESM syntax works, including
export * from, export { x } from, export * as ns from, and top-level
await. The in-memory module loader is intended for application scripts and
Flutter asset modules; it does not fetch network module URLs.
A JsRuntime owns one QuickJS runtime and one context.
Use a runtime from the same Dart isolate that created it.
Dispose every runtime with dispose().
Dispose owned JsValue handles when you are done.
Do not use handles after their runtime is disposed.
Disposing a runtime also releases owned JsValue handles still registered under that runtime, but explicit dispose() remains recommended to control memory peaks.
Testing
Integration tests live in example/integration_test:
cd example
flutter drive --driver=integration_test/driver.dart --target=integration_test/js_runtime_test.dart -d macos
The test suite covers primitive conversion, BigInt, object/array conversion, handle calls, Dart callbacks, promise waiting, module loading, exceptions, timeouts, Unicode, typed arrays, circular objects, and multiple runtimes.