Flutter JavaScript交互插件 js_wrapping 的使用

js_wrapping 是一个允许开发者为 JavaScript 对象定义良好类型的接口的 Dart 包。通过这个包，你可以创建与 JavaScript 对象交互的 Dart 类，并且这些类具有明确的 Dart API，包括类型注释、构造函数，甚至可选和命名参数。

编写 JS Wrapper

假设有一个 JavaScript 类如下：

LatLng = function(lat, lng) {
  this.lat = lat;
  this.lng = lng;
}
LatLng.prototype.equals = function(other) {
  return this.lat === other.lat && this.lng === other.lng;
}

你可以创建一个包装类如下：

@JsName()
abstract class LatLng {
  factory LatLng(num lat, num lng, [bool noWrap]) => $js;

  bool equals(LatLng other);
  num get lat => _lat();
  @JsName('lat')
  num _lat();
  num get lng => _lng();
  @JsName('lng')
  num _lng();
  String toString();
  String toUrlValue([num precision]);
}

一旦生成器执行完毕，你就可以使用 LatLng 来包装一个 JavaScript 的 LatLng 对象。

配置和初始化

添加依赖

在你的 pubspec.yaml 文件中添加以下内容：

dependencies:
  js_wrapping: ^0.6.0
dev_dependencies:
  js_wrapping_generator: ^0.6.0

运行生成器

参考 source_gen package 的运行生成器部分。

使用方法

定义 Typed JavaScript Interfaces

要创建一个 Typed JavaScript Interface，你需要从创建一个标记有 @JsName() 的类开始。它将作为创建 JavaScript 接口的模板。

@JS('google.maps')
library google_maps.sample.simple;

import 'package:js_wrapping/js_wrapping.dart';

@JsName()
abstract class LatLng {
  factory LatLng(num lat, num lng, [bool noWrap]) => $js;

  bool equals(LatLng other);
  num get lat => _lat();
  @JsName('lat')
  num _lat();
  num get lng => _lng();
  @JsName('lng')
  num _lng();
  String toString();
  String toUrlValue([num precision]);
}

生成器会生成一个新的库 mylib.g.dart，包含以下内容：

// GENERATED CODE - DO NOT MODIFY BY HAND

// **************************************************************************
// JsWrappingGenerator
// **************************************************************************

// Copyright (c) 2015, Alexandre Ardhuin. All rights reserved. Use of this
// source code is governed by a BSD-style license that can be found in the
// LICENSE file.

@JS('google.maps')
library google_maps.sample.simple;

import 'package:js_wrapping/js_wrapping.dart';

@JS()
class LatLng {
  external LatLng(num lat, num lng, [bool noWrap]);

  external bool equals(LatLng other);

  external String toString();

  external String toUrlValue([num precision]);
}

extension LatLng$Ext on LatLng {
  num get lat => _lat();
  num get lng => _lng();

  num _lat() => callMethod(this, 'lat', []);

  num _lng() => callMethod(this, 'lng', []);
}

构造函数用于创建 JS 对象

如果 LatLng 是一个 JavaScript 对象/函数，你可以在 JavaScript 中用 LatLng() 创建一个新实例。为了使 Dart 侧能够创建这样的 JavaScript 实例，你需要定义一个 factory 构造函数：

@JsName()
abstract class LatLng {
  factory LatLng(num lat, num lng, [bool noWrap]) => $js;
}

这将生成：

@JS()
class LatLng {
  external LatLng(num lat, num lng, [bool noWrap]);
}

现在可以通过 LatLng() 在 Dart 中实例化 JavaScript 对象。

属性和访问器

可以向类中添加属性或抽象的 getter/setter，并生成访问底层 JavaScript 对象属性的 getter 和 setter。

@JsName()
abstract class Person {
  factory Person() => $js;
  String firstname, lastname;
  int get age;
  void set email(String email);
}

这将生成：

@JS()
class Person {
  external Person();
  external String get firstname;
  external set firstname(String value);
  external String get lastname;
  external set lastname(String value);
  external int get age;
  external void set email(String email);
}

方法

抽象方法将以相同的方式实现：

@JsName()
abstract class Person {
  factory Person() => $js;
  String sayHelloTo(String other);
  void fall();
}

这将生成：

@JS()
class Person {
  external Person();

  external String sayHelloTo(String other);

  external void fall();
}

名称使用

构造函数

你可以通过在类上提供 JsName('MyClassName') 来覆盖名称：

@JsName('People')
abstract class Person {
  factory Person() => $js;
  String sayHelloTo(Person other);
  Person get father;
}

成员

你可以通过在成员上提供 JsName('myMemberName') 来覆盖名称：

@JsName()
abstract class Person {
  @JsName('daddy') Person get father;
}

小技巧和窍门

匿名对象

实例化匿名 JavaScript 对象是很常见的。如果你的私有类映射到一个匿名对象，可以在其上添加 @anonymous 注解：

@JsName()
@anonymous
abstract class Foo {
  factory Foo() => $js;
}

这将生成：

@JS()
@anonymous
class Foo {
  external factory Foo();
}

从方法创建 getter

如果一个 JavaScript 对象有一个 getXxx() 函数，你想在 Dart 端将其映射为 get xxx，你可以这样做：

@JsName()
abstract class Person {
  String get firstname => _getFirstname();
  @JsName('getFirstname')
  String _getFirstname();
}

这个方法可以应用于任何你想进行的重定向。

示例 Demo

下面是一个完整的示例 demo，展示了如何使用 js_wrapping 插件来与 JavaScript 进行交互：

JavaScript 代码

function LatLng(lat, lng) {
  this.lat = lat;
  this.lng = lng;
}

LatLng.prototype.equals = function(other) {
  return this.lat === other.lat && this.lng === other.lng;
};

LatLng.prototype.toString = function() {
  return `Lat: ${this.lat}, Lng: ${this.lng}`;
};

Dart 代码

首先，在 pubspec.yaml 中添加依赖：

dependencies:
  js_wrapping: ^0.6.0
dev_dependencies:
  js_wrapping_generator: ^0.6.0

然后，创建一个 Dart 文件（例如 lat_lng.dart）：

import 'package:js_wrapping/js_wrapping.dart';

@JsName()
abstract class LatLng {
  factory LatLng(num lat, num lng) => $js;

  bool equals(LatLng other);
  num get lat => _lat();
  @JsName('lat')
  num _lat();
  num get lng => _lng();
  @JsName('lng')
  num _lng();
  String toString();
}

接下来，运行生成器以生成相应的 Dart 代码：

flutter pub run build_runner build

最后，在你的 Flutter 应用中使用这个类：

import 'package:flutter/material.dart';
import 'lat_lng.g.dart'; // 生成的文件

void main() {
  runApp(MyApp());
}

class MyApp extends StatelessWidget {
  [@override](/user/override)
  Widget build(BuildContext context) {
    final latLng = LatLng(39.9042, 116.4074); // 创建一个 LatLng 实例
    print(latLng.toString()); // 输出: Lat: 39.9042, Lng: 116.4074

    return MaterialApp(
      home: Scaffold(
        appBar: AppBar(title: Text('js_wrapping Demo')),
        body: Center(child: Text('Check console for output')),
      ),
    );
  }
}