用Tauri跨平台框架在鸿蒙PC上开发闪控枢纽:FlickOrb的闪控球、闪控窗与沙箱暂存舱实践
用Tauri跨平台框架在鸿蒙PC上开发闪控枢纽:FlickOrb的闪控球、闪控窗与沙箱暂存舱实践
欢迎加入开源鸿蒙PC社区: https://harmonypc.csdn.net/
欢迎在PC社区平台申请新建项目:https://atomgit.com/OpenHarmonyPCDeveloper
前言
在鸿蒙PC(HarmonyOS PC)上做桌面应用,很多开发者第一反应是"是不是只能用 ArkTS?“答案是:完全不必。借助 Tauri 这套以 Rust 为内核的跨平台框架,我们可以把业务逻辑全部放进 Rust,前端只保留一层 HTML/CSS/JS 的"皮”,最终以一个标准 HAP 包落进鸿蒙PC 真机运行。笔者此前已经用 Tauri 跨平台框架在 鸿蒙PC 上完成了待办清单、便签、日历、性能实验室等十余个练手项目,这次带来的第十五个作品,聚焦一个桌面端非常经典的交互形态——悬浮球与悬浮窗,项目定名 FlickOrb 闪控枢纽。
FlickOrb 的产品隐喻是"闪控":一颗可以拖拽停靠到屏幕四角的闪控球,点开后展开一扇闪控窗,里面集成了剪贴暂存、便签速记、轻量计数器三种轻量工具,主界面则提供暂存架、能力矩阵与交互日志三栏。所有数据经 Rust 内核做校验、环形截断与沙箱持久化,前后端通过 Tauri 的 invoke 通道以 JSON 双向通信。
本文会从工程结构讲起,逐一拆解 Rust 命令集、沙箱存储回退链、前端闪控球的拖拽停靠逻辑、能力矩阵的如实标注策略,最后给出测试与真机运行结果。全部代码托管在 AtomGit 的开源鸿蒙PC开发者组织下,欢迎参考与共建。
关键词: Tauri,跨平台框架,鸿蒙PC,HarmonyOS PC,Rust,悬浮球,悬浮窗,闪控,沙箱持久化,IPC,HAP,开源鸿蒙
一、为什么选 Tauri 跨平台框架做鸿蒙PC应用
先回答一个高频问题:Tauri 官方主线并不包含 HarmonyOS 目标,那这套跨平台框架是如何跑在 鸿蒙PC 上的?关键在于三点组合:
- Tauri 鸿蒙分支 + Rust
cdylib:Rust 侧以动态库(libflickorb_lib.so)形式编译到aarch64-unknown-linux-ohos目标,前端资产在编译期直接嵌入这个动态库; - ArkTS
NativeAbility承载:鸿蒙侧的 ArkTS 入口负责加载动态库并创建 ArkWeb 视图,WebView 的内核由 Tauri 的 wry 层对接; invokeIPC 通道:前端 JS 调用invoke("命令名", 参数),Rust 命令返回可序列化结构体,整条链路是类型安全的 JSON。
对开发者而言,收益非常直接:业务逻辑用 Rust 写一次,配上测试就能保证质量;界面用最熟悉的 Web 技术栈;产物是一个标准 HAP,可以正常签名、安装到 鸿蒙PC 真机。相比纯 ArkTS 方案,这套跨平台框架路线把"逻辑层"与"视图层"解耦得更彻底,也让熟悉 Rust/Web 的开发者几乎零成本迁移到 鸿蒙PC 生态。
二、FlickOrb 的产品与架构设计
2.1 三个核心概念
- 闪控球(Flash Ball):一颗悬浮在界面上的光球,支持 pointer 拖拽,可停靠到屏幕四角(右下/右上/左下/左下),停靠方位会写入后端状态并持久化;
- 闪控窗(Flash Window):点击闪控球展开的毛玻璃浮层,内置轻量计数器、便签速记与"最近暂存"列表,是轻量交互的主入口;
- 暂存架(Stash):主界面的数据中转舱,剪贴/便签/计数三种类型的条目统一暂存,单条上限 2000 字、总量 50 条环形截断。
2.2 架构分层
web/(HTML+CSS+JS 界面层)
│ invoke(JSON)
src-tauri/src/lib.rs(Rust 内核:9 个命令)
│ fs / serde_json
沙箱目录 flickorb.json(探针回退链选定的持久化位置)
Rust 侧一共注册了 9 个命令:app_info、greet、load_flash、stash_item、remove_stash、set_ball_dock、log_flash、clear_flash、capability_report。其中前两个用于握手自检,中间五个承载全部业务读写,capability_report 负责把当前运行环境的能力边界如实汇报给前端——这一点后文会专门讲。
三、Rust 内核:命令集、状态与环形截断
3.1 状态模型
后端用一个 Mutex<FlashState> 管理全部可变状态,FlashState 包含自增 ID、闪控球停靠方位、暂存条目列表和事件日志列表:
const KINDS: [&str; 3] = ["clip", "note", "counter"];
const DOCKS: [&str; 4] = ["br", "tr", "bl", "tl"];
const STASH_CAPACITY: usize = 50;
const EVENT_CAPACITY: usize = 50;
#[derive(Serialize, Deserialize, Clone)]
struct FlashState {
next_id: u64,
ball_dock: String,
stash: Vec<StashItem>,
events: Vec<FlashEvent>,
}
所有写命令都遵循同一个模式:校验入参 → 取锁修改状态 → 追加事件 → 落盘 → 返回快照。快照 FlashSnapshot 携带暂存列表、事件列表、停靠方位和两个总数,前端拿到一个快照就能完整重绘,不需要多次往返。
3.2 一次典型的写命令:stash_item
#[tauri::command]
fn stash_item(
app: tauri::AppHandle,
orb: tauri::State<Orb>,
kind: String,
text: String,
) -> Result<FlashSnapshot, String> {
let trimmed = text.trim();
if trimmed.is_empty() {
return Err("暂存内容不能为空".into());
}
if trimmed.len() > 2000 {
return Err("暂存内容过长,请控制在 2000 字以内".into());
}
if !valid_kind(&kind) {
return Err(format!("未知的暂存类型:{kind}"));
}
let at = now_epoch()?;
let mut state = orb.0.lock().unwrap();
let item = StashItem { id: state.next_id, kind: kind.clone(), text: trimmed.to_string(), at };
state.next_id += 1;
state.stash.insert(0, item);
if state.stash.len() > STASH_CAPACITY {
state.stash.truncate(STASH_CAPACITY);
}
push_event(&mut state, "stash", &format!("新增 {kind} 暂存"), at);
save_to_disk(&app, &state)?;
Ok(snapshot(&state))
}
这里有两个值得展开的细节:
其一,事件日志是环形截断的。 push_event 把新事件插到列表头部,超过 EVENT_CAPACITY(50 条)就 truncate 掉尾部旧事件。交互日志永远展示"最近的 50 件事",既满足桌面应用的审计需求,又不会让 JSON 文件无限膨胀。
其二,容量检查必须发生在"复用之后"。 单测里我们模拟连续压入 60 条数据,断言列表长度恰好是 50、首条是最新写入的"片段 59"。这类边界如果不写测试,很容易在重构时把 truncate 挪到错误的位置而不自知。
3.3 停靠方位:把交互语义收敛为四个合法值
闪控球的停靠方位只有四种合法取值 br/tr/bl/tl,set_ball_dock 命令先经 valid_dock 白名单校验再写入。把交互语义收敛成有限集合,好处是前后端约定极简:前端传一个两字母代号,后端做唯一性裁决,UI 层再由 DOCK_LABEL 映射成"右下/右上/左下/左下"文案。任何越界值都会被 Rust 侧拒绝并返回明确错误,前端据此提示而不是默默吞掉。
四、沙箱持久化:探针回退链的落地
鸿蒙PC 应用运行在沙箱里,app_data_dir 在真机上会解析到 XDG 风格路径($HOME/.local/share),而这个路径在真机环境常常不可写——这是笔者在多个 Tauri 鸿蒙PC 项目里反复验证过的坑。FlickOrb 的解法是候选目录 + 探针写入回退链:
fn writable_dir(candidates: &[PathBuf]) -> Option<PathBuf> {
for dir in candidates {
if fs::create_dir_all(dir).is_ok() {
let probe = dir.join(".flickorb-probe");
if fs::write(&probe, b"ok").is_ok() {
let _ = fs::remove_file(&probe);
return Some(dir.clone());
}
}
}
None
}
fn storage_dir(app: &tauri::AppHandle) -> Result<PathBuf, String> {
let mut candidates = Vec::new();
if let Ok(dir) = app.path().app_data_dir() {
candidates.push(dir.join("flickorb"));
}
if cfg!(target_env = "ohos") {
candidates.push(PathBuf::from(
"/data/storage/el2/base/haps/entry/files/flickorb",
));
candidates.push(PathBuf::from("/data/storage/el2/base/files/flickorb"));
}
candidates.push(PathBuf::from("/data/local/tmp/flickorb"));
candidates.push(std::env::temp_dir().join("flickorb"));
writable_dir(&candidates).ok_or_else(|| "未找到可写的数据目录".to_string())
}
回退顺序是:app_data_dir → el2 沙箱 files 目录(仅 ohos 目标编译)→ /data/local/tmp → 系统临时目录。每个候选都先 create_dir_all,再写入一个 .flickorb-probe 探针文件验证真实可写,成功后立即删除探针。“能创建目录"不等于"能写文件”,只有探针写入成功才算数。 这套链路是纯函数 writable_dir,可以直接单测:传入一个不可写目录和一个临时目录,断言它跳过前者选中后者,且探针文件不留残留。
业务数据最终落为 flickorb.json,load_flash 命令在内存态为空时才从磁盘恢复一次,避免每次读命令都碰文件系统。
五、前端:闪控球拖拽、闪控窗与能力矩阵
5.1 前端运行时探测与降级
web/main.js 的第一行就决定了双运行模式:
const invoke = window.__TAURI__?.core?.invoke;
const hasNativeRuntime = typeof invoke === "function";
const IS_BROWSER_PREVIEW = !hasNativeRuntime;
有 window.__TAURI__ 就是原生环境,走真实 IPC;没有则进入浏览器预览模式,界面会明确标注"浏览器预览"。这让我们可以在普通浏览器里快速迭代 UI,再一次性回到 鸿蒙PC 真机验证 IPC 链路,开发节奏不受真机构建速度拖累。
5.2 闪控球的拖拽停靠
闪控球用 pointer 事件实现拖拽,抬手时根据落点相对屏幕中心的位置判定四向停靠方位,随后调用 set_ball_dock 把语义方位交给 Rust 持久化。下次启动时 load_flash 快照里的 ball_dock 会直接恢复上次的停靠位置——拖拽是"手感",方位是"语义",两者分离让交互逻辑可以被测试、被复现。
5.3 能力矩阵:如实标注"可用"与"受限"
这是笔者想着重强调的一段。Tauri 在鸿蒙PC 上的窗口层目前仍有部分占位实现,系统级悬浮窗这类能力并不能真实生效。与其让用户点击一个"假成功"的按钮,不如把真实情况摊开来讲。capability_report 命令返回一份静态能力矩阵:
Capability { name: "页面内闪控窗", level: "可用",
detail: "毛玻璃浮层 + 展开/收起动画" },
Capability { name: "闪控球拖拽停靠", level: "可用",
detail: "pointer 事件 + 四向停靠语义" },
Capability { name: "系统级悬浮窗", level: "受限",
detail: "当前鸿蒙窗口层为占位实现,浮层收敛于应用内" },
Capability { name: "暂存 IPC 通道", level: "可用",
detail: "invoke 双向 JSON,50 条环形截断" },
Capability { name: "沙箱持久化", level: "已接入",
detail: "候选目录探针回退链 + flash.json 落盘" },
主界面把这份矩阵渲染成五张徽标卡片,"系统级悬浮窗"明确打上受限标签。做跨平台框架的移植工作,诚实标注能力边界比堆功能更重要——受限项不是缺陷,而是未来随上游演进的明确路线图。
六、真机运行效果
以下截图均来自 鸿蒙PC 真机(画面中可见系统顶部状态栏与底部 Dock 栏),应用为标准签名 HAP 安装运行。
图 1:FlickOrb 启动初始状态。 三栏布局完整呈现:左侧暂存架空置提示,中间能力矩阵五张徽标卡与"呼叫内核"入口,右侧交互日志待命。顶栏显示"Rust 内核在线"与"停靠:右下",深紫霓虹的毛玻璃质感一览无余。

图 2:第一条便签闪存成功。 在"便签"页签输入内容点击"闪存"后,暂存架出现带类型标签的卡片,右侧日志同步记录"新增 note 暂存",底部提示"已闪存至暂存架(共 1 条)"。

图 3:多类型暂存与内核呼叫验证。 暂存架已积累剪贴与便签两类条目,在"呼叫内核"输入框输入名字点击"呼叫",底部返回"闪控球已就位,Rust 内核在线!“——这是前端 invoke("greet", ...) 打通 IPC 的直观证据,左下角同时标注"原生运行 · com.flickorb.app”。

图 4:展开闪控窗。 点击闪控球展开毛玻璃闪控窗,内含轻量计数器(+1/归零)、便签速记输入框与"最近暂存"列表,日志同步记录"展开闪控窗"事件。

图 5:跨浮层状态实时同步。 在闪控窗里连续点击"+1"把计数器拨到 6,并速记一条便签"zdfb"——主界面暂存架同步增至 3 条,闪控窗的"最近暂存"列表也实时刷新。两个视图消费的是同一份 Rust 快照,这正是"状态收敛在后端"架构的直接收益。

七、测试与构建:让每一步都可回归
FlickOrb 延续了系列项目的双测试层约定:
- Rust 单测(8 项):覆盖
greet文案、app_info目标识别(断言ohos_library == "flickorb_lib"、包名为com.flickorb.app)、类型与方位白名单、暂存环形截断(60 条压入断言 50 条存活且首条最新)、事件日志截断、format_epoch时间转换、writable_dir探针回退的正反两个用例; - 工程测试:校验 HAP 配置、
rawfile同步、前端关键调用点与改名完整性。
值得单独一提的是 format_epoch:为了在无第三方依赖的前提下把 Unix 时间戳转成 YYYY-MM-DD hh:mm 可读文案,笔者手写了民用历转换,包含闰年判断(四年一闰、百年不闰、四百年再闰)。这类"看起来简单"的日期函数恰恰是 off-by-one 高发区,测试里用 format_epoch(0) == "1970-01-01 00:00" 和一个 2026 年的定点断言兜底。
构建链路沿用系列工程的固定节奏:cargo test → Rust release 编译产出 libflickorb_lib.so → hvigor 打包 HAP。特别提醒一个本系列反复出现的坑:前端资产是编译期嵌入动态库的,改动 web/ 之后必须重新编译 Rust 再打 HAP,否则真机上跑的还是旧界面,且不会有任何报错提示。
八、复盘与展望
FlickOrb 作为第十五个 Tauri 跨平台框架 鸿蒙PC 实践项目,沉淀了三条可复用的经验:
- 交互语义后端化:把停靠方位、暂存类型这类交互语义收敛为有限枚举,交由 Rust 白名单校验,前端只做映射渲染,整条链路可测试、可复现;
- 探针回退链是沙箱存储的标准答案:不要相信任何"理论上可写"的路径,探针写入成功才算数,并把回退链做成可单测的纯函数;
- 能力矩阵如实标注:跨平台框架在单一平台上的能力边界应当主动暴露给用户,"受限"徽标是工程诚实的体现,也是上游演进的路线图。
悬浮交互是桌面体验的深水区。随着 Tauri 鸿蒙分支的窗口层逐步完善,系统级悬浮窗、跨应用拖拽投递等能力都有望从"受限"翻转为"可用",届时 FlickOrb 这类闪控枢纽会有更大的想象空间。如果你也想在 鸿蒙PC 上用 Tauri 跨平台框架做出自己的应用,欢迎到 AtomGit 的 OpenHarmonyPCDeveloper 组织申请新建项目,一起把开源鸿蒙PC 生态做厚。
更多推荐





所有评论(0)