主题
前端侧:用 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: 500 | Rust handler 抛了错 | 看 dev-server 终端日志 |
NativeModules.Bridge is null | 跑在浏览器却期待原生 | dev 模式正常,真机 App 才走 native |
Lynx 运行时报 相对 URL 不可用 | 手机联调忘了 setBridgeHost | bridge.setBridgeHost('192.168.1.100') |
| BridgeError 404 | Rust 侧路由没注册 | 检查 build_router()、#[route] + link_routes! |