前端通信 API

概述

JadeView 提供了简洁易用的前端 API，用于与后端进行通信。这些 API 基于自定义协议实现，具有低延迟、高吞吐量和良好的异步支持特性。

注意

前端 API 仅在 JadeView 1.0 及以上版本中可用。

API 详细说明

1. jade.invoke(command, payload)

调用后端 API 并获取返回结果，返回一个 Promise 对象。

参数

• command (String) - 要调用的后端命令名称
• payload (Any, 可选) - 传递给后端的数据，可以是字符串、对象、数组等

返回值

• Promise<Any> - 后端返回的结果

示例

// 调用后端 message 命令，发送消息，等待后端返回结果
async function sendMessage() {
  try {
    const messageData = {
      timestamp: Date.now(),
      data: '测试消息',
    };
    const result = await jade.invoke('message', messageData);
    console.log('后端返回结果:', result);
  } catch (error) {
    console.error('调用失败:', error);
  }
}

// 设置窗口背景材料, 等待后端返回结果
async function setBackdrop(backdropType) {
  try {
    await jade.invoke('setBackdrop', backdropType);
    console.log('背景材料设置成功:', backdropType);
  } catch (error) {
    console.error('设置背景材料失败:', error);
  }
}

// 设置窗口主题（异步模式：调用命令 + 监听事件）
function setTheme(theme) {
  // 调用后端 setTheme 命令
  jade.invoke('setTheme', theme)
    .then(result => {
      console.log('主题设置命令发送成功:', result);
    })
    .catch(error => {
      console.error('发送主题设置命令失败:', error);
    });
  
  // 使用 on API 监听主题设置事件
  const unsubscribe = jade.on('setTheme', function (payload) {
      console.log('收到主题设置消息:', payload);
      // 处理主题设置逻辑
      
      // 完成后取消订阅（如果不再需要）
      unsubscribe();
  });
}

对应的 C++ 回调函数示例

// message 命令的 C++ 回调函数示例
const char* message_callback(uint32_t window_id, const char* event_data) {
    // event_data 包含前端传递的 JSON 数据
    // 例如: {"timestamp": 1234567890, "data": "测试消息"}
    printf("收到 message 命令，窗口ID: %u, 数据: %s\n", window_id, event_data);

    // 处理逻辑
    
    // 动态分配内存并格式化返回结果
    char* result = (char*)malloc(256);
    snprintf(result, 256, "{\"status\": \"success\", \"message\": \"收到消息\", \"window_id\": %u, \"data\": %s}", 
             window_id, event_data);
    
    // 返回消息结果
    return result;
}

// setBackdrop 命令的 C++ 回调函数示例
const char* set_backdrop_callback(uint32_t window_id, const char* event_data) {
    printf("收到 setBackdrop 命令，窗口ID: %u, 背景类型: %s\n", window_id, event_data);

    // 处理设置背景材料逻辑

    // 返回成功结果 - 使用 jade_text_create 创建安全文本指针
    return jade_text_create("{\"success\": true, \"result\": \"背景材料设置完成\"}");
}

// setTheme 命令的 C++ 回调函数示例（异步处理）
const char* set_theme_callback(uint32_t window_id, const char* event_data) {
    printf("收到 setTheme 命令，窗口ID: %u, 主题: %s\n", window_id, event_data);

    // 1. 立即返回成功，通知前端命令已接收 - 使用 jade_text_create 创建安全文本指针
    char result[128];
    snprintf(result, sizeof(result), "{\"status\": \"success\", \"message\": \"主题设置命令已接收，将异步处理\"}");
    
    // 2. 异步处理主题设置逻辑
    // 注意：在真实场景中，这部分可能在另一个线程执行
    
    // 3. 处理完成后，发送事件回前端
    // 假设 send_event 是 JadeView 提供的发送事件函数
    char event_payload[256];
    snprintf(event_payload, sizeof(event_payload), 
             "{\"theme\": \"%s\", \"window_id\": %u, \"status\": \"completed\", \"timestamp\": %lld}", 
             event_data, window_id, (long long)time(NULL));
    
    // 发送 setTheme 事件到前端，前端通过 jade.on('setTheme') 监听
    send_event(window_id, "setTheme", event_payload);
    
    // 返回初始结果 - 使用 jade_text_create 创建安全文本指针
    return jade_text_create(result);
}

2. jade.on(eventName, callback)

订阅后端发送的事件，当后端触发该事件时，调用指定的回调函数。

参数

• eventName (String) - 要监听的事件名称
• callback (Function) - 事件触发时调用的回调函数，接收一个参数表示事件数据

返回值

• Function - 取消订阅的函数，调用此函数可停止监听事件

示例

// 监听主题设置事件
const unsubscribeTheme = jade.on('setTheme', function (payload) {
  console.log('收到主题设置事件:', payload);
  // 处理主题设置逻辑
});

// 监听窗口状态变化事件
const unsubscribeWindowState = jade.on(
  'window-state-changed',
  function (payload) {
    console.log('窗口状态变化:', payload);
    // 处理窗口状态变化逻辑
  },
);

// 取消订阅主题设置事件
// unsubscribeTheme();

最佳实践

1. 使用 async/await - 充分利用 Promise 特性，避免回调地狱
2. 错误处理 - 始终使用 try/catch 捕获可能的错误
3. 合理使用事件订阅 - 只订阅必要的事件，及时取消不再需要的订阅
4. 保持 payload 简洁 - 只传递必要的数据，减少序列化开销
5. 避免阻塞操作 - 不要在事件回调中执行耗时操作，避免影响UI响应

性能优化

• JadeView API 设计为低延迟（通常 <1ms 往返）
• 支持高并发请求（建议同时请求数不超过 100）
• 使用连接池复用，减少连接建立开销
• 优化的 JSON 处理，减少序列化/反序列化开销

常见问题

1. 调用失败，提示 "Failed to fetch"

   • 检查命令名称是否正确
   • 确保后端已正确注册该命令
   • 检查网络连接（尽管是本地通信，但协议栈仍可能出现问题）

2. 事件不触发

   • 检查事件名称是否正确
   • 确保后端正在发送该事件
   • 检查订阅是否在事件发送之前执行

3. 性能问题

   • 减少不必要的 API 调用
   • 合并多个相关请求
   • 及时取消不再需要的事件订阅

4. 调用失败，提示 "JadeView API not available" 或类似错误

   • 原因：JadeView 前端 API 仅支持通过 local-server-api 创建的服务器页面
   • 解决方案：确保你的页面是通过 JadeView 本地服务器提供的，而不是直接打开的本地文件或来自其他服务器
   • 参考：创建本地服务器 文档

示例代码

// 初始化时设置背景材料
(async function () {
  try {
    await jade.invoke('setBackdrop', 'mica');
    console.log('初始背景材料设置成功');
  } catch (error) {
    console.error('初始背景材料设置失败:', error);
  }
})();

// 监听窗口状态变化
jade.on('window-state-changed', function (data) {
  console.log('窗口状态变化:', data);
  // 更新UI以反映窗口状态
});

// 按钮点击事件处理
document.getElementById('sendBtn').addEventListener('click', async function () {
  const message = document.getElementById('msgInput').value;
  try {
    const result = await jade.invoke('message', message);
    console.log('发送成功:', result);
  } catch (error) {
    console.error('发送失败:', error);
  }
});

性能表现

根据实际测试，JadeView API 具有出色的性能表现：

• 前后端通信往返延迟：<1ms
• 支持并发请求数：>800 请求/秒
• CPU 消耗降低：30%-50%
• 内存占用降低：20%-40%

总结

JadeView 前端 API 提供了简洁、高效的方式与后端通信，具有以下特点：

• 低延迟（通常 <1ms 往返）
• 高吞吐量（支持高并发请求）
• 良好的异步支持（Promise/async-await）
• 简单易用的 API 设计
• 可靠的错误处理机制

通过合理使用这些 API，可以构建出高性能、响应迅速的桌面应用。