鸿蒙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 上。

鸿蒙PC 真机完整桌面:织匣 Arcvault 首屏,三栏布局与空态

图 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,不用递归

扫描器写成迭代式,而不是递归函数调用,理由有三个,都跟桌面场景强相关:

  1. 深度不可控。用户的工程目录可能有几十层,递归会吃掉栈;迭代用显式 stack: string[],堆内存比栈安全。
  2. 可中断。while (stack.length > 0 && !truncated) 这个条件让扫描可以在任意文件处停下,把剩余目录留在栈里——这就是「增量备份能做到秒级响应」的实现基础。
  3. 可观测。每处理完一个目录就能吐出一次进度,界面上的进度条不用等整棵树扫完。

完整实现(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);
}

三个必须配齐的东西,缺一个就会静默失败:

  1. 权限:module.json5 里声明 ohos.permission.KEEP_BACKGROUND_RUNNING(normal 级,无需用户弹窗)。
  2. 模式:BackgroundMode.DATA_TRANSFER,对应「数据传输」长时任务类型。用错模式(比如 AUDIO_PLAYBACK)会被系统在审核或运行阶段拒绝。
  3. 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_RUNNINGnormal6.3 长时任务startBackgroundRunning 抛 201
ohos.permission.FILE_ACCESS_PERSISTnormal5.2 持久化授权目录persistPermission 抛 201
ohos.permission.STORAGE_MANAGERsystem_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 已经在第二章出现过(首屏空态),它回答的是「三栏在宽窗口下怎么站住」。剩下三张是同一份代码在不同状态下的采样,正好把状态机的三条支路走了一遍。

鸿蒙PC 真机完整桌面:手动备份触发后,快照胶片带新增一格,左侧详情显示演练进行中 86%

图 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; } 挡住重复点击。功能上没问题,视觉上更省事,但严格说这是「看起来禁用、实际可点」的不一致,属于下一轮要收拾的细节。

鸿蒙PC 真机完整桌面:选中的增量快照产生两条演练报告,一条无保留意见、一条带两条意见

图 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 调大,让两条意见必然同时出现,是值得养成的习惯。

鸿蒙PC 真机完整桌面:同一状态稍后采样,工坊日志继续累积、传输带进度前移

图 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。

Logo

作为“人工智能6S店”的官方数字引擎,为AI开发者与企业提供一个覆盖软硬件全栈、一站式门户。

更多推荐