JavaScript 与 Message Bridge

LitheView 提供同步表达式、异步 Promise 和页面消息三类 JavaScript 集成方式。结果和消息都使用 JSON 作为 ABI 边界。

同步表达式

ltv_eval_result_t result =
    ltv_view_eval(view, "({title: document.title, ready: true})");

if (result.code == LTV_OK) {
  UseJson(result.json_result);
} else {
  LogError(result.error);
}

ltv_free(result.json_result);
ltv_free(result.error);

结果必须可以序列化为 JSON。json_result 和 error 由调用者持有，ltv_free(nullptr) 是安全的。

异步执行与 Promise

void LTV_CALLBACK OnResult(ltv_view_t view,
                           const ltv_javascript_result_t* result,
                           void* user_data) {
  if (result->code == LTV_OK) {
    UseBorrowedJson(result->json_result);
  }
}

ltv_view_execute_javascript(
    view,
    "fetch('/api/state').then(response => response.json())",
    &OnResult,
    user_data);

Promise 会被等待。callback 参数及其字符串只在本次 callback 中有效；View 提前销毁时，未完成 callback 不再执行。

页面到宿主

页面可以发送任意可序列化 JSON 值：

window.litheview.postMessage({type: 'save', documentId: 42});

宿主通过 ltv_view_client_t.on_javascript_message 接收：

void LTV_CALLBACK OnMessage(ltv_view_t view,
                            const ltv_javascript_message_t* message,
                            void* user_data) {
  HandleJson(message->json_value, message->source_url,
             message->is_main_frame != 0);
}

宿主到页面

ltv_view_post_javascript_message(
    view, R"({"type":"document-updated","id":42})");

页面可以使用单一 handler 或事件监听器：

window.litheview.onmessage = value => {
  console.log('host message', value);
};

window.addEventListener('message', event => {
  console.log(event.data);
});

传入宿主 API 的字符串必须是一段完整且合法的 JSON；无效 JSON 返回 LTV_ERR_INVALID_ARG。