Kamome

Kamome 是一个用于 iOS 和 Android 应用的 WebView 库。此库在 WebView 中的 JavaScript 和由 Swift、Objective-C、Java 或 Kotlin 编写的本地代码之间架起了一座桥梁。

Kamome 为 iOS 和 Android 提供了通用的 JavaScript 接口。

快速使用

从 JS 代码向本地代码发送消息

1. 从 JavaScript 代码发送消息

   // JavaScript
   
   // Send `echo` command.
   Kamome.send('echo', { message: 'Hello' }).then(function (result) {
       // Receive a result from the native code if succeeded.
       console.log(data.message);
   }).catch(function (error) {
       // Receive an error from the native code if failed.
       console.log(error);
   });

2. 在 iOS 上接收消息

   // Swift
   
   private var webView: WKWebView!
   private var kamome: KMMKamome!
   
   override func viewDidLoad() {
       super.viewDidLoad()
   
       // Create the Kamome object with default webView.
       var webView: AnyObject!
       kamome = KMMKamome.create(webView: &webView, class: WKWebView.self, frame: view.frame)
       self.webView = webView as? WKWebView
   
       // Register `echo` command.
       kamome.add(KMMCommand(name: "echo") { commandName, data, completion in
                 // Received `echo` command.
                 // Then send resolved result to the JavaScript callback function.
                 completion.resolve(with: ["message": data!["message"]!])
                 // Or, send rejected result if failed.
                 //completion.reject(with: "Echo Error!")
             })
   
       let htmlURL = Bundle.main.url(forResource: "index", withExtension: "html", subdirectory: "www")!
       self.webView.loadFileURL(htmlURL, allowingReadAccessTo: htmlURL)
       view.addSubview(self.webView)
   }

   [注意] 此框架仅支持 WKWebView。不支持 UIWebView。

3. 在 Android 上接收消息

   // Java
   
   private Kamome kamome;
   
   @Override
   protected void onCreate(Bundle savedInstanceState) {
       super.onCreate(savedInstanceState);
       setContentView(R.layout.activity_main);
   
       WebView webView = findViewById(R.id.webView);
   
       // Create the Kamome object with the webView.
       kamome = new Kamome(webView)
           .add(new Command("echo", new Command.IHandler() {  // Register `echo` command.
   
               @Override
               public void execute(String commandName, JSONObject data, ICompletion completion) {
                   // Received `echo` command.
                   // Then send resolved result to the JavaScript callback function.
                   HashMap<String, Object> map = new HashMap<>();
                   map.put("message", data.optString("message"));
                   completion.resolve(map);
                   // Or, send rejected result if failed.
                   //completion.reject("Echo Error!");
               }
           }));
   
       webView.loadUrl("file:///android_asset/www/index.html");
   }

从本地代码向 JS 代码发送消息

1. 在 iOS 上从本地代码发送消息

   // Swift
   
   // Send a data to JavaScript.
   kamome.sendMessage(with: ["greeting": "Hello! by Swift"], name: "greeting") { (commandName, result, error) in
       // Received a result from the JS code.
       guard let result = result else { return }
       print("result: \(result)")
   }

2. 在 Android 上从本地代码发送消息

   // Java
   
   // Send a data to JavaScript.
   HashMap<String, Object> data = new HashMap<>();
   data.put("greeting", "Hello! by Java");
   kamome.sendMessage(data, "greeting", new Kamome.ISendMessageCallback() {
   
       @Override
       public void onReceiveResult(String commandName, Object result, Error error) {
           // Received a result from the JS code.
           Log.d(TAG, "result: " + result);
       }
   });

3. 在 JavaScript 代码上接收消息

   // JavaScript
   
   // Add a receiver that receives a message sent by the native client.
   Kamome.addReceiver('greeting', function (data, resolve, reject) {
       // The data is the object sent by the native client.
       console.log(data.greeting);
   
       // Run asynchronous something to do...
       setTimeout(function () {
   
           // Return a result as any object or null to the native client.
           resolve('OK!');
           // If the task is failed, call `reject()` function.
           //reject('Error message');
       }, 1000);
   });

将库包含到您的项目中

1. JavaScript

1. 下载最新版本的 Kamome SDK

2. 导入 kamome.js 或 kamome.min.js

   <script src="/path/to/kamome[.min].js"></script>

   或者，您可以复制 kamome.js 文件中的所有代码到您的 JavaScript 中。

2. iOS 应用

CocoaPods

Kamome 通过 CocoaPods 提供。要安装它，只需将以下行添加到您的 Podfile 中

pod "KamomeSDK"

手动安装

将 KamomeSDK.framework 拖放到您的 Xcode 项目中

导入框架

在您的源代码中编写导入语句

import KamomeSDK

3. Android 应用

Gradle

在 build.gradle（项目级别）中添加以下代码。

allprojects {
    repositories {
        maven {
            url 'https://hituziando.github.io/kamome/android/repo'
        }
    }
}

在 build.gradle（应用级别）中添加以下代码。

dependencies {		
    implementation 'jp.hituzi:kamome:3.0.0'
}

手动安装

1. 将 kamome-x.x.x.jar 复制到 YOUR_ANDROID_STUDIO_PROJECT/app/libs 目录下
2. 在 AndroidStudio 中同步项目

配置

从 JS 代码到原生代码的请求超时

Kamome.send 方法在 JavaScript 中期望返回一个 resolve 或 reject 的响应，该响应将在一段时间后返回。如果请求超时，回调将调用 reject 并返回 requestTimeout 错误。您可以根据需要更改默认请求超时。请参阅以下内容。

// JavaScript

// Set default timeout in millisecond.
Kamome.setDefaultRequestTimeout(15000);

如果给定的时间小于或等于 0，则禁用请求超时功能。

如果您想单独指定请求超时，您可以在 Kamome.send 方法的第 4 个参数中设置以毫秒为单位的超时值。

// JavaScript

// Set a timeout in millisecond at 4th argument.
const promise = Kamome.send(commandName, data, null, 5000);

钩子

在调用之前和之后处理命令时钩子。

// JavaScript

// Hook.
Kamome.hook
    .before("getScore", function () {
        // Called before sending "getScore" command.
        Kamome.send("getUser").then(function (data) {
            console.log("Name: " + data.name);
        });
    })
    .after("getScore", function () {
        // Called after "getScore" command is processed.
        Kamome.send("getAvg").then(function (data) {
            console.log("Avg: " + data.avg);
        });
    });

// Send "getScore" command.
Kamome.send("getScore").then(function (data) {
    console.log("Score: " + data.score + " Rank: " + data.rank);
});

仅在浏览器中

当没有Kamome的iOS/Android原生客户端时，即当仅用浏览器运行时，您可以注册每个命令的处理过程。

// JavaScript

Kamome.browser
    .addCommand("echo", function (data, resolve, reject) {
        // Received `echo` command.
        // Then send resolved result to the JavaScript callback function.
        resolve({ message: data["message"] });
        // Or, send rejected result if failed.
        //reject("Echo Error!");
    });

更多信息，请参阅我的iOS示例项目和Android示例项目。