flutterSdk

Flutter App WebView 与 H5 交互 SDK。H5 应用嵌入 App WebView 中时，通过此 SDK 调用原生能力（拍照、扫码、录音、地理位置等）。

工作原理

H5 (WebView)                          App (Native)
   │                                     │
   │  SDK.method()                       │
   │  → GFAPP.postMessage(json)          │
   │    { message, data, handleId }       │
   │                                     │
   │                                     │ 解析命令
   │                                     │ 执行原生操作
   │                                     │ GFSDK.callback(json)
   │    resolve(data) ←──── json响应 ←────│

安装

npm

npm install @gf-tech/fluttersdk

CDN / 直接引入

<script src="js/flutterSdk.min.js"></script>

使用

ES Module

import flutterSdk from "@gf-tech/fluttersdk";

// SDK 已自动实例化并挂载到 window.GFSDK
const sdk = window.GFSDK;

浏览器直接引入

<script src="js/flutterSdk.min.js"></script>
<script>
    // SDK 已自动实例化并挂载到 window.GFSDK
    const sdk = window.GFSDK;
</script>

API 参考

账号系统

login(accountName, password)

H5 向 App 注册账号密码，App 端保存后可用于自动登录。

| 参数 | 类型 | 说明 | |------|------|------| | accountName | string | 账号名称 | | password | string | 密码 |

sdk.login("zhangsan", "123456")
    .then(() => console.log("登录成功"))
    .catch(err => console.error(err));

getLocalAccount()

H5 主动获取 App 本地已保存的账号密码。

返回值： Promise<{ accountName: string; password: string }>

sdk.getLocalAccount()
    .then(res => {
        console.log(res.accountName, res.password);
    })
    .catch(err => console.error(err));

设备信息

getNetWork()

获取当前网络状态。

返回值： Promise<"data" | "WIFI" | "offLine" | "unknow">

sdk.getNetWork()
    .then(res => console.log("网络状态：", res));
// "data" | "WIFI" | "offLine" | "unknow"

getGeoInfo()

获取地理位置信息。

返回值： Promise<{ latitude: number; longitude: number }>

sdk.getGeoInfo()
    .then(res => console.log(res.latitude, res.longitude));

WebView

closeWebview()

关闭当前 WebView 页面。

sdk.closeWebview();

openWebview(url)

打开新的 WebView 页面。

| 参数 | 类型 | 说明 | |------|------|------| | url | string | 目标网页地址 |

sdk.openWebview("https://example.com");

媒体

chooseImage()

选择或拍摄图片。

返回值： Promise<string[]> — 图片临时路径数组

sdk.chooseImage()
    .then(res => {
        console.log(res); // ["temp://xxx.jpg", ...]
    });

scanCode()

调用系统摄像头扫描二维码或条形码。

返回值： Promise<string> — 扫码结果字符串

sdk.scanCode()
    .then(res => console.log("扫码结果：", res));

startRecord()

开始录音。

sdk.startRecord();

stopRecord()

停止录音。

返回值： Promise<string> — mp3 临时路径

sdk.stopRecord()
    .then(res => console.log("录音文件：", res));

recordVideo()

录制视频。

返回值： Promise<string> — mp4 临时路径

sdk.recordVideo()
    .then(res => console.log("录像文件：", res));

震动

startShock()

开始震动。

sdk.startShock();

stopShock()

停止震动。

sdk.stopShock();

文件系统

uploadFile(config)

上传文件到服务器。

| 参数 | 类型 | 说明 | |------|------|------| | config.url | string | 上传地址 | | config.path? | string | 本地临时文件路径 | | config.params? | object | 上传附加参数 | | config.headers? | object | 上传请求头 |

返回值： Promise<any> — 服务器完整响应

sdk.uploadFile({
    url: "https://api.example.com/upload",
    path: "temp://xxx.jpg",
    params: { userId: "123" }
}).then(res => console.log(res));

saveFile(config)

保存文件到本地。

| 参数 | 类型 | 说明 | |------|------|------| | config.url | string | 文件远程地址 | | config.path? | string | 本地保存路径 |

sdk.saveFile({
    url: "https://example.com/file.pdf"
}).then(() => console.log("保存成功"));

openFile(config)

打开本地文件。

| 参数 | 类型 | 说明 | |------|------|------| | config.path | string | 文件路径 |

sdk.openFile({
    path: "temp://xxx.pdf"
}).then(() => console.log("打开成功"));

支付

pay(config)

调用原生支付能力（微信支付等）。

| 参数 | 类型 | 说明 | |------|------|------| | config | object | 支付配置，包含 type 和 params |

sdk.pay({
    type: "wx",
    params: {
        appid: "wx123",
        partnerid: "456",
        prepayid: "789",
        package: "Sign=WXPay",
        noncestr: "random",
        timestamp: "1699999999",
        sign: "signature"
    }
});

原生桥接协议

App 端需要注入以下全局对象：

// App WebView 注入的桥接对象
window.GFAPP = {
    postMessage: function(str) {
        const msg = JSON.parse(str);
        // msg.message: 命令名称，如 "GFAPP_GETNETWORK"
        // msg.data: 传递的参数
        // msg.handleId: 请求ID，回调时原样返回

        // 处理完成后调用回调
        window.GFSDK.callback(JSON.stringify({
            handleId: msg.handleId,
            err: "",        // 空字符串表示成功
            data: result    // 任意返回数据
        }));
    }
};

命令列表

| 命令 | 说明 | |------|------| | GFAPP_GETNETWORK | 获取网络状态 | | GFAPP_GETGEOINFO | 获取地理位置 | | GFAPP_CLOSEWEBVIEW | 关闭 WebView | | GFAPP_OPENWEBVIEW | 打开 WebView | | GFAPP_CHOOSEIMAGE | 选择图片 | | GFAPP_SCANCODE | 扫一扫 | | GFAPP_STARTRECORD | 开始录音 | | GFAPP_STOPRECORD | 停止录音 | | GFAPP_STARTVIDEORECORD | 录制视频 | | GFAPP_STARTSHOCK | 开始震动 | | GFAPP_STOPSHOCK | 停止震动 | | GFAPP_UPLOADFILE | 上传文件 | | GFAPP_SAVEFILE | 保存文件 | | GFAPP_OPENFILE | 打开文件 | | GFAPP_PAY | 支付 | | GFAPP_LOGIN | 账号登录 | | GFAPP_GETLOCALACCOUNT | 获取本地账号 |

错误处理

所有方法返回 Promise，需使用 .catch() 处理错误：

sdk.getNetWork()
    .then(res => console.log(res))
    .catch(err => alert("调用失败：" + err.message));

常见错误：

| 错误信息 | 原因 | |---------|------| | GFAPP未注入，请在App内打开此页面 | 页面未在 App WebView 内打开 | | callback:err=>xxx | 原生端返回了错误信息 |

浏览器调试

在浏览器中调试时，可在引入 SDK 之前添加 mock 桥接：

<script>
    if (!window.GFAPP) {
        window.GFAPP = {
            postMessage: function(str) {
                var msg = JSON.parse(str);
                setTimeout(function() {
                    var data = '';
                    if (msg.message === 'GFAPP_GETNETWORK') data = 'WIFI';
                    else if (msg.message === 'GFAPP_GETLOCALACCOUNT')
                        data = { accountName: 'test', password: '123' };
                    else data = 'ok';
                    window.GFSDK.callback(JSON.stringify({
                        handleId: msg.handleId,
                        err: '',
                        data: data
                    }));
                }, 100);
            }
        };
    }
</script>
<script src="js/flutterSdk.min.js"></script>

版本历史

| 版本 | 说明 | |------|------| | 0.0.3 | 重构 SDK 架构，新增 login / getLocalAccount | | 0.0.12 | 基础版本 |