Skip to content

前端侧:用 bridge-client 调 Rust ​

模板里已经配好了 @aura/bridge-client,你只需要 createBridgeClient 一次,init() 一次,然后 call(path, params) 就行。


初始化 ​

在入口或顶层组件里做一次:

tsx
import { createBridgeClient } from '@aura/bridge-client';

// bridgePort 必须和 rust/main.rs 里的 port 一致(模板默认 3456)
const bridge = createBridgeClient({ bridgePort: 3456 });

// 判断当前运行在哪个通道
bridge.init().then((mode) => {
  console.log('bridge mode:', mode);   // "native" | "http" | "disconnected"
});
  • dev 模式(浏览器 / Lynx Explorer):自动走 HTTP,fetch /bridgePort/dispatch
  • 真机(Android / iOS / 鸿蒙 App):自动走 NativeModules.Bridge.dispatchAsync
  • 两种通道的接口完全一样,业务代码不需要区分

手机联调时(Lynx Explorer),因为没有页面 origin,相对 URL 会报错,需要先设置电脑 IP:

tsx
bridge.setBridgeHost('192.168.1.100');  // 开发机 IP(必须和 dev-server 同网段)

调用业务路由 ​

tsx
// 调 Rust 的 #[route("/hello")] 或 aura.register("/hello", ...)
const res = await bridge.call<{ greeting: string; lang: string }>('/hello', {
  name: '小明',
});
// bridge.call 会自动拆掉信封,直接给你 response.data
// 出错时 throw BridgeError,包含 code 和 message

带错误处理:

tsx
import { BridgeError } from '@aura/bridge-client';

try {
  const data = await bridge.call<{ doubled: number }>('/sync', { count: 21 });
  console.log(data.doubled);  // 42
} catch (e) {
  if (e instanceof BridgeError) {
    console.error(`Rust 侧返回 ${e.code}: ${e.message}`);
  } else {
    console.error('网络或通道异常', e);
  }
}

订阅 Rust 发来的事件 ​

两种模式都能收到事件:

  • native(真机):GlobalEventEmitter,由原生壳把 Rust emit 转成全局事件。
  • dev / HTTP:轮询 dev-server 的 /events(默认 1s 一次,仅开发期;aura-dev-server::DevPlatform 负责把 emit 放进队列)。
tsx
// Rust 侧:ctx.platform().emit("progress", { percent: 50 })
const unsubscribe = bridge.on('progress', (_event, payload) => {
  console.log('payload:', JSON.parse(payload));  // { percent: 50 }
});

// 页面卸载时退订(同一事件可以多个订阅者,互不影响)
unsubscribe();

@aura/ui 组件 ​

模板已经装好了,CSS 全部 aura- 前缀,不会和你的业务样式撞。

tsx
import { SubPage, TabBar, TabBarItem } from '@aura/ui';
import type { AuraTheme } from '@aura/theme';

// TabBar
<TabBar
  items={[
    { key: 'home', label: '首页', icon: (active) => <text>{active ? '●' : '○'}</text> },
    { key: 'settings', label: '设置', icon: (active) => <text>{active ? '■' : '□'}</text> },
  ]}
  active={tab}
  onChange={(key) => setTab(key as TabKey)}
  theme={theme}
/>

// 二级页
<SubPage title="关于" onBack={() => ...} theme={theme}>
  <text>内容...</text>
</SubPage>

@aura/theme 主题切换 ​

tsx
import { createTheme, darkTheme, lightTheme } from '@aura/theme';

const LIGHT = createTheme(lightTheme, { brand: '#2F7DF6' });
const DARK = createTheme(darkTheme, { brand: '#2F7DF6' });

// theme 是一个完整的语义 token 对象:
theme.background     // 页面底色
theme.surface        // 卡片底色
theme.brand          // 主题色(TabBar active / 按钮)
theme.text           // 主文字色
theme.textSecondary  // 副文字色
theme.spacing.md     // 间距(8px 基准)
theme.radius.md      // 圆角(8px 基准)
theme.fontSize.body  // 字号(16px 基准)

@aura/i18n 前端文案 ​

模板已经配好了 locales 文件和 i18n 单例:

tsx
// frontend/src/locales/zh-CN.json
{ "home": { "title": "首页", "hint": "点下面试试" } }

// 使用
import { i18n } from './i18n.js';

<text>{i18n.t('home.title')}</text>

// 切语言
i18n.setLang('en');
i18n.getLang();           // 'en'
i18n.subscribe(() => { /* 重渲染整棵树(Lynx 没有响应式 i18n 绑定) */ });

出错了怎么办 ​

报错原因排查
后端服务未连接dev-server 没启动先 pnpm dev:rust
HTTP Bridge error: 500Rust handler 抛了错看 dev-server 终端日志
NativeModules.Bridge is null跑在浏览器却期待原生dev 模式正常,真机 App 才走 native
Lynx 运行时报 相对 URL 不可用手机联调忘了 setBridgeHostbridge.setBridgeHost('192.168.1.100')
BridgeError 404Rust 侧路由没注册检查 build_router()、#[route] + link_routes!

lynx-aura · 跨平台本地应用开发框架