鸿蒙PC 备份编排台实战:用 ArkUI 把文件遍历、外置卷探测与系统能力调用编成一条可校验的流水线
鸿蒙PC 备份编排台实战:用 ArkUI 把文件遍历、外置卷探测与系统能力调用编成一条可校验的流水线
欢迎加入开源鸿蒙PC社区:https://harmonypc.csdn.net/
欢迎在PC社区平台申请新建项目:https://atomgit.com/OpenHarmonyPCDeveloper
前言:在桌面形态上做工具,最容易被低估的不是 UI,而是「数据从哪儿来、放到哪儿去、到底有没有放对」这三件事。备份把这组问题放大到极致:它同时要读文件系统(源目录长什么样、有多少文件、哪个文件的修改时间超窗)、要管外设(外置硬盘还在不在、NAS 挂没挂上、目标卷剩多少空间)、要用系统能力(这台机器是不是 2in1、现在是在电池上还是插着电、备份跑到一半合盖了会不会被杀)。三件事任何一件没接好,界面上那个「✓ 完好」就是假的。
本文的样本是开源鸿蒙PC 上的一个小工具「织匣 Arcvault」:一个备份计划与恢复演练编排实验台。它用一屏三栏把「计划 → 快照 → 演练」串起来:左边是四张备份计划卡,中间是快照胶片带与演练报告,右边是传输带与工坊日志。工程是纯 ArkTS + ArkUI 声明式 UI 框架、零三方依赖、Stage 模型,
compatibleSdkVersion为26.0.0,deviceTypes只声明2in1——它从第一天起就只打算跑在鸿蒙PC 上。这里必须先纠正一个常见称呼错误:本文所说的跨平台框架落点是 ArkUI,即鸿蒙原生声明式 UI 框架本身具备的跨设备、跨形态复用能力(同一份
.ets声明在手机、平板、2in1 之间复用),不是 ArkUI-X。工程里没有接任何第三方跨平台 UI 运行时,也没有一层 JS 桥。文中凡是写「跨平台框架」「ArkUI 跨平台框架」的地方,指的都是 ArkUI 这一套。同时把边界说在前面:仓库里这一版是界面层完整、能力层待接入的实验台。四张截图里的基线数字来自
Models.ets的演示数据(createPlans()/createSnaps()),而新增的快照与演练报告是界面上真实点击后由状态机生成的——它验证的是布局、状态流与演练语义;文件遍历、卷探测、系统能力探测三块代码是本文逐行给出的能力层实现,可直接放进entry/src/main/ets/common/编译运行。哪些是截图里看得见的、哪些是代码里写好的,第二章会一条条切开。
关键词:鸿蒙PC、鸿蒙 PC、开源鸿蒙PC、ArkUI、ArkUI 跨平台框架、2in1 桌面形态、ArkTS、文件系统、statfs、外置卷、符号链接、长时任务、备份快照、恢复演练、AtomGit。
一、问题定义:备份编排台必须回答四个问题
桌面端做备份工具,绕不开四问,而每一问对应一套完全不同的系统接口:
| 问题 | 数据从哪来 | 对应能力 | 界面落点 |
|---|---|---|---|
| 备什么 | 源目录树 | 文件遍历、lstat、stat | 计划卡副标题「工作室卷宗/设计 → 外置卷 · BRICK-01」 |
| 备到哪 | 目标挂载点 | statfs 容量、卷在线探活 | 计划卡的目标段、容量账 |
| 备得对不对 | 快照清单 | 修改时间窗口、符号链接存活 | 胶片带上的 ✓ 与「校验中」 |
| 能不能恢复 | 抽样还原 | 抽样读、报告聚合 | 演练报告卡片 |
绝大多数「备份 UI」的失败点不在第四问,而在第三问:把「文件数量对上了」当成「数据完好」。文件数量对上但修改时间超出窗口,意味着你备的是一份旧副本;符号链接指向的路径已经不存在,意味着还原出来会缺块。织匣演练报告里那两条意见——「2 个文件时间戳超出窗口」「1 个符号链接指向失效路径」——就是第三问的两个真实判据,也是第四章代码要产出的东西。
第一栏的四张计划卡,恰好把三类目标摆齐了:
设计源文件夜间备份 每日 42.6 GB 外置卷 · BRICK-01 已加密
账务与合同周备 每周 6.8 GB NAS · 存档区 已加密
会议记录手动备份 手动 0.4 GB 外置卷 · BRICK-01 明文(停用)
影像原始素材归档 每周 218.0 GB 磁带库 · TL-9 明文
外置卷是热插拔设备,NAS 是网络挂载,磁带库是离线介质。它们在代码里都是 target: string,但在系统能力上前两者可以探活、可以读容量,后者只能人工登记。能不能区分「探不到的卷」和「被拔掉的卷」,是桌面备份工具的第一道分水岭。
二、事实边界:截图、工程、演示数据
先把三类东西摊开,避免把界面上的数字当成实测结论。
第一类,截图。 文中四张图都是鸿蒙PC 真机的完整桌面截图,不是应用窗口裁剪图。判断依据是同一屏里能看到三样东西:最上方的 DevEco Code 标题栏(左侧是 Arcvault_ohos 工程标签与 版本控制 分支,右侧是「安装 DevEco Code」横幅)、底部鸿蒙PC 系统 Dock(文件管理、终端、浏览器、应用中心、备忘录一排图标)、右下角系统托盘与顶栏的电池、音量、输入法状态区。中间那个米色窗口才是应用本体,标题写着「织匣」。这种取景是刻意的:不需要读者相信任何文字,看一眼 Dock 就知道跑在鸿蒙PC 上。

图 1 鸿蒙PC 真机完整桌面:左上角是 ⌂ 织匣 Arcvault 品牌区与副标题「备份计划与恢复演练编排实验台」,右上角是「快照 · 已入匣」计数与「演示数据」标签;主体自左向右为「备份计划」「快照胶片带 + 演练报告」「传输带 + 工坊日志」三栏;底部可见鸿蒙PC 系统 Dock 与应用窗口的缩放控制点
第二类,工程。 项目源码/Arcvault_ohos 是标准 DevEco Stage 工程:AppScope/app.json5 里 bundleName = com.arcvault.orchestra、vendor = Arcvault Lab、versionCode = 1000000;build-profile.json5 里 compatibleSdkVersion 与 targetSdkVersion 都是 26.0.0,runtimeOS 为 HarmonyOS;module.json5 里 deviceTypes: ['2in1'];oh-package.json5 的 dependencies 是空对象。全部代码只有四个 .ets 文件:EntryAbility.ets、pages/Index.ets、common/Models.ets、common/Theme.ets。布局宽度用的是 layoutWeight(1.05) / layoutWeight(1.3) / width(300),颜色全部收在 Theme.ets 的 ArcColors 里,字号收在 ArcText 里——这套「设计变量集中化」是后面做窄窗口适配的前提。
第三类,演示数据。 界面上的四张计划卡与五格基线快照由 common/Models.ets 的 createPlans() / createSnaps() 返回;之后的传输带进度由 Index.ets 里 setInterval(..., 700) 驱动的 pumpJobs() 推进,完成时实时追加新快照,演练进度则是 320 ms 一步的 setTimeout 递归。也就是说:基线是写死的演示数据,增量是状态机真跑出来的。它的价值是把状态机、布局约束、可读性先钉死,接能力层时只换数据源,界面逻辑一行不改。
三、模型层:九个字段描述一次备份
模型层不追求字段多,而追求「一眼能看出这条记录在讲什么」。BackupPlan 用九个字段描述一张计划卡:
export type PlanFreq = '每日' | '每周' | '手动';
export type SnapKind = '全量' | '增量';
export interface BackupPlan {
id: number;
name: string;
scope: string; // 源:工作室卷宗/设计
freq: PlanFreq;
target: string; // 目标:外置卷 · BRICK-01
enabled: boolean;
encrypt: boolean;
lastAt: string;
sizeGb: number;
}
export interface Snapshot {
id: number;
planId: number;
planName: string;
kind: SnapKind;
at: string;
sizeGb: number;
files: number;
status: string; // 完好 / 校验中 / 校验中断
verified: boolean;
}
两个设计取舍值得说:
其一,status 用字符串而不是 enum。 因为它的最终消费者是「工坊日志」这类纯文本行——'校验中断' 直接拼进日志就是人能读的中文,省掉一层映射表。代价是编译期不再校验取值,所以要配一个 statusTone() 把字符串收敛成颜色,让「未识别的状态」必然落到告警色:
export function statusTone(status: string): string {
if (status === '完好') {
return ArcColors.sageDeep;
}
if (status === '校验中') {
return ArcColors.terra;
}
return ArcColors.alert;
}
这个「默认落到告警色」的写法,比 switch 里补 default: 灰色 要安全得多:新增一个状态忘了配色,界面会立刻用红色提醒你,而不是默默显示成正常。
其二,kind 决定的不只是标签色,还有体积量级。 kindTone() 里全量用赤陶色、增量用靛色;而「立即备份」动作会根据计划频率推导入匣类型——每日的计划做增量,其余做全量,增量体积按 Math.round(plan.sizeGb * 6) / 100 估算(42.6 GB 的计划 → 2.56 GB 的增量):
const kind: SnapKind = plan.freq === '每日' ? '增量' : '全量';
this.jobs = this.jobs.concat([{
id: this.nextId,
title: plan.name,
kind: kind,
sizeGb: kind === '增量' ? Math.round(plan.sizeGb * 6) / 100 : plan.sizeGb,
progress: 0,
state: '打包中'
}]);
注意这里用的是 concat 而不是 push,也不是展开运算符。ArkTS 在严格模式下对 [...this.jobs, job] 这类数组展开有兼容性限制,concat 返回新数组、语义等价、还顺手满足了 @State 必须整体替换的要求——一箭双雕。
四、文件能力:从目录树到可校验清单
把「备什么」变成代码,只需一个函数:给定根目录和一个上限,产出一份清单——文件数、目录数、总字节、链接数、失效链接数,以及每条记录的相对路径、体积、修改时间。这份清单就是快照的语义内核,也是后面校验与演练的唯一输入。
4.1 为什么必须用 lstat 而不是 stat
fs.stat() 会跟随符号链接。这意味着两件事同时发生:你把一个指向 /data/.../设计 的链接当成了目录,递归进去后「源目录」和「目标目录」可能变成同一棵树;而当链接目标已经不存在时,stat() 抛错,你连「这里曾经有一个链接」都不知道,只能把它当成一个读不了的坏文件跳过。
fs.lstat() 不跟随链接,返回的是链接本身的元信息。于是三种情况可以分开处理:st.isDirectory() 是真目录,st.isFile() 是真文件,st.isSymbolicLink() 是链接。对于链接,再用一次 fs.stat() 试探目标是否存活——这一次抛错不是失败,而是结论:
if (st.isSymbolicLink()) {
links++;
let alive = true;
try {
await fs.stat(full); // 故意跟随,探测目标
} catch (e) {
alive = false; // 目标不存在:这是一个失效链接
}
if (!alive) {
broken++;
}
marks.push({
rel: full.substring(prefixLen + 1),
size: 0, // 链接本身不占数据体积
mtimeSec: st.mtime,
isLink: true,
linkBroken: !alive
});
continue;
}
这段代码直接对应演练报告里那句「1 个符号链接指向失效路径」。在鸿蒙PC 上做设计文件备份尤其容易撞上:设计工具喜欢用链接做「素材软引用」,用户整理目录时删掉了原素材,链接留在原地成了悬空指针。如果备份工具把链接当普通文件复制,还原出来的工程打开就是一堆空占位符。
4.2 迭代式 DFS,不用递归
扫描器写成迭代式,而不是递归函数调用,理由有三个,都跟桌面场景强相关:
- 深度不可控。用户的工程目录可能有几十层,递归会吃掉栈;迭代用显式
stack: string[],堆内存比栈安全。 - 可中断。
while (stack.length > 0 && !truncated)这个条件让扫描可以在任意文件处停下,把剩余目录留在栈里——这就是「增量备份能做到秒级响应」的实现基础。 - 可观测。每处理完一个目录就能吐出一次进度,界面上的进度条不用等整棵树扫完。
完整实现(entry/src/main/ets/common/FileVault.ets):
import { fileIo as fs } from '@kit.CoreFileKit';
import { BusinessError } from '@kit.BasicServicesKit';
export interface FileMark {
rel: string;
size: number;
mtimeSec: number;
isLink: boolean;
linkBroken: boolean;
}
export interface TreeScan {
root: string;
files: number;
dirs: number;
bytes: number;
links: number;
broken: number;
truncated: boolean;
marks: FileMark[];
}
export async function scanTree(root: string, limit: number): Promise<TreeScan> {
const marks: FileMark[] = [];
let files: number = 0;
let dirs: number = 0;
let bytes: number = 0;
let links: number = 0;
let broken: number = 0;
let truncated: boolean = false;
const stack: string[] = [root];
const prefixLen: number = root.length;
while (stack.length > 0 && !truncated) {
const dir: string = stack.pop() as string;
let names: string[] = [];
try {
names = await fs.listFile(dir);
} catch (e) {
const err = e as BusinessError;
// 13900002 = No such file or directory,目录在遍历途中被移走或卷被拔出
if (err.code === 13900002) {
truncated = true;
break;
}
continue; // 单目录不可读不应中断整棵树
}
for (let i = 0; i < names.length; i++) {
if (marks.length >= limit) {
truncated = true;
break;
}
const full: string = dir + '/' + names[i];
let st: fs.Stat;
try {
st = await fs.lstat(full);
} catch (e) {
continue;
}
if (st.isDirectory()) {
dirs++;
stack.push(full);
continue;
}
if (st.isSymbolicLink()) {
links++;
let alive: boolean = true;
try {
await fs.stat(full);
} catch (e) {
alive = false;
}
if (!alive) {
broken++;
}
marks.push({
rel: full.substring(prefixLen + 1),
size: 0,
mtimeSec: st.mtime,
isLink: true,
linkBroken: !alive
});
continue;
}
if (st.isFile()) {
files++;
bytes += st.size;
marks.push({
rel: full.substring(prefixLen + 1),
size: st.size,
mtimeSec: st.mtime,
isLink: false,
linkBroken: false
});
}
}
}
return {
root: root, files: files, dirs: dirs, bytes: bytes,
links: links, broken: broken, truncated: truncated, marks: marks
};
}
三个细节值得单独点出来:
truncated是契约的一部分。 扫描到limit就停,但必须让调用方知道「这不是全量」。界面上的说法要跟着变:「抽样 120 个」而不是「共 120 个」——一字之差,可信度天差地别。演练报告里那行「抽样 120 个 · 完好 118 个」用的就是这个词。13900002单独分流。 目录不存在和「文件太多扫不完」是两种完全不同的结束原因,前者大概率是外置卷被拔掉了(第五章展开),后者是策略上限。两者的后续动作不一样:前者要挂起计划并提示重新插卷,后者只需要记一条「已达上限」。st.mtime的单位是秒。 鸿蒙的文件Stat里mtime是自 Unix 纪元起的秒,不是毫秒。要做时间窗口比较时统一乘 1000 再和Date.now()比,否则你会发现「所有文件都超窗了」——因为 1.7e9 秒被当成了 1970 年附近的毫秒。
4.3 大目录必须离开 UI 线程
上面这个 scanTree 是纯 await 链,看着不阻塞,但 ArkTS 的微任务依然在 UI 线程上跑。真实场景里 8 万文件的目录树,单次 lstat 哪怕只要 0.02 ms,累加也是秒级,界面会卡在「计划卡点不动」的状态。
正确做法是把它丢进 taskpool,写法有一个硬约束:@Concurrent 标注的函数不能调用同模块的普通函数,也不能访问类成员或闭包变量。所以不能写成「把 scanTree 传进 taskpool.execute」,只能把函数体搬过去:
import { taskpool } from '@kit.ArkTS';
// 注意:@Concurrent 函数体内不能调用 scanTree(),只能复制函数体
@Concurrent
async function scanTreeTask(root: string, limit: number): Promise<TreeScan> {
const marks: FileMark[] = [];
// ...与 scanTree 完全相同的函数体...
return {
root: root, files: 0, dirs: 0, bytes: 0,
links: 0, broken: 0, truncated: false, marks: marks
};
}
export async function scanOffMainThread(root: string, limit: number): Promise<TreeScan> {
const task: taskpool.Task = new taskpool.Task(scanTreeTask, root, limit);
const result: TreeScan = await taskpool.execute(task) as TreeScan;
return result;
}
taskpool 的返回值走结构化克隆,TreeScan 这种纯 interface + 基础类型数组可以安全往返;但如果你在返回对象里塞了 fs.File 句柄或 PixelMap,会遇到「克隆失败」而不是「返回 undefined」——错误码会明确告诉你哪个字段不可序列化。
这一节最后给一个工程约定:清单只落一次盘,之后所有校验都读清单,不再读源。原因很简单——校验的语义是「我上次备的东西对不对」,不是「源目录现在长什么样」。截图里那格 status: '校验中断' 的快照(218 GB、60412 个文件)就是这么来的:扫描到一半卷没了,清单本身保留,状态标中断。这个设计让「中断」成为一种可恢复状态,而不是「这条记录作废」。
五、外设:普通应用拿不到卷列表,怎么知道卷还在
「备到哪」看起来只是把路径写进配置,实际是整篇文章最脏的一块。原因在于鸿蒙的卷管理接口不是给普通应用准备的。
5.1 先认清权限现实
@kit.CoreFileKit 里确实有 volumeManager,getAllVolumes() 能一次列出所有卷的 id、uuid、state、path。但它要求 ohos.permission.STORAGE_MANAGER——系统应用权限,第三方应用申请不到。同一个 Kit 里的 storageStatistics.getCurrentBundleStats() 只能拿到「本应用自己的」占用,也解决不了「目标卷还剩多少」。
所以第三方在鸿蒙PC 上做备份工具,路径只有两条:
| 路线 | 拿到什么 | 代价 |
|---|---|---|
statfs 探活任意可访问路径 | 总容量、可用容量;抛错即不可达 | 需要用户先授权该路径 |
picker 授权目录 + fileShare.persistPermission | 持久化的读写 URI | 需要 FILE_ACCESS_PERSIST 权限,且必须用户手动选一次 |
两条结合,就是完整的「外置卷生命周期」:用户选一次目录 → 持久化 URI → 之后用 statfs 定时探活。这条路线不依赖系统权限,也不假装自己知道「系统里一共有几个卷」——它只回答「我关心的那个目标还活着吗、还剩多少」,而这恰好是备份工具真正需要的语义。
5.2 授权:一次点击换一个永久入口
import { picker } from '@kit.CoreFileKit';
export async function pickTargetDir(ctx: Context): Promise<string> {
const options: picker.DocumentSelectOptions = new picker.DocumentSelectOptions();
options.maxSelectNumber = 1;
options.selectMode = picker.DocumentSelectMode.FOLDER; // 只选文件夹
const viewPicker: picker.DocumentViewPicker = new picker.DocumentViewPicker(ctx);
const uris: string[] = await viewPicker.select(options);
return uris.length > 0 ? uris[0] : '';
}
拿到的 URI 是 file://... 形式,直接 fs.open(uri, fs.OpenMode.READ_WRITE) 就能用,不需要把它转成路径。这一点跟「沙箱路径」是两套东西:沙箱内(context.filesDir)用路径,用户授权目录用 URI,别混着传。
「一次点击」如果只在本进程有效,重启就失效,那这个交互是不可接受的。持久化用 fileShare:
import { fileShare } from '@kit.CoreFileKit';
export async function keepAccess(uri: string): Promise<void> {
const policy: fileShare.PolicyInfo = {
uri: uri,
operationMode: fileShare.OperationMode.READ_WRITE
};
await fileShare.persistPermission([policy]);
}
对应的权限声明是 ohos.permission.FILE_ACCESS_PERSIST。这里有个容易被忽略的细节:persistPermission 成功不代表下次 fs.open 一定成功——用户可能在系统设置里撤销了授权,或者外置卷换了台机器插。所以探活逻辑不能省,它才是唯一可信的状态来源。
5.3 statfs 探活:把「抛错」当成信号
import { statfs } from '@kit.CoreFileKit';
import { BusinessError } from '@kit.BasicServicesKit';
export interface VolumeReading {
online: boolean;
total: number; // 字节
free: number; // 字节
code: number; // 失败时的错误码
}
export async function probeVolume(mount: string): Promise<VolumeReading> {
try {
const total: number = await statfs.getTotalSize(mount);
const free: number = await statfs.getFreeSize(mount);
return { online: true, total: total, free: free, code: 0 };
} catch (e) {
const err = e as BusinessError;
return { online: false, total: 0, free: 0, code: err.code };
}
}
三次调用,一个结论:能读到容量说明卷在线;抛错说明不可达。注意 getTotalSize 要求路径可访问——文件级的 stat 权限它也要,所以探活用的路径必须是用户授权过的那一个,或者沙箱内的 filesDir。
5.4 两次失败才判离线:防抖比精度重要
直接拿一次 probeVolume 的结果去翻状态,会有一个很难查的 bug:statfs 在系统繁忙、卷刚挂载、休眠唤醒的一瞬间都可能短暂抛错。用户看到的界面就变成「外置卷离线」与「在线」之间闪烁——而备份任务如果跟着状态走,会在闪烁时被反复挂起。
所以引入一个「连续失败计数」的 VolumeLedger:第一次失败只记一笔,连续第二次失败才对外宣布离线;任何一次成功立刻清零。
export class VolumeLedger {
private miss: Map<string, number> = new Map<string, number>();
private readings: Map<string, VolumeReading> = new Map<string, VolumeReading>();
async poll(mounts: string[]): Promise<string[]> {
const offline: string[] = [];
for (let i = 0; i < mounts.length; i++) {
const mount: string = mounts[i];
const now: VolumeReading = await probeVolume(mount);
if (now.online) {
this.miss.set(mount, 0);
this.readings.set(mount, now);
continue;
}
const n: number = (this.miss.get(mount) ?? 0) + 1;
this.miss.set(mount, n);
if (n >= 2) {
offline.push(mount);
}
}
return offline;
}
readingOf(mount: string): VolumeReading | undefined {
return this.readings.get(mount);
}
}
轮询周期用 5 秒就够:备份任务的粒度是分钟级,探活再快也不会更快发现拔卷,反而白耗电。判定阈值取 2,是「一次毛刺容忍 + 一次确认」的最小组合;取 3 会让拔卷提示延迟 5 秒以上,取 1 就退化成上面说的闪烁。
5.5 容量账:把「够不够」在点击前回答
VolumeReading 拿到的是 total 与 free,但它只有和计划体积比才有意义。织匣的四张计划里,最危险的是第四张:218 GB 的影像归档,目标是磁带库 TL-9。这类离线介质探不到容量,probeVolume 会永远返回 online: false——这不是 bug,而是「该卷不支持在线探测」这一事实的正确表达。
于是界面上的语义要分三层,而不是二元:
| 探测结果 | 界面语义 | 动作 |
|---|---|---|
online: true 且 free >= sizeGb | 容量充足 | 允许「立即备份」 |
online: true 且 free < sizeGb | 空间不足 | 禁用按钮,提示换卷 |
连续两次 online: false | 目标不可达 | 挂起计划,等重新接入 |
| 该目标标记为离线介质(磁带库) | 不探测 | 允许「立即备份」但要求人工登记介质编号 |
这四行是纯业务规则,没有一行系统 API,但它决定了用户会不会在某天早上发现「昨晚的 218 GB 备份其实写进了本地磁盘」。桌面备份工具出事故,十有八九是这条规则被简化成了二元判断。
六、系统能力:2in1 上必须先问清的四个问题
能力层最后一块,是把「这台机器现在是什么状态」问清楚。桌面形态与移动形态的差别不只是屏幕大小,而是四条会直接改变业务分支的事实。
6.1 形态判定:deviceInfo.deviceType
import { deviceInfo } from '@kit.BasicServicesKit';
export function isDesktop(): boolean {
return deviceInfo.deviceType === '2in1';
}
deviceType 在鸿蒙PC 上返回 '2in1',平板是 'tablet',手机是 'phone',还有 'tv'、'wearable'、'car' 等。这个判断的意义不是「显示不同 UI」,而是「允不允许做某些事」:桌面形态可以做多窗口并排、可以要求用户选目录、可以长期挂着后台传输;手机形态上这些交互要么不存在,要么体验极差。
织匣在 module.json5 里直接写死 deviceTypes: ['2in1'],等于在安装层就把非桌面设备挡掉。这是最省事的做法——能力不匹配的形态,最好在清单里就拒绝,而不是在代码里到处写 if。
6.2 供电状态:夜间备份该不该跑
import { batteryInfo } from '@kit.BasicServicesKit';
export function onBattery(): boolean {
// batterySOC 是 0-100 的整数;isCharging 表示当前是否在充电
return !batteryInfo.isCharging && batteryInfo.batterySOC < 100;
}
「设计源文件夜间备份」这张卡的频率是每日、时间是 23:00。对笔记本用户,23:00 大概率在电池上。如果 42.6 GB 的全量备份在电量 18% 时启动,用户第二天早上会得到一个「备份失败」和一个「机器没电」。所以真正的策略是:电池状态下只跑增量、插电才跑全量。这个分支只需要 batteryInfo 两个字段,但它把「备份工具」和「电池杀手」区分开了。
6.3 长时任务:别让合盖杀掉传输
这是鸿蒙PC 上最容易被忽略的一条。备份跑到一半,用户合上盖子或者切到别的窗口,应用进入后台——如果不申请长时任务,很快就会被冻结,传输带卡在 62% 再也不动。
import { backgroundTaskManager } from '@kit.BackgroundTasksKit';
import { wantAgent, WantAgent } from '@kit.AbilityKit';
import { common } from '@kit.AbilityKit';
export async function beginTransfer(ctx: common.UIAbilityContext): Promise<void> {
const info: wantAgent.WantAgentInfo = {
wants: [{
bundleName: 'com.arcvault.orchestra',
abilityName: 'EntryAbility'
}],
actionType: wantAgent.OperationType.START_ABILITY,
requestCode: 100,
actionFlags: [wantAgent.WantAgentFlags.UPDATE_PRESENT_FLAG]
};
const agent: WantAgent = await wantAgent.getWantAgent(info);
await backgroundTaskManager.startBackgroundRunning(
ctx,
backgroundTaskManager.BackgroundMode.DATA_TRANSFER,
agent
);
}
export async function endTransfer(ctx: common.UIAbilityContext): Promise<void> {
await backgroundTaskManager.stopBackgroundRunning(ctx);
}
三个必须配齐的东西,缺一个就会静默失败:
- 权限:
module.json5里声明ohos.permission.KEEP_BACKGROUND_RUNNING(normal级,无需用户弹窗)。 - 模式:
BackgroundMode.DATA_TRANSFER,对应「数据传输」长时任务类型。用错模式(比如AUDIO_PLAYBACK)会被系统在审核或运行阶段拒绝。 - WantAgent:任务栏上那条「织匣正在传输」的胶囊点击后要能回到应用,靠的就是这个
WantAgent。bundleName必须与AppScope/app.json5一致(com.arcvault.orchestra),写错了startBackgroundRunning直接抛错。
配对原则只有一条:start 和 stop 必须成对出现在同一个生命周期里。传输完成、用户取消、演练结束都要调 endTransfer;漏掉 stop 的后果是应用一直挂着长时任务,用户在系统隐私面板里会看到一个永远在「传输中」的应用,这比功能缺失更伤信任。
6.4 屏幕与窗口:别硬编码像素
织匣的三栏是 layoutWeight(1.05) / layoutWeight(1.3) / width(300)。前两栏按比例分,右栏固定 300 vp。窗口从 1280 拖到 800 宽时,前两栏各自缩水,右栏纹丝不动——于是「工坊日志」挤成两字一行。修法不是改成三个比例,而是给固定列加约束:
Column() {
// 传输带 + 工坊日志
}
.width(300)
.constraintSize({ minWidth: 260, maxWidth: 360 })
再往外一层,用窗口限制把「不可能好看」的尺寸直接挡掉:
import { window } from '@kit.ArkUI';
const win: window.Window = await window.getLastWindow(ctx);
// 注意:WindowLimits 的单位是 px,不是 vp,需要按屏幕密度换算后再传
await win.setWindowLimits({ minWidth: 1280, minHeight: 800 });
setWindowLimits 是 2in1 形态上很实用的一类接口:它把「窗口最小能拖多小」这件事从「布局崩了才发现」提前到「拖不动」。桌面用户对窗口尺寸的容忍度很高,但对「拖小之后排版错乱」的容忍度是零。
多屏场景下还有一个坑:display.getDefaultDisplaySync() 拿到的是主屏的 densityDPI,如果用户在副屏(缩放比例不同)上把窗口拖过去,用主屏 DPI 算出来的尺寸会失真。稳妥做法是只用 vp 布局,不拿 DPI 参与计算;确实需要时,用 display.on('change') 监听并重新取当前窗口所在屏幕的 display 对象。
6.5 权限清单
把上面几节需要的东西收成一张表,方便对照检查:
| 权限 | 级别 | 用在哪 | 不申请的后果 |
|---|---|---|---|
ohos.permission.KEEP_BACKGROUND_RUNNING | normal | 6.3 长时任务 | startBackgroundRunning 抛 201 |
ohos.permission.FILE_ACCESS_PERSIST | normal | 5.2 持久化授权目录 | persistPermission 抛 201 |
ohos.permission.STORAGE_MANAGER | system_core | 卷列表(本文未用) | 第三方应用无法申请,别写进清单 |
只有前两条需要写进 requestPermissions,第三条明确「不申请」——这类「知道自己不该申请什么」的判断,比多申请几个权限更能体现工程素养。
七、ArkUI 状态层:不可变替换、状态泵与 key
能力层解决「数据从哪来」,ArkUI 这一层解决「数据怎么让界面动起来」。织匣只有一个页面,但状态不少:plans、snaps、jobs、reports、logs 五个数组,外加 selectedSnapId、drillRunning、drillProgress 三个标量。
7.1 五个 @State,全部靠整体替换
ArkUI 的 @State 只能观测到引用变化。this.snaps.push(x) 不会触发刷新,this.snaps[i].status = '完好' 也不会——这是新手最常写错的两行。织匣里的写法统一成「构造新对象 + 返回新数组」:
this.snaps = this.snaps.map((s: Snapshot): Snapshot => {
if (s.id !== snap.id) {
return s;
}
const done: Snapshot = {
id: s.id, planId: s.planId, planName: s.planName, kind: s.kind,
at: s.at, sizeGb: s.sizeGb, files: s.files,
status: '完好', verified: true
};
return done;
});
map 里每个分支都必须 return,而且返回类型要显式标注 : Snapshot。ArkTS 的类型推导在回调里遇到「部分分支返回旧引用、部分分支返回新字面量」时会退化成联合类型,触发编译告警。把返回类型钉死,这类问题一次消失。
7.2 状态泵:setInterval 推传输带
传输带的进度不是真实 I/O 回调驱动的,而是一个 700 ms 的定时器在推进:
aboutToAppear(): void {
this.pumpId = setInterval(() => {
this.pumpJobs();
}, 700);
}
aboutToDisappear(): void {
if (this.pumpId >= 0) {
clearInterval(this.pumpId);
this.pumpId = -1;
}
}
pumpJobs() 里做三件事:给队首任务加随机步长;到 100% 时把它标成「已入匣」并弹出队列日志;同时生成一条新快照插到胶片带最前面,保留 14 条。
const p: number = j.progress + 12 + Math.floor(Math.random() * 14);
if (p >= 100) {
const done: BeltJob = {
id: j.id, title: j.title, kind: j.kind,
sizeGb: j.sizeGb, progress: 100, state: '已入匣'
};
next.push(done);
doneNow = done;
} else {
const moving: BeltJob = {
id: j.id, title: j.title, kind: j.kind,
sizeGb: j.sizeGb, progress: p,
state: p > 60 ? '写入校验' : '传输中'
};
next.push(moving);
}
这里有个业务含义很强的设计:state 在 60% 处从「传输中」切成「写入校验」。真实备份的耗时也确实分两段——写数据与回读校验,后者往往比前者更慢(尤其是外置机械盘)。界面提前把这个阶段暴露出来,用户才不会在 62% 卡住时以为程序死了。
aboutToDisappear 里的清理是必须的。页面被销毁而定时器还在跑,回调里的 this 指向已卸载的组件,轻则日志报错,重则内存持续增长。pumpId 初始值设 -1、清理后置回 -1,是为了让 clearInterval 幂等——setInterval 返回的 id 从 0 开始,用 0 当「未初始化」哨兵会误伤第一个定时器。
7.3 ForEach 的 key:身份 ≠ 内容
织匣里传输带的写法是:
List({ space: 0 }) {
ForEach(this.jobs, (j: BeltJob) => {
ListItem() {
this.JobRow(j)
}
}, (j: BeltJob) => j.id.toString() + j.progress.toString())
}
这是一个可以改进的地方。 把 progress 拼进 key,等于告诉框架「进度每变一次,这一行就是一条新数据」——于是每次 pumpJobs() 都会销毁并重建 ListItem,里面进度条的隐式动画、Stack 的布局缓存全部白费,而且 22 条日志、8 条报告、14 格快照同时在刷新时,重建成本会叠加。
正确做法是 key 只用身份:
(j: BeltJob) => j.id.toString()
反过来,有一些场景必须把状态拼进 key:当同一 id 下渲染结构完全不同(比如「已入匣」行末尾多一个 ✓,而「传输中」行没有 if 分支包裹),ArkUI 的复用会保留旧的子树,导致 ✓ 不出现。判断标准很简单:结构变,key 变;只是属性变,key 不变。进度条宽度是属性,✓ 的有无是结构。
7.4 日志环形缓冲:concat + slice
pushLog(text: string, tone: string): void {
const e: ArcLog = { id: this.nextId, time: clockText(), text: text, tone: tone };
this.nextId = this.nextId + 1;
this.logs = [e].concat(this.logs).slice(0, 22);
}
三个动作一次完成:新记录进队首、旧记录保留、超过 22 条丢弃尾部。桌面工具连续点击十几次「立即备份」是常态,日志不设上限的话,List 会越长越慢,最后变成一屏需要不停滚动的流水账。22 这个数字也不是随便取的——List 的高度约 440 vp,单行 20 vp,正好一屏略多,用户不用滚动就能看完最近的操作。
八、演练报告:把「一致性」写成一句话
「校验快照」与「恢复演练」是两个不同动作,织匣把它们做成了两条路径:
- 校验:对选中的快照全部文件做元数据比对,1.1 秒后统一出结果(
setTimeout)。 - 演练:抽样 120 个文件做「还原读」,进度条 320 ms 一步推进,结束后生成
DrillReport并插到报告列表首位,最多保留 8 条。
演练的收尾逻辑值得逐行看,因为它是全文唯一的业务判定:
finishDrill(snap: Snapshot): void {
const bad: number = Math.floor(Math.random() * 3);
const issues: string[] = [];
if (bad >= 1) {
issues.push('2 个文件时间戳超出窗口');
}
if (bad >= 2) {
issues.push('1 个符号链接指向失效路径');
}
const checked: number = 120;
const ok: number = checked - issues.length;
const report: DrillReport = {
id: this.nextId,
snapshotId: snap.id,
at: clockText(),
checkedFiles: checked,
okFiles: ok,
issues: issues,
verdict: issues.length === 0 ? '演练通过' : '演练通过 · 有保留意见',
minutes: Math.round((4 + Math.random() * 6) * 10) / 10
};
this.nextId = this.nextId + 1;
this.reports = [report].concat(this.reports).slice(0, 8);
this.drillRunning = false;
this.pushLog('演练完成:抽样 ' + checked + ' 个文件,' + ok + ' 个完好,用时 ' + report.minutes + ' 分钟',
issues.length === 0 ? ArcColors.sageDeep : ArcColors.terraDeep);
// ...
}
这里有一个真实存在的计算偏差,必须指出来。 const ok = checked - issues.length 用「意见条数」当成了「问题文件数」。第一条意见是「2 个文件时间戳超出窗口」、第二条是「1 个符号链接指向失效路径」,两条意见一共对应 3 个问题文件,但 120 - 2 = 118 只减掉了 2。于是界面出现了一处自相矛盾的表述——截图里那条报告写着「抽样 120 个 · 完好 118 个」,下面却列着 2 + 1 = 3 个问题文件。读者如果按「120 - 118 = 2」去核对,永远对不上账。
修法是把「意见」和「计数」解耦:
let badFiles: number = 0;
const issues: string[] = [];
if (bad >= 1) {
badFiles += 2;
issues.push('2 个文件时间戳超出窗口');
}
if (bad >= 2) {
badFiles += 1;
issues.push('1 个符号链接指向失效路径');
}
const ok: number = checked - badFiles; // 120 - 3 = 117
改完之后,「完好 117」与「2 + 1 = 3 个问题文件」严格自洽。这个 bug 之所以值得单独写一节,是因为它是报表类界面的通用陷阱:一旦明细行是自然语言(带数量词的句子),汇总数字就再也不能从「明细条数」推出来,必须由明细自己累加。文案越像人话,越容易骗过程序。
同一个函数里还有第二处可以商量的设计:演练结束后,它会把快照状态无条件写成 '完好'、verified: true,即使报告里明明有保留意见。这等于用报告否定了自己刚打的勾。更合理的做法是分档:
const verdictCode: string = badFiles === 0 ? '完好' : (badFiles <= 2 ? '完好 · 有保留' : '需复检');
界面上的 statusTone() 只需要再补一个分支就能表达第三档,颜色上建议用赤陶色而不是告警红——「有保留意见」不等于「坏」,用错颜色会让用户对整个校验体系失去信任。
九、四张真机截图逐张读
图 1 已经在第二章出现过(首屏空态),它回答的是「三栏在宽窗口下怎么站住」。剩下三张是同一份代码在不同状态下的采样,正好把状态机的三条支路走了一遍。

图 2 鸿蒙PC 真机完整桌面:胶片带最左新增一格「全量 / 00:24:56 / 6.8 GB」并被选中,详情区显示「账务与合同周备 · 942 个文件 · 完好」,「校验快照」与「演练中 86%」并排;右侧传输带出现对应条目,工坊日志开始滚动
这张图把「一次手动备份的完整回声」摆在了一屏里。触发点是左边第二张计划卡的「立即备份」,它的频率是每周,所以 runNow() 按 plan.freq === '每日' ? '增量' : '全量' 判定成了全量,体积沿用计划的 6.8 GB;pumpJobs() 每 700 ms 推进一次,到 100% 时弹出一条新 Snapshot 插到 this.snaps 的最前面——所以胶片带第一格的时间是 00:24:56,而不是任何一张演示数据里的「昨日 23:00」。这就是 [fresh].concat(this.snaps).slice(0, 14) 的可见效果。
同时注意「演练中 86%」这个按钮:它不是独立文案,而是 this.drillRunning ? '演练中 ' + this.drillProgress + '%' : '恢复演练' 的三元表达式。按钮在演练期间变成灰底(ArcColors.faint)——这是刻意的禁用视觉,但代码里并没有真的 .enabled(false),而是靠 startDrill() 开头的 if (this.drillRunning) { return; } 挡住重复点击。功能上没问题,视觉上更省事,但严格说这是「看起来禁用、实际可点」的不一致,属于下一轮要收拾的细节。

图 3 鸿蒙PC 真机完整桌面:胶片带选中「增量 / 昨日 23:00 / 1.9 GB」,详情显示「设计源文件夜间备份 · 326 个文件」;下方演练报告已累积两条,第一条「用时 6 分钟」、第二条「用时 4.3 分钟」;右侧传输带还有一条全量任务在推进
这张图是第八章那个计算偏差的直接证据。第二条报告写着「抽样 120 个 · 完好 118 个」,下面跟着两行意见:「2 个文件时间戳超出窗口」「1 个符号链接指向失效路径」——2 + 1 = 3,而 120 - 118 = 2。界面自己在账面上差了 1。这不是渲染问题,是 ok = checked - issues.length 这一行把「意见条数」当成了「问题文件数」。第八章给的修法(badFiles 累加)改完,这一格会变成「完好 117 个」,三个数字立刻自洽。
第一条报告「完好 119 个」+ 一条意见「1 个文件时间戳超出窗口」是对的,因为那一次 bad 恰好等于 1,只推了一条意见。也就是说:这个 bug 只在「两条意见同时出现」时暴露——这类概率性 bug 如果只截图一次,很容易漏掉。桌面工具测试时故意把 bad 的上限从 3 调大,让两条意见必然同时出现,是值得养成的习惯。

图 4 鸿蒙PC 真机完整桌面:与图 3 同一快照选中态,工坊日志条目更多、传输带上的全量任务进度条更长,其余区域完全一致
图 4 与图 3 的差别只有两处:右侧「工坊日志」多了几条,传输带的进度条更长。这两张图相隔不到一分钟,恰好把 700 ms 泵的节奏拍了下来。为什么值得单独放一张?因为桌面应用的「活着感」全靠这种持续可见的变化。如果日志只在操作时刷新、进度只在完成时跳变,用户会怀疑程序是不是卡死了。织匣的做法是把每一次 pumpJobs() 里的状态跃迁都写进日志(pushLog),并用颜色区分语义:赤陶色是备份事件、靛色是校验、深鼠尾草绿是成功、深赤陶是被拒。
三张图连起来读,还能看出一件事:logs 与 reports 都是环形缓冲(slice(0, 22) 与 slice(0, 8)),所以无论用户点多少次,右侧栏的高度都不会被撑爆。桌面工具长时间开着是常态,所有会随时间增长的数组都必须有上限,这一条比任何性能优化都管用。
十、踩坑清单
按「踩到的顺序」排,每一条都能在上面的代码里找到出处。
1. @State 数组的 push 与下标赋值都不触发刷新。 唯一可靠写法是整体替换:map 出新数组、concat 加元素、slice 截断。写下 this.jobs.push(j) 的那一刻,界面就已经死了。
2. ForEach 的 key 拼了会变的字段。 织匣把 progress 拼进 key,等于每 700 ms 重建一次整行。判断标准:结构变化才换 key,属性变化不换。
3. setInterval 忘记清,且用 0 当未初始化哨兵。 setInterval 的返回值从 0 开始,用 0 表示「还没启动」会误杀第一个定时器;用 -1。
4. ArkTS 里数组展开受限。 [...this.jobs, job] 这类写法在严格模式下容易出问题,统一改 concat,语义相同且天然返回新引用。
5. st.mtime 的单位是秒。 乘 1000 再和 Date.now() 比。忘了这一步,所有文件都会被判成「时间戳超出窗口」。
6. fs.stat() 会跟随符号链接。 扫描必须用 lstat();要判断链接是否失效,再对同一路径补一次 stat(),让抛错变成结论。
7. volumeManager.getAllVolumes() 需要系统级权限。 第三方应用申请不到 ohos.permission.STORAGE_MANAGER,别把卷列表写进方案。用「picker 授权目录 + statfs 探活」替代。
8. 固定像素列 + 比例列的组合在窄窗口必崩。 layoutWeight 只解决「怎么分」,不解决「最小多宽」。给固定列加 constraintSize,再给窗口加 setWindowLimits。
9. 长时任务三件套缺一不可。 权限 KEEP_BACKGROUND_RUNNING、模式 DATA_TRANSFER、WantAgent 里的 bundleName 与 AppScope/app.json5 严格一致;start 与 stop 必须成对。
10. 报表汇总数字不能从明细条数推。 明细是带数量词的中文句子时,汇总必须由明细自己累加计数,否则就会出现第八章那种「118 对不上 3」的账面矛盾。
11. 签名 profile 会锁死 bundleName。 若沿用的调试签名来自别的示例工程,实际安装的包名以 pack.info 为准;同名包名装第二次会被拒(9568263),先 hdc uninstall com.arcvault.orchestra 再装。
十一、构建与复现
# 1. 构建(DevEco Studio 内 Build > Build Hap(s)/APP(s),或命令行)
hvigorw assembleHap --mode module -p product=default -p buildMode=debug
# 2. 安装到鸿蒙PC(先确认设备在线)
hdc list targets
hdc install -r entry/build/default/outputs/default/entry-default-signed.hap
# 3. 拉起
hdc shell aa start -a EntryAbility -b com.arcvault.orchestra
工程路径:项目源码/Arcvault_ohos,四个 .ets 文件、零三方依赖,可直接用 DevEco Studio 打开 Arcvault_ohos 目录。想验证第四章的扫描器,把 FileVault.ets 放进 entry/src/main/ets/common/,在 Index.aboutToAppear() 里加一行:
scanTree(this.getUIContext().getHostContext()!.filesDir, 500).then((r: TreeScan) => {
this.pushLog('扫描完成:' + r.files + ' 个文件 / ' + r.bytes + ' 字节 / 失效链接 ' + r.broken, ArcColors.indigo);
});
沙箱目录不需要任何权限声明,先跑通「扫描 → 日志」这条链路,再换成 picker 授权的用户目录。先证明能力可用,再谈交互设计——这是能力层接入时唯一稳妥的顺序。
十二、小结:三层可以分别演进
把这篇的结论压成三句话:
文件层只做一件事——产出可校验的清单。 用 lstat 分辨链接、用迭代 DFS 换取可中断、用 truncated 标明抽样、用秒级 mtime 统一时间口径。清单是快照的语义内核,也是演练的唯一输入。
外设层只承认可探测的事实。 没有系统权限就拿不到卷列表,那就只回答「我关心的目标还活着吗、剩多少」。两次失败才判离线,离线介质不探测但要人工登记。把「探不到」和「被拔掉」分开,是桌面备份工具的第一道分水岭。
系统层决定策略,不决定 UI。 2in1 判定、供电状态、长时任务、窗口限制,四条都在回答「现在允不允许做这件事」。把这些判断放进能力层,ArkUI 那层就只剩「怎么把结果画出来」——这也是 ArkUI 跨平台框架真正的价值所在:同一套声明式描述,换一台设备只是换约束,不是重写界面。
织匣这一版界面层是完整的,能力层是一半的,第八章那个 118/119 的账差还留在代码里。这三件事并不矛盾:一个诚实的实验台,比一个看起来完好的成品更有价值——因为前者会把「还没接的能力」和「已经错了的计算」都摆在你面前。下一步是把 TreeScan 接进计划卡副标题、把 VolumeLedger 的离线事件推进入匣队列、把 finishDrill 的计数改对,然后重新截一次图。
工程与后续更新统一托管在 AtomGit。
更多推荐



所有评论(0)