Dart 튜토리얼 27편: JavaScript interop 현대 방식(dart:js_interop·JS types·package:web)

Why#

NOTE

JS 라이브러리를 쓰려면 먼저 JS 쪽에서 사용할 API가 접근 가능한 위치에 있어야 합니다.
그 다음 Dart에서 그 멤버를 선언하고 호출할 수 있습니다.

What#

NOTE

이 방식에서는 “JS API를 global JS scope 어딘가에 노출한 뒤”, Dart에서 external interop 멤버로 접근합니다.
또한 top-level interop 멤버는 @JS()로 표시해야 한다고 설명합니다.

How#

TIP

예시로 JS의 globalThis.name과 함수 isNameEmpty를 만들고, Dart에서 getter/setter/함수로 선언하는 코드가 제시됩니다.

1
@JS()
2
external String get name;
3

4
@JS()
5
external set name(String value);
6

7
@JS()
8
external bool isNameEmpty();

Watch out#

WARNING

top-level external은 dart:ffi 같은 다른 의미의 external과 구분해야 하므로 @JS()가 필수라는 설명이 제시됩니다.
즉, annotation을 빼면 interop 의도가 전달되지 않습니다.

결론: JS interop는 “JS 글로벌 노출 → Dart @JS() + external 선언” 흐름으로 시작합니다.

Why#

NOTE

JS 값은 구조가 있지만, Dart에서 타입이 없으면 자동 완성/정적 검사/설계 의도가 흐려지기 쉽습니다.
따라서 JS 값에 대응하는 Dart 타입을 만들어두는 것이 유리합니다.

What#

NOTE

interop 타입은 Dart가 제공하는 JS 타입(JSObject 등)을 감싸는 extension type로 선언할 수 있다고 설명됩니다.
또한 “런타임에서 실제 Window라는 보장”이 없다는 점도 함께 설명됩니다.

How#

TIP

다음은 JSObject를 표현 타입으로 갖는 interop 타입 예시입니다.

1
extension type Window(JSObject _) implements JSObject {}

Watch out#

WARNING

런타임 보장이 없으므로, 특정 JS 타입임을 가정하고 사용하면 위험할 수 있습니다.
따라서 필요한 경우 interop를 통해 타입을 확인하는 방법을 별도로 사용해야 한다는 안내가 있습니다.

결론: interop 타입은 “타입 안정성/가독성”을 위해 만들되, 런타임 보장 여부를 구분해야 합니다.

Why#

NOTE

값을 Dart↔JS로 넘기는 순간, 성능과 의미(참조/복사) 문제가 생길 수 있습니다.
그래서 변환은 “필요할 때만” 명시적으로 수행하는 기준이 필요합니다.

What#

NOTE

JS types는 JS 접두사를 가진 타입(JSString, JSNumber 등)이며, Dart 값과 JS 값을 컴파일 시점에 구분하기 위한 체계로 설명됩니다.
변환은 Dart→JS는 toJS, JS→Dart는 toDart... 형태로 제공된다고 설명됩니다.

How#

TIP

변환 예시는 다음과 같이 제시됩니다.

1
String str = 'hello world';
2
JSString jsStr = str.toJS;

1
JSNumber jsNum = ...;
2
int integer = jsNum.toDartInt;

Watch out#

WARNING

JS↔Dart 변환은 컴파일 타깃(JS vs Wasm)에 따라 비용/의미가 달라질 수 있고, List 같은 값은 참조/프록시/복사 여부를 가정하지 말라고 경고합니다.
즉, 변환 후 두 값 사이의 연결 관계에 기대지 말아야 합니다.

결론: 값 이동은 toJS/toDart로 통제하고, 변환의 비용/의미 차이를 전제로 코드를 작성합니다.

Why#

NOTE

Wasm 타깃을 고려하면, 기존 dart:html 같은 코어 웹 라이브러리는 제약이 될 수 있습니다.
그래서 장기적으로는 package:web로 이동하는 방향이 제시됩니다.

What#

NOTE

package:web는 브라우저 API 접근을 제공하고, Wasm 호환을 위해 dart:js_interop 기반으로 설계되었다고 설명됩니다.
또한 dart:html 등은 deprecated이며 Wasm에서 지원되지 않는다고 안내합니다.

How#

TIP

기본 사용 예시는 다음과 같이 제시됩니다.
코드 블록 주석은 한글로 맞췄습니다.

1
import 'package:web/web.dart';
2

3
void main() {
4
  final div = document.querySelector('div')!;
5
  div.text = 'Text set at ${DateTime.now()}';
6
}

마이그레이션은 dart:html import를 제거하고 package:web/web.dart로 바꾸는 흐름이 제시됩니다.

1
import 'dart:html' as html; // 제거
2
import 'package:web/web.dart' as web; // 추가

Watch out#

WARNING

package:web는 List를 그대로 반환하지 않는 API가 있고, 런타임 타입 테스트(is)가 dart:html과 다르게 동작할 수 있다는 안내가 있습니다.
즉, 마이그레이션은 import만 바꾸는 작업이 아니라, 타입/컬렉션/테스트 방식까지 함께 바꾸는 작업이 될 수 있습니다.

결론: 브라우저 API 접근은 package:web로 표준화하고, 마이그레이션 시 타입/리스트/테스트 차이를 함께 처리합니다.