鸿蒙PC 文件工作台实战:用 ArkUI 打通文件、外设与系统能力调用的三层链路
鸿蒙PC 文件工作台实战:用 ArkUI 打通文件、外设与系统能力调用的三层链路
欢迎加入开源鸿蒙PC社区: https://harmonypc.csdn.net/
欢迎在PC社区平台申请新建项目:https://atomgit.com/OpenHarmonyPCDeveloper
前言:桌面端的「文件应用」和手机端的「文件应用」根本不是同一类东西。手机上用户点开一个文件,期望是「全屏打开、看完返回」;而在鸿蒙PC 这类 2in1 桌面设备上,用户要的是不打断的速览——左边一列卷宗,中间一块预览面,右边一栏元数据,鼠标在列表里上下扫、滚轮不离开当前视线,看到哪份就渲哪份。这带来三个工程问题:文件语义怎么建模(扩展名、大小、修改时间、来源目录四类信息谁说了算)、渲染怎么按类型分派(文本、代码、表格、图像、PDF、音频各有各的画法)、外设与系统能力怎么接(音频输出、打印、显示器密度、文件授权)。
本文以配套工程「卷宗 · FOLIO」为例,讲清楚在鸿蒙PC 上用 ArkUI 声明式 UI(ArkTS 语言,非 ArkUI-X 跨平台分支)把这三层链路搭起来:第一章到第五章是已在真机跑通的界面与状态层,第六、七章给出可直接落地的文件 / 外设 / 系统能力接入层实现,并明确标注哪些是实测、哪些是接入清单。截图全部来自鸿蒙PC 真机,不拿模拟器画面充数,也不把演示数据包装成真机回执。
关键词:鸿蒙PC、鸿蒙 PC、开源鸿蒙PC、ArkUI 声明式 UI、ArkTS、2in1 桌面形态、文件访问、DocumentViewPicker、外设与系统能力调用、MediaKit、AudioKit、AtomGit。

一、问题定义:桌面文件工作台的三层职责
先把「文件工作台」拆成三层,后面所有代码都挂在这三层上:
| 层 | 职责 | 失败表现 |
|---|---|---|
| 语义层 | 把一个文件变成可渲染、可筛选、可打标的数据对象 | 界面里到处 if (ext === 'png'),加一种格式改八个文件 |
| 视图层 | 按类型分派预览、按窗口宽度重排、保持滚动不跳 | 拉伸窗口后网格错位、长文本把窗口撑破、点击星标无反应 |
| 能力层 | 拿真实文件的 URI / fd / 元数据,调用系统与外设 Kit | 能在沙箱里跑,一接真文件就大量「打开了空白」 |
我给自己定了三条硬约束,本文的实现全部为满足它们:
- 单一数据源。 一份文件的可渲染内容、标签、是否钤星,全部收敛进同一个对象;界面只做派生,不存在第二处布尔值。
- 类型分派只在一处。 字形、配色、文案、预览体四件事都走同一个
FileKind枚举,任何地方都不许再判断扩展名字符串。 - 系统能力走桥接层。 视图里不直连
@kit.CoreFileKit,全部经过一层FileBridge;换真机、换权限模型时只改桥接层。
二、事实边界:先分清截图、工程与数据
进入代码前把材料摊开讲,避免读者误读。
第一类是截图。 本文 5 张配图全部是鸿蒙PC 真机的完整桌面截图:底部是系统 Dock(文件管理器、应用中心、设置等图标一字排开),顶部是系统状态栏与「11月16日 上午12:20」时间,背景露出 DevEco Code 的工程树(AppScope / entry / hvigor / build-profile.json5 / oh-package.json5),前台是可拖拽的「卷宗 · FOLIO」窗口。系统桌面与应用窗口同框,运行平台可以一眼确认。
第二类是工程。 项目源码/Folio_ohos,纯 ArkTS + ArkUI 声明式语法的 Stage 模型工程,应用名「卷宗 · FOLIO」,bundleName 为 com.folio.quicklook,versionName 1.0.0 / versionCode 1000000,deviceTypes 只写 ['2in1'],compatibleSdkVersion 与 targetSdkVersion 均为 26.0.0。它已构建出签名 HAP 并安装到鸿蒙PC 真机运行——四个视图的切换、星标变色、标签归集、日志入栈与底栏提示,都是这个 HAP 真实执行的结果。
第三类是数据。 工程里 7 份卷宗(瓷语 · 卷首.txt、preview_model.ets、窑务台账 · 冬季批次.xlsx、缠枝纹样 · 藏品照.png、展陈方案 · 终稿.pdf、窑火环境音.m4a、钴料采买清单.txt)来自 common/Models.ets 的构造数据,不是从磁盘扫描出来的。这一点我在第九章的截图说明里也会再写一次。本文不会把演示值写成实测值。
那么真正「已完成」的是什么?是语义模型、类型分派、三栏布局、滚动与刷新策略,以及一层可替换的文件能力桥接。这些真机跑通、可以直接复用;把桥接层的 select / stat / readText 换成真实实现,界面一行不用改就能读你的磁盘——第六、七章给完整做法。
最后交代用词:本文界面全部由 ArkUI 声明式语法直写(@Entry / @Component / @State / @Builder),不是 ArkUI-X。ArkUI 是鸿蒙原生声明式 UI 框架,ArkUI-X 是把它跨到其他平台的分支工程,两者在讨论鸿蒙PC 桌面交互时必须分清——本文用的能力(@kit.CoreFileKit、@kit.MediaKit、@kit.ArkUI 的 display)都只属于原生 ArkUI 这一侧。
三、语义层:把一份文件压成 11 个字段
桌面文件最容易被做错的一点,是把「文件名」当成唯一事实来源。真实场景里,文件名只提供名字和扩展名,大小和修改时间必须从文件句柄 stat 出来,来源目录则由用户选择路径决定。工程里的 FolioFile 把这三路信息拍平成一个对象:
export class FolioFile {
id: string; // 稳定标识,同时是 ForEach key 的基座
name: string; // 不含扩展名的展示名
ext: string; // 小写扩展名,仅用于角标与筛选
kind: FileKind; // 六类语义:text/code/sheet/image/pdf/audio
size: string; // 已格式化的体积文案,如 '4.8 MB'
modified: string; // 已格式化的时间文案,如 '2026-11-14 20:31'
origin: string; // 来源语义,如 '文稿库 / 青花卷'
tags: string[] = []; // 体积型标签,可追加
starred: boolean; // 钤星
excerpt: string[] = []; // 预览行缓存,避免预览时再解析
meta: string[] = []; // 元数据侧牌的行文案
}
三个建模决定值得展开。
其一,kind 与 ext 分离。 扩展名是用户可见的字符串(角标上要显示 XLSX),kind 是给渲染层用的枚举。二者分离后,.m4a 和 .wav 映射到同一个 audio,界面不用关心容器格式:
const f6 = new FolioFile('v6', '窑火环境音', 'm4a', 'audio', '7.7 MB',
'2026-11-10 16:44', '音频库 / 采样', false);
f6.tags = ['采样', '窑务'];
f6.excerpt = ['00:00 柴窑点火 · 劈啪声渐强', '01:24 恒温段 · 低频嗡鸣'];
f6.meta = ['时长 05:12', '采样率 48kHz', '声道 双声道', '码率 192kbps'];
其二,excerpt 预缓存渲染行。 文本、代码、表格的预览体在数据构造阶段就切好行塞进 excerpt,预览时零解析。桌面端用户会在列表里快速扫十几份文件,每份都现场切行会明显拖慢帧率:
const SHEET_ROWS: string[][] = [
['批次', '器物', '窑温', '成品率'],
['A-07', '梅瓶 ×12', '1300℃', '92%'],
['A-08', '笔洗 ×30', '1280℃', '88%']
];
f3.excerpt = SHEET_ROWS.map((r: string[]) => r.join(' '));
其三,origin 是语义路径而非绝对路径。 桌面应用不该在界面上暴露 /data/storage/el2/base/haps/entry/files/... 这种长度超过一屏的路径;工程用「文稿库 / 青花卷」两级语义目录,真接盘时由 FileBridge 把沙箱路径裁成末两级。
四、视图层之一:类型分派只写一次
common/Theme.ets 用四个纯函数把 FileKind 派生成字形、配色、标签、名称。这四个函数是整份代码里唯一允许出现「按类型分支」的地方:
export type FileKind = 'text' | 'code' | 'sheet' | 'image' | 'pdf' | 'audio';
export function kindGlyph(k: FileKind): string {
if (k === 'text') { return 'A'; }
if (k === 'code') { return '⌗'; }
if (k === 'sheet') { return '⊞'; }
if (k === 'image') { return '❖'; }
if (k === 'pdf') { return '▤'; }
return '♪'; // 兜底必须存在:新枚举值忘写分支时不会渲染出空白
}
export function kindColor(k: FileKind): string {
if (k === 'text') { return CeraColors.cobalt; }
if (k === 'code') { return CeraColors.okGreen; }
if (k === 'sheet') { return CeraColors.gold; }
if (k === 'image') { return CeraColors.copper; }
if (k === 'pdf') { return CeraColors.cobaltDeep; }
return CeraColors.inkDim;
}
预览体的分派在 components/PeekStage.ets,同样是「图像、音频、其余文本类」三支,而不是六支。桌面速览的核心不是把每种格式都做完,而是把没有专属渲染器的格式统一降级成行文本:
@Builder
previewBody(f: FolioFile) {
if (f.kind === 'image') {
Column({ space: 12 }) {
Stack() {
Circle({ width: 120, height: 120 }).fill(CeraColors.glazeDeep)
Circle({ width: 84, height: 84 }).fill(CeraColors.cobalt)
Text('❖').fontSize(40).fontColor(CeraColors.glazeWhite)
}
Text('缠枝纹样 · 藏品照(示意渲染)')
.fontSize(CeraText.sub).fontColor(CeraColors.inkDim)
}
.width('100%').layoutWeight(1).justifyContent(FlexAlign.Center)
} else if (f.kind === 'audio') {
Column({ space: 14 }) {
Row({ space: 6 }) {
ForEach([18, 34, 26, 48, 30, 52, 38, 24, 44, 28, 40, 20, 36, 50], (h: number) => {
Column().width(7).height(h).borderRadius(3).backgroundColor(CeraColors.cobalt)
}, (h: number) => `h${h}`)
}
Text('窑火环境音 · 05:12').fontSize(CeraText.sub).fontColor(CeraColors.inkDim)
}
.width('100%').layoutWeight(1).justifyContent(FlexAlign.Center)
} else {
Column({ space: 8 }) {
ForEach(f.excerpt, (ln: string, i: number) => {
Text(ln)
.fontSize(CeraText.body)
.fontColor(f.kind === 'code' && ln.startsWith('//') ? CeraColors.inkFaint : CeraColors.ink)
.fontFamily(f.kind === 'code' ? 'monospace' : 'sans-serif')
.width('100%').lineHeight(26)
}, (ln: string, i: number) => `${i}-${ln}`)
}
.alignItems(HorizontalAlign.Start).width('100%')
}
}
这里有个细节值得单独说:代码预览用 monospace 并给 // 开头的行降色,是为了让 preview_model.ets 这类源码在鸿蒙PC 上不用行号也能看出结构;表格预览则用四个空格对齐列,靠等宽字体的天然对齐顶替真正的 Table 组件。桌面端的速览要的是「一眼认出这是什么」,而不是「精确还原渲染结果」。
五、视图层之二:百分比网格与 layoutWeight 的双重约束
手机布局可以假设「屏幕宽高固定」,鸿蒙PC 不行:2in1 窗口可以自由拖宽拖窄、可以半屏贴边、可以被用户拖成一个窄条。工程里所有容器都用相对约束,一条固定 dp 宽度都不写死(除三栏的侧栏基准值):
export class CeraMetrics {
static readonly barHeight: number = 64;
static readonly shelfWidth: number = 320; // 左卷轴基准宽
static readonly metaWidth: number = 300; // 右元数据基准宽
static readonly cardGap: number = 14;
static readonly pagePad: number = 22;
}
三栏主体是「固定 + 弹性 + 固定」:左 320、右 300 固定,中间 layoutWeight(1) 吃掉剩余宽度。这样窗口从 1000dp 拉到 2000dp 时,松的是预览面,两侧稳定不动——用户在宽屏上不会看到侧栏被撑变形。
网格区用 Flex + width('23%') 而不是固定卡片宽:
Flex({ wrap: FlexWrap.Wrap, justifyContent: FlexAlign.Start }) {
ForEach(this.filtered(), (f: FolioFile) => {
Column() { this.fileCard(f) }
.width('23%')
.margin({ right: 10, bottom: 10 })
}, (f: FolioFile) => `${f.id}-${f.starred}-${this.kindFilter}-${this.onlyStarred}`)
}
.width('100%')
23% 的选择有算过:四列布局下 4 × 23% = 92%,剩下 8% 分给三个 10vp 的右边距,窗口变宽时按比例放大不会溢出成三列半。如果改用 220 这种固定值,窗口一窄就会出现「最后一张卡片被切一半」的桌面经典事故。
滚动容器则一律「Scroll + layoutWeight(1)」,绝不写 height('100%'):
Scroll() {
Column({ space: 10 }) { /* 卡片 */ }.width('100%')
}
.scrollBar(BarState.Auto)
.layoutWeight(1)
.align(Alignment.Top)
原因写在第十章的踩坑里:Scroll 一旦拿到 height('100%'),它就会跟父容器争高度,在可自由改高的 PC 窗口里表现为「内容多的那一屏滚不动,底栏把最后一张卡片压掉」。
六、能力层之一:文件的三态——URI / fd / 沙箱路径
这一章开始进入「文件」正题。鸿蒙上跟文件打交道,最耗时间的不是读字节,而是搞清楚手里这个东西到底是 URI、fd 还是路径。三者在工程里的分工是死的:
| 形态 | 长相 | 谁给的 | 能做什么 |
|---|---|---|---|
| URI | file://docs/storage/Users/.../瓷语.txt | 系统文件选择器 DocumentViewPicker | 打开成 fd;不能直接拼字符串当路径用 |
| fd | number | fs.openSync(uri, ...) | stat、read、copyFile;AVPlayer.fdSrc 只能吃它 |
| 沙箱路径 | /data/storage/el2/base/haps/entry/files/x.txt | 应用自己的 context.filesDir | fs.readTextSync 这类便捷接口;跨应用无效 |
桥接层 common/FileBridge.ets 把这三态收在一处,视图层只认 PickedFile:
// common/FileBridge.ets
import { picker, fileIo as fs, fileUri } from '@kit.CoreFileKit';
import { common } from '@kit.AbilityKit';
import { util } from '@kit.ArkTS';
import { image } from '@kit.ImageKit';
export interface PickedFile {
uri: string; // 临时授权标识,进程重启后可能失效
name: string;
ext: string;
sizeByte: number; // 来自 fd 的 stat,不信文件名
modifiedMs: number;
}
export class FileBridge {
/** 1. 拉起系统文件选择器。返回 string[],元素是 URI。 */
static async select(ctx: common.UIAbilityContext, max: number = 20): Promise<string[]> {
const view = new picker.DocumentViewPicker(ctx);
const opts = new picker.DocumentSelectOptions();
opts.maxSelectNumber = max;
opts.fileSuffixFilters = ['.txt', '.ets', '.xlsx', '.pdf', '.m4a', '.png'];
const uris = await view.select(opts);
return uris;
}
/** 2. 用 fd 读真实元数据:size / mtime 只能这样拿。 */
static stat(uri: string): PickedFile {
const file = fs.openSync(uri, fs.OpenMode.READ_ONLY);
try {
const st = fs.statSync(file.fd);
const tail = uri.substring(uri.lastIndexOf('/') + 1);
const dot = tail.lastIndexOf('.');
return {
uri: uri,
name: dot > 0 ? tail.substring(0, dot) : tail,
ext: dot > 0 ? tail.substring(dot + 1).toLowerCase() : '',
sizeByte: st.size,
modifiedMs: st.mtime * 1000
};
} finally {
fs.closeSync(file); // 只取元数据,必须立刻还句柄
}
}
}
三个必须记住的点:
其一,「选择文件」不需要声明读权限。 DocumentViewPicker 返回的 URI 自带临时读授权,用户在系统弹窗里点过那一下就是授权本身。反过来,如果你的应用声明了 ohos.permission.READ_MEDIA 之类的重权限去「自己扫目录」,在鸿蒙PC 上反而会触发权限审查并且扫不到用户没授权过的目录。授权跟着 URI 走,不跟着应用走,这是鸿蒙PC 文件模型跟传统桌面最大的差别。
其二,size 只能信 stat。 文件名里没有大小,扩展名推断不出体积;双击一份被替换过的文件时,缓存里的旧大小会误导用户。statSync(file.fd) 是唯一权威来源,注意 st.mtime 单位是秒,换算成毫秒要 ×1000。
其三,finally 里必须 closeSync。 ArkTS 没有 GC 兜底文件句柄的保证,漏一个 closeSync 在桌面端就是「打开二十份文件后新文件全部打不开」。这条在真机上极难复现、极难定位。
文本预览走 fd 直读,带上限保护:
static readText(uri: string, maxByte: number = 256 * 1024): string {
const file = fs.openSync(uri, fs.OpenMode.READ_ONLY);
try {
const size = Math.min(fs.statSync(file.fd).size, maxByte);
const buf = new ArrayBuffer(size);
fs.readSync(file.fd, buf);
return util.TextDecoder.create('utf-8').decodeToString(new Uint8Array(buf));
} finally {
fs.closeSync(file);
}
}
maxByte 这个上限不是保守,是保命:用户误选一个 2 GB 的日志文件,一次性 new ArrayBuffer(2GB) 会直接把 ArkTS 运行时打穿,表现为应用闪退且没有任何日志。桌面端的速览语义是「看开头几屏」,截断再解码反而是正确行为。
图像预览必须走 ImageKit,原因是 ArkUI 的 Image 组件不吃 file://docs/... 这种跨应用 URI:
static async loadPixelMap(uri: string): Promise<image.PixelMap> {
const file = fs.openSync(uri, fs.OpenMode.READ_ONLY);
const source = image.createImageSource(file.fd);
try {
return await source.createPixelMap({ desiredSize: { width: 960, height: 540 } });
} finally {
await source.release();
fs.closeSync(file);
}
}
desiredSize 是桌面端必须写的参数。一张 3840×2160 的藏品照如果按原尺寸解码进内存,四张就吃掉几百兆,而速览面只有 960×540 的显示区域——按显示尺寸解码,而不是按原始尺寸解码,是文件应用在鸿蒙PC 上不卡的关键。
如果确实需要把图片交给 Image 组件直接显示(比如要做缩略图列表),正确做法是先拷进应用缓存,再把沙箱路径转成 URI:
static copyToCache(ctx: common.UIAbilityContext, uri: string, name: string): string {
const file = fs.openSync(uri, fs.OpenMode.READ_ONLY);
try {
const dst = ctx.cacheDir + '/' + name;
fs.copyFileSync(file.fd, dst);
return fileUri.getUriFromPath(dst); // file://<bundleName>/cache/xxx.png
} finally {
fs.closeSync(file);
}
}
fileUri.getUriFromPath() 这一步不能省。直接拼 'file://' + path 在鸿蒙PC 上会被系统当成非法 URI 静默丢弃,Image 什么都不报,只显示空白——这类「不报错但没效果」的接口,是桌面文件应用里最难查的一类 bug。
七、能力层之二:外设与系统能力怎么接
文件工作台真正跟「外设」产生交集的地方有三处:音频输出(试听音频卷宗)、打印(把 PDF 卷宗送出去)、显示器与窗口(密度、可用区域)。再叠加两块系统能力:设备形态判定与权限申请。这一章按「一处外设一段代码」给完整实现。
7.1 音频外设:AVPlayer 的 fdSrc 与句柄生命周期
试听音频不能用沙箱路径喂 AVPlayer,它只接受三种源:url、fdSrc、dataSrc。跨应用 URI 必须先开成 fd:
// components/AudioPeek.ets
import { media } from '@kit.MediaKit';
import { fileIo as fs } from '@kit.CoreFileKit';
export class AudioPeek {
private player: media.AVPlayer | null = null;
private fd: fs.File | null = null;
async start(uri: string, onTick: (curMs: number, durMs: number) => void): Promise<void> {
await this.stop();
const file = fs.openSync(uri, fs.OpenMode.READ_ONLY);
const len = fs.statSync(file.fd).size;
const player = await media.createAVPlayer();
player.on('timeUpdate', (t: number) => onTick(t, player.duration));
player.on('stateChange', (state: media.AVPlayerState) => {
if (state === 'initialized') { player.prepare(); }
if (state === 'prepared') { player.play(); }
if (state === 'completed') { player.seek(0); player.pause(); }
});
player.fdSrc = { fd: file.fd, offset: 0, length: len };
this.player = player;
this.fd = file; // 播放期间必须持有 fd,绝不能提前 close
}
async stop(): Promise<void> {
if (this.player !== null) {
await this.player.release();
this.player = null;
}
if (this.fd !== null) {
fs.closeSync(this.fd);
this.fd = null;
}
}
}
这段代码里有两个原子顺序,颠倒就是线上事故:fdSrc 赋值必须在 createAVPlayer 之后、prepare 之前(状态机是 idle → initialized → prepared);closeSync 必须在 release() 之后(提前关 fd 会让播放中途静默中断,且 stateChange 不再回调,界面表现为进度条卡死)。先 release 再 close,是这类媒体外设调用的固定次序。
真正跟外设打交道的还有一处:音频路由。耳机插拔会让输出设备切换,桌面端要给出提示,否则用户会以为应用没声音:
import { audio } from '@kit.AudioKit';
export class AudioRoute {
static async outputs(): Promise<string[]> {
const mgr = audio.getAudioManager().getRoutingManager();
const devs = await mgr.getDevices(audio.DeviceFlag.OUTPUT_DEVICES_FLAG);
return devs.map((d: audio.AudioDeviceDescriptors) => d.name);
}
}
OUTPUT_DEVICES_FLAG 拿到的是当前所有可用输出端(扬声器、耳机、蓝牙、HDMI 显示器音频),而不是「正在用的那个」。要监听切换就再挂一次 deviceChange 回调,把返回的设备名刷进右侧元数据侧牌的 meta 数组——复用第四、五章已有的渲染路径,一行 UI 都不用改。
7.2 打印外设:一行调用,两行权限
PDF 卷宗要送打印机,用 Print Kit 只有一次调用:
import { print } from '@kit.BasicServicesKit';
export class PrintBridge {
static async send(uri: string): Promise<number> {
try {
await print.print([uri]);
return 0; // 已提交到打印队列
} catch (e) {
return 1; // 失败原因在 e 里,不要吞掉
}
}
}
但 print.print 需要在 module.json5 里声明权限,并在运行时申请:
{
"module": {
"requestPermissions": [
{ "name": "ohos.permission.PRINT",
"reason": "$string:reason_print",
"usedScene": { "abilities": ["EntryAbility"], "when": "inuse" } }
]
}
}
import { abilityAccessCtrl, common, Permissions } from '@kit.AbilityKit';
export async function ensurePrintPermission(ctx: common.UIAbilityContext): Promise<boolean> {
const at = abilityAccessCtrl.createAtManager();
const res = await at.requestPermissionsFromUser(ctx, ['ohos.permission.PRINT'] as Permissions[]);
return res.authResults[0] === 0;
}
注意 usedScene.when 写 inuse 而不是 always:鸿蒙PC 对常驻权限卡得比手机严,always 会成为上架审核的问题项。打印是典型的「用的时候才要」,inuse 才是对的语义。
7.3 显示器与窗口:不要硬编码尺寸
桌面端必须知道自己的显示密度,否则三栏基准宽在你的机器上好看、在 4K 屏上挤成一团:
import { display, window } from '@kit.ArkUI';
export async function probeScreen(): Promise<string> {
const d = display.getDefaultDisplaySync();
const win = window.getLastWindow(getContext());
const props = win.getWindowProperties();
return `${d.width}×${d.height} @${d.densityPixels.toFixed(2)} / 窗口 ${props.windowRect.width}dp`;
}
densityPixels 是「1vp 等于多少 px」的换算率。工程里 CeraMetrics.shelfWidth = 320 这类基准值在 2in1 上够用,但如果做自适应,正确写法是 320 * 一个 0.85~1.15 的系数,系数由窗口宽度反推——windowRect.width < 1100 时收窄侧栏,> 1600 时放开。这比「监听断点 + 三套布局」简单得多,也足够应对鸿蒙PC 上用户随手拉伸窗口的习惯。
7.4 设备形态判定:2in1 与非 2in1 走不同分支
同一份代码要被装到鸿蒙PC 和手机上时,形态判定不能靠屏幕尺寸猜,用 deviceInfo:
import { deviceInfo } from '@kit.BasicServicesKit';
export function isDesktop(): boolean {
return deviceInfo.deviceType === '2in1'; // 手机是 'phone',平板是 'tablet'
}
这个布尔值在工程里决定两件事:底部提示条要不要显示(手机没有鼠标,提示「选中即预览」没意义)、三栏要不要降级成单栏。而工程的 module.json5 里 deviceTypes 只写 ['2in1'],等于在安装阶段就把手机挡在门外——形态过滤优先写在清单里,别指望运行时分支兜底。
7.5 PC 专属:把文件拖进窗口
桌面用户不会去点「打开文件」按钮,他们直接从文件管理器把文件拖进来。ArkUI 的 allowDrop + onDrop 三行接住:
import { uniformTypeDescriptor as utd, unifiedDataChannel } from '@kit.ArkData';
Column() { /* 三栏主体 */ }
.allowDrop([utd.UniformDataType.FILE])
.onDrop((event: DragEvent, extraParams: string) => {
const data = event.getData() as unifiedDataChannel.UnifiedData;
if (data === null) { return; }
for (const rec of data.getRecords()) {
const uri = (rec as unifiedDataChannel.File).getUri();
if (uri !== '') { this.intake(uri); } // 复用 FileBridge.stat
}
})
allowDrop 必须显式声明接受的文件类型,写 FILE 才收得到文件 URI;不写的话 onDrop 根本不触发,这又是一处「不报错但没反应」的接口。intake 内部就是第六、七章的桥接层:stat 拿元数据 → 归类 kind → 塞进 files 数组 → 预览面切过去。
八、状态刷新:ArkUI 里最容易被忽略的两行代码
前七章的东西要真的动起来,还差状态刷新的正确写法。工程 pages/Index.ets 里有一段看起来「多余」的代码:
private star(id: string) {
let name = '';
for (const f of this.files) {
if (f.id === id) {
f.starred = !f.starred; // 直接改元素属性
name = f.name;
}
}
this.files = this.files.slice(); // 这一行不能删
this.log('钤星', `${name} ${this.starredOf(id) ? '钤星' : '去星'}`);
this.toast(this.starredOf(id) ? `「${name}」已钤星` : `「${name}」已去星`);
}
f.starred = !f.starred 改的是数组元素内部的属性。ArkUI 对 @State files: FolioFile[] 的观测粒度是「数组引用是否变化」以及「数组长度与元素引用是否变化」,不包含元素内部字段。所以只改 starred,界面不会刷新;this.files = this.files.slice() 用一次浅拷贝重建数组引用,才会触发依赖 files 的组件重渲。这一行删掉后的现象是:点星标,图标不变;切到别的视图再切回来,星星又亮了——因为数据其实早就改了。
第二处是 ForEach 的 key。工程里所有 key 都把「会影响渲染的状态」拼了进去:
// ShelfGrid
(f: FolioFile) => `${f.id}-${f.starred}-${this.kindFilter}-${this.onlyStarred}`
// PeekStage 左侧列表
(f: FolioFile) => `${f.id}-${f.starred}-${this.selectedId}`
如果 key 只写 f.id,ArkUI 会认为「同一个 key 就是同一个节点」,复用旧节点、跳过 fileCard 重建,结果就是星标、选中边框、筛选按钮的高亮全都不刷新。这两个坑我在同一份工程里各踩了一次,症状一模一样:数据变了,界面不动。
日志与提示是同一套思路:日志用不可变拼接([新项].concat(旧数组).slice(0, 40))保证引用变化,提示用 setTimeout 自管生命周期:
private log(action: string, text: string) {
this.logs = [new LogItem(this.now(), action, text)].concat(this.logs).slice(0, 40);
}
slice(0, 40) 这个上限是桌面端必须的:一个下午的整理操作能刷出几百条日志,不截断的话「翻阅志」视图的 ForEach 会持续膨胀,滚动开始掉帧。
九、真机运行:四个视图与它们在鸿蒙PC 上的样子
下面 5 张图全部是鸿蒙PC 真机完整桌面截图(底部 Dock + 顶部状态栏 + 前台应用窗口)。需要说明的是:截图里的 7 份卷宗是工程内置的演示卷宗(Models.ets 构造数据),不是磁盘扫描结果,界面上的「元数据侧牌」也因此是构造值。第六、七章的能力层代码是接入实现,尚未在这 5 张截图里启用——这一点本文从第二章就讲明了,不做事后修饰。
9.1 卷轴阁:百分比网格在宽窗口下的表现

这是应用的主视图。顶部是四条视图的切换条(卷轴阁 / 速览台 / 标签阁 / 翻阅志),中间是类型筛选(全部 / TEXT / CODE / SHEET / IMAGE / PDF / AUDIO),下面是四列网格。可以看到窗口被拖得比较宽时,四列卡片仍然等分、右边距保持一致——这就是第五章 width('23%') 的效果。每张卡片左下角是体积型标签(手稿、青花),右下角是星标按钮。注意卡片上的类型角标(TXT / ETS / XLSX / M4A / PDF)和圆形底色:颜色由 kindColor 派生,青花蓝、窑火红、苔绿各司其职。
9.2 速览台:三栏不打断的预览布局

这张图是本工程的核心交互。左侧「卷轴」列是 320dp 固定宽,中间预览面吃剩余宽度,右侧「元数据侧牌」300dp。中央显示的是 preview_model.ets 的代码预览——等宽字体、export class 与 render 正常缩进、右上角是「☆ 钤星」按钮。右侧侧牌列出的是「语言 ArkTS / 行数 12 / 缩进 2 空格 / 依赖 0」与来源、印章印记。鼠标在左侧列表上下扫、中间预览跟着换,视线不需要离开当前区域,这正是桌面速览与手机全屏打开的根本差别。
9.3 速览台空态:空态的引导文案

未选中任何卷宗时的空态。工程没有用「加载中」占位,而是直接给出下一步动作:「从左侧卷轴选一份文件开始速览」。底部提示条同时写死了这条交互规则:「速览不打断整理:选中即预览,钤星与加签即时入志」。桌面应用的空态必须告诉用户下一步做什么,这一点跟移动端「空页面 + 一行灰字」的做法完全不同。
9.4 标签阁:点选瓷印归集卷宗

标签视图。八枚标签(青花 2 / 手稿 1 / 工程 1 / 台账 1 / 纹样 1 / 定稿 1 / 窑务 2 / 展陈 1)横向排开,每枚前面有一枚对应色的小圆点,后面跟当前归集数量。点任意一枚,下方立刻列出该标签下的卷宗,速览 → 一键跳回速览台。这里的数量是运行时算出来的(countOf 遍历 files),不是写死的文案——加一个标签,数字立刻变,这是语义层建模带来的直接收益。
9.5 翻阅志:操作轨迹的完整留痕

最后一个视图是操作轨迹。每次速览、钤星、加签都会入栈一条,最新一条高亮(深底 + 钴青描边),其余为白底。左侧是时间(00:20),中间是动作胶囊(「速览」深青、「钤星」金色、「加签」钴青),右侧是描述文案。桌面文件应用里,「我刚才到底动过哪份文件」是高频需求,一份不留痕的工作台在真实使用里基本不可用。
十、踩坑清单:十个在鸿蒙PC 桌面开发里最容易踩的坑
这些坑不是纸上推演:下面十条里前两条是本工程里真实踩到的(症状就是「数据变了界面不动」),其余是同一类桌面文件应用在鸿蒙PC 上反复出现的同源问题,按出现频率排序:
@State数组元素属性改了不刷新。 必须this.files = this.files.slice()重建引用。症状:点星标图标不动,切视图回来又对了。ForEachkey 不含状态,节点被错误复用。 星标、选中边框、筛选高亮一起失效。key 里必须拼进所有参与渲染的状态。Scroll写height('100%')会让滚动失效。 PC 窗口高度可变,父容器与Scroll争高度;改layoutWeight(1)。Image组件不吃file://docs/...跨应用 URI。 要么image.createImageSource(fd)转PixelMap,要么copyFileSync进cacheDir再fileUri.getUriFromPath()。手拼'file://' + path一定失败且不报错。st.mtime单位是秒。 直接当毫秒用,时间会显示成 1970 年。AVPlayer播放期间不能关 fd。 先release()再closeSync(),顺序颠倒表现为进度条卡死、无声。fdSrc必须在createAVPlayer之后、prepare之前赋值。 状态机顺序错了,stateChange不回调,什么都不发生。deviceTypes写['2in1']就在安装阶段完成形态过滤。 但compatibleSdkVersion必须写全三位(26.0.0),写26会构建报错。allowDrop不声明文件类型,onDrop不触发。 必须[utd.UniformDataType.FILE],否则拖拽静默失败。- 别用重权限去「自己扫目录」。
DocumentViewPicker的 URI 自带临时读授权,声明READ_MEDIA反而触发审查且扫不到未授权目录。
十一、构建、安装与复现
工程是标准 Stage 模型,DevEco Studio 打开 Folio_ohos 直接 Run 即可。CLI 复现路径如下(hdc 目标为鸿蒙PC 真机):
# 1. 构建签名 HAP
hvigorw assembleHap --mode module -p product=default -p buildMode=debug
# 2. 安装到鸿蒙PC
hdc install -r entry/build/default/outputs/default/entry-default-signed.hap
# 3. 拉起应用
hdc shell aa start -a EntryAbility -b com.folio.quicklook
若安装报 9568263 downgrade,说明同 bundleName 的旧包 versionCode 更高,先 hdc uninstall com.folio.quicklook 再装。签名配置里 bundleName 被 profile 锁定,改了 app.json5 的 bundleName 必须同步换签名,否则装上去的仍是旧包名。
十二、小结:文件工作台的三层可以分别演进
回到开头那个三层划分。这套结构真正的好处是三层可以各自独立演进,互不牵连:
- 语义层要加一种格式?只改
FileKind枚举和Theme.ets四个纯函数,FolioFile构造处补一条数据,界面零改动。 - 视图层要换成双栏或单栏?只动
CeraMetrics的基准宽与deviceInfo.deviceType那一个分支,语义层不动。 - 能力层要接真文件、真外设?只改
FileBridge、AudioPeek、PrintBridge三个桥接类,界面一行不改。
这就是为什么我在第一章把「系统能力走桥接层」写成硬约束:鸿蒙PC 的系统 Kit 演进很快(fileIo 的同步接口、AVPlayer 的状态机、picker 的选项字段都在小版本里动过),能力调用一旦散落在视图里,每次 Kit 变更都要在整个工程里找调用点。桥接层把这层成本压到三个文件里。
最后再强调两句事实边界:本文 5 张截图来自鸿蒙PC 真机,界面、状态迁移、日志与提示是工程实测跑通的;截图中的卷宗数据来自 Models.ets 的构造数据,第六、七章的文件 / 外设 / 系统能力代码是可落地接入的实现,不是截图里已启用的功能。把 Models.ets 的 FolioData.files() 换成 FileBridge.select + FileBridge.stat 的扫描结果,这套界面就直接变成你的真实文件工作台——接口已经对齐,缺的只是那一行替换。
工程源码与后续更新托管在 AtomGit:项目源码/Folio_ohos,标准 Stage 模型、无三方依赖、oh-package.json5 只有 modelVersion 5.0.0。欢迎在开源鸿蒙PC 社区交流更多 2in1 桌面形态下的 ArkUI 实践。
更多推荐




所有评论(0)