鸿蒙PC上的ArkUI跨平台实战:用ArkTS与Canvas 2D织一张可拖拽的关系图谱

欢迎加入开源鸿蒙PC社区: https://harmonypc.csdn.net/

欢迎在PC社区平台申请新建项目:https://atomgit.com/OpenHarmonyPCDeveloper

前言

Topograph(图谱织造台)是一款只面向桌面形态的关系图编辑器。它把节点与边当作一等公民:可以在画布上拖拽节点改变位置,可以点一下空白处落下一颗新节点,也可以把整张图交给力导向算法重新收敛。从第一行清单文件到最后一次真机自检,整个工程都在鸿蒙PC 本机的 DevEco Studio 里完成,没有借助手机形态的缩放去凑桌面观感。

技术栈只讲两层。ArkUI 是鸿蒙生态的声明式 UI 框架,页面用 ArkTS 描述,组件树、状态、布局约束、事件分发都由它统一负责;ArkUI-X 是在 ArkUI 之上构建的跨平台框架,把同一套声明式开发范式延伸到 Android、iOS 等平台。这两者的分工必须说清楚:ArkUI 决定"界面怎么写",ArkUI-X 决定"这套写法能落到哪些运行环境"。所以本文讨论的跨平台,是页面层与平台能力层之间那条可迁移的边界,而不是把 ArkTS 直接编译成某个桌面系统的原生程序。本文的界面部分全部使用 ArkUI 的声明式语法,平台能力一律收进 Ability 层;这条分界线,同时决定了将来若把覆盖范围交给 ArkUI-X 跨平台框架,需要改的到底是哪几行。

边界也要先交代清楚,免得读者照着抄时产生误解。当前的图谱数据只活在内存里:新增节点不落盘,重启后回到初始的 8 节点 10 边环形结构;画布尺寸固定 960×520,不随窗口拉伸重算;自动布局是同步的 90 轮迭代,节点规模上去以后必须改成分批推进。这三条都是明确的取舍,下文会逐个解释为什么这样写、代价在哪里。

关键词:鸿蒙PC、ArkUI跨平台框架、ArkUI-X、ArkTS、Canvas 2D、OpenHarmony PC、声明式UI、图可视化

Topograph在鸿蒙PC电脑上的运行现场

图1:鸿蒙PC 上的运行现场。顶部是系统状态栏,底部是桌面 Dock,应用窗口占满屏,右上角是系统下发的窗口控制按钮——这三点同时出现在一张图里,才能证明它确实跑在鸿蒙PC 上,而不是被拉伸的手机界面。

一、工程起点:先把"这台机器是 PC"写进清单

鸿蒙PC 应用与手机应用的第一处差别不在界面代码,而在工程清单。很多人写多端项目时习惯先把页面写完、最后才补 deviceTypes,结果是在桌面设备上装不上,或者装上了却是被拉宽的窄栏布局。Topograph 反过来做:先锁设备形态,再写第一行 UI。

module.json5 里把 deviceTypes 收窄为单一形态,意味着应用分发层面就只认二合一/PC 设备:

{
  module: {
    name: 'entry',
    type: 'entry',
    mainElement: 'EntryAbility',
    deviceTypes: ['2in1'],
    pages: '$profile:main_pages',
    abilities: [
      {
        name: 'EntryAbility',
        srcEntry: './ets/entryability/EntryAbility.ets',
        exported: true,
        skills: [ { entities: ['entity.system.home'], actions: ['action.system.home'] } ]
      }
    ]
  }
}

build-profile.json5 里锁编译目标。从 API 26 起 compatibleSdkVersion 不再接受整数,必须写成三段式 26.0.0;useNormalizedOHMUrl 打开规范化模块地址,多模块引用时能避免路径解析歧义:

"products": [
  {
    "name": "default",
    "compatibleSdkVersion": "26.0.0",
    "runtimeOS": "HarmonyOS",
    "buildOption": {
      "strictMode": { "useNormalizedOHMUrl": true }
    }
  }
]

入口 Ability 只有二十来行,却是整个跨平台边界的分水岭:窗口、日志、生命周期全部收在这一层,页面层一行都不碰。主窗口请求内容延伸到装饰区,再加载首页:

import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { window } from '@kit.ArkUI';

export default class EntryAbility extends UIAbility {
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    hilog.info(0x0000, 'Topograph', 'Topograph onCreate');
  }

  onWindowStageCreate(windowStage: window.WindowStage): void {
    windowStage.getMainWindow()
      .then((win) => { win.setWindowLayoutFullScreen(true).catch(() => { }); })
      .catch(() => { });
    windowStage.loadContent('pages/Index', (err) => {
      if (err.code) {
        hilog.error(0x0000, 'Topograph', 'load fail %{public}s', JSON.stringify(err));
      }
    });
  }
}

getMainWindow() 与 setWindowLayoutFullScreen() 都返回 Promise,这里做了两层 catch 兜底:窗口能力在不同设备与不同系统版本上的可用范围并不一致,失败时不应该把首页加载一起拖住。代价是内容会顶到窗口装饰区,系统把最小化、最大化、关闭三个按钮叠在右上角,所以顶栏右侧必须让位。

在鸿蒙PC本机DevEco Studio中开发Topograph

图2:开发现场。左侧是鸿蒙PC 本机运行的 DevEco Studio 工程树(Topograph_ohos),右侧悬浮着正在运行的应用窗口,底部是鸿蒙PC 桌面 Dock。工程编写、构建、调试、真机运行四件事发生在同一台电脑上。

二、ArkUI 声明式骨架:宽屏上的一屏三段

鸿蒙PC 的可用宽度通常是手机的两倍以上,但信息密度受限于人眼在桌面观看距离下的可读性。Topograph 的取舍是:纵向一条主流程,横向只在顶栏分左右。骨架只保留三层——顶栏常驻,下面用 Scroll 承载"标题句 + 工具条 + 画布":

build() {
  Column() {
    this.topBar()
    Scroll() {
      Column({ space: 20 }) {
        this.hero()
        this.toolPanel()
        Column() {
          Canvas(this.ctx)
            .width(WW).height(WH)
            .backgroundColor('rgba(20,17,44,0.5)')
            .borderRadius(20)
            .onReady(() => { this.drawGraph(); })
            .onTouch((ev: TouchEvent) => { this.handleTouch(ev); })
        }
        .width('100%').padding(2).borderRadius(22)
        .border({ width: 1, color: G.LINE })
      }
      .width('100%').padding({ left: 28, right: 28, bottom: 40 })
    }
    .scrollable(ScrollDirection.Vertical).scrollBar(BarState.Off)
    .width('100%').layoutWeight(1)
  }
  .width('100%').height('100%').backgroundColor(G.BG)
}

三处细节值得单独拎出来。第一,Scroll 用 layoutWeight(1) 而不是固定高度,这样窗口在鸿蒙PC 上被拉高或压低时,滚动区自动吃掉剩余空间,顶栏永远贴顶。第二,顶栏用 Blank() 撑开左右两端,选中的节点名以胶囊形态停在右侧,这是桌面应用常见的"状态回显"位置,比在手机上加一行说明更省纵向空间。第三,三处重复的按钮被抽成 @Builder toolBtn(label, active, fn),状态色靠 linearGradient 表达,激活时用青色到紫色渐变,未激活时用 5% 白色蒙层——同一种组件在不同状态下不需要两套布局代码。

状态只有六个:nodes、edges、selected、addMode、tick、statsStr。把"8 节点 · 10 边 · 选中度 2"这类统计预先算成字符串 statsStr,而不是在 build() 里遍历边数组求值,是一个刻意的小优化:build() 会被频繁重入,任何 O(E) 的计算放在里面都会被放大成帧率问题,而放进 refreshStats() 只在选中变化时执行一次。

三、Canvas 2D 绘制管线:从图数据到 312 个点阵

画布是这台工具的主体,也是 ArkUI 里唯一需要命令式思维的地方。上下文在组件外创建,构造参数 true 表示开启抗锯齿:

private ctx: CanvasRenderingContext2D = new CanvasRenderingContext2D(new RenderingContextSettings(true));

数据模型同样只有两个类,节点带位置、半径与颜色,边带权重:

export class GNode {
  id: number; label: string;
  x: number; y: number; r: number; color: string;
  constructor(id: number, label: string, x: number, y: number, color: string) {
    this.id = id; this.label = label; this.x = x; this.y = y; this.r = 22; this.color = color;
  }
}

export class GEdge {
  from: number; to: number; weight: number;
  constructor(from: number, to: number, weight: number) { this.from = from; this.to = to; this.weight = weight; }
}

一次完整重绘分四层,顺序不能颠倒:清屏、背景点阵、边、节点。背景按 40px 步长铺点,960×520 的画布对应 24×13 共 312 个 arc;点被刻意画得很小(半径 1.3)并压到 10% 透明度,它的作用是给拖拽提供空间参照,而不是当装饰:

private drawGraph(): void {
  const ctx = this.ctx;
  if (!ctx) { return; }
  ctx.clearRect(0, 0, WW, WH);

  ctx.fillStyle = 'rgba(124,108,255,0.10)';
  for (let gy = 0; gy < WH; gy += 40) {
    for (let gx = 0; gx < WW; gx += 40) {
      ctx.beginPath();
      ctx.arc(gx, gy, 1.3, 0, Math.PI * 2);
      ctx.fill();
    }
  }

  for (const e of this.edges) {
    const a = this.findById(e.from);
    const b = this.findById(e.to);
    if (!a || !b) { continue; }
    const grad = ctx.createLinearGradient(a.x, a.y, b.x, b.y);
    grad.addColorStop(0, a.color);
    grad.addColorStop(1, b.color);
    ctx.strokeStyle = grad;
    ctx.lineWidth = 1.5 + e.weight * 0.6;
    ctx.globalAlpha = 0.6;
    ctx.beginPath();
    ctx.moveTo(a.x, a.y);
    ctx.lineTo(b.x, b.y);
    ctx.stroke();
    ctx.globalAlpha = 1;
    ctx.fillStyle = '#8A84B8';
    ctx.font = '13px sans-serif';
    ctx.fillText(`${e.weight}`, (a.x + b.x) / 2 - 6, (a.y + b.y) / 2 - 6);
  }
}

边用两端节点色做线性渐变,lineWidth = 1.5 + weight * 0.6,权重 4 的边实测线宽 3.9,视觉上刚好比权重 2 的边重一档。两个必须复位的地方:globalAlpha 用完立刻回 1,否则后面的节点会连带变半透明;ctx.shadowBlur 在节点绘制完立刻归零,否则下一次 fill 会继续带着高斯模糊,画面会出现一层说不清来源的雾。这两类"上下文状态残留"是 Canvas 2D 最容易踩的坑,它们不会报错,只会让颜色和清晰度莫名偏差。

节点的画法做了三层叠加:外层带 shadowBlur 的彩色圆晕(选中 26、未选中 14),中间一层 55% 不透明度的深色内芯把圆做成环,最后用 16px 文字写标签。textAlign 一旦设成 center 就会持续生效,所以标签坐标直接给节点中心,不必再算字宽。

四、触摸交互:命中测试、拖拽与落子

鸿蒙PC 上的鼠标左键在 ArkUI 的事件体系里同样以 TouchType.Down/Move/Up 进入 onTouch,鼠标点击会被映射成一到多个触摸点,ev.touches[0] 就是当前指针位置。这一点非常关键:同一套交互代码同时服务触屏与鼠标,不需要为桌面单独写一份 onMouse,这是 ArkUI 在鸿蒙PC 上"手感一致"的底层原因之一。

流程只有三条分支。按下时先做命中测试,命中就进入拖拽并同步选中态;未命中且处于添加模式,就在落点创建一个新节点;移动时改坐标并重绘;抬起时清掉拖拽标记:

private handleTouch(ev: TouchEvent): void {
  if (ev.touches.length === 0) { return; }
  const t = ev.touches[0];
  const x = t.x, y = t.y;
  if (ev.type === TouchType.Down) {
    const idx = GraphEngine.hitTest(this.nodes, x, y);
    if (idx >= 0) {
      this.dragging = idx;
      this.selected = idx;
      this.refreshStats();
    } else if (this.addMode) {
      const nd = new GNode(this.nextId++, `K${++this.nodeSeq}`, x, y, G.AMBER);
      this.nodes = this.nodes.concat([nd]);
      this.selected = this.nodes.length - 1;
      this.refreshStats();
    }
    this.drawGraph();
  } else if (ev.type === TouchType.Move) {
    if (this.dragging >= 0 && this.dragging < this.nodes.length) {
      this.nodes[this.dragging].x = x;
      this.nodes[this.dragging].y = y;
      this.drawGraph();
    }
  } else if (ev.type === TouchType.Up) {
    this.dragging = -1;
    this.tick += 1;
    this.refreshStats();
  }
}

命中测试用的是"最近邻 + 半径容差",而不是逐点精确判定。节点半径 22,判定阈值给 38,多出来的 16px 是留给手指与鼠标的容错:

static hitTest(nodes: GNode[], x: number, y: number): number {
  let best = -1;
  let bestD = 38;
  for (let i = 0; i < nodes.length; i++) {
    const dx = nodes[i].x - x, dy = nodes[i].y - y;
    const d = Math.sqrt(dx * dx + dy * dy);
    if (d < bestD) { bestD = d; best = i; }
  }
  return best;
}

这里有一条纪律必须记住:Canvas 不会因为状态变化自动重绘。它不像 Text 那样有 diff,@State 改了数据,画布依旧停在上一次 drawGraph() 的结果上。所以每一处改完数据的代码后面都紧跟一次绘制调用,this.nodes = this.nodes.concat([nd]) 这种换引用的写法也是为了让依赖 nodes 的表达式重新求值。tick += 1 在抬起时递增,是为了给顶栏那类依赖状态的表达式一次重新求值的机会,真正决定画面内容的仍然是紧随其后的 drawGraph()。

添加模式下画布出现青色虚线边界

图3:添加模式。整块画布被 2px 青色虚线框住并在顶部给出文字提示,此时空白处按下即落子,新增节点统一用琥珀色,与初始节点的配色区分开。这是"模式"该有的样子:状态可见,而不是藏在某个菜单里。

五、力导向布局:90 轮迭代的成本与边界

自动布局是整份代码里唯一带算法味道的部分。每个节点同时受三种力:节点之间的斥力、沿边的弹簧引力、以及一个把图拉回画布中心的弱回中力。

static layout(nodes: GNode[], edges: GEdge[], W: number, H: number): void {
  let it = 0;
  while (it < 90) {
    for (let i = 0; i < nodes.length; i++) {
      let fx = 0, fy = 0;
      for (let k = 0; k < nodes.length; k++) {
        if (i === k) { continue; }
        let dx = nodes[i].x - nodes[k].x;
        let dy = nodes[i].y - nodes[k].y;
        let d = Math.sqrt(dx * dx + dy * dy);
        if (d < 1) { d = 1; dx = 1; dy = 0; }
        const f = 3400 / (d * d);
        fx += dx / d * f;
        fy += dy / d * f;
      }
      for (const e of edges) {
        if (e.from !== i && e.to !== i) { continue; }
        const other = e.from === i ? e.to : e.from;
        const dx = nodes[other].x - nodes[i].x;
        const dy = nodes[other].y - nodes[i].y;
        const d = Math.sqrt(dx * dx + dy * dy) || 1;
        const f = (d - 130) * 0.04;
        fx += dx / d * f;
        fy += dy / d * f;
      }
      fx += (W / 2 - nodes[i].x) * 0.01;
      fy += (H / 2 - nodes[i].y) * 0.01;

      nodes[i].x += fx * 0.5;
      nodes[i].y += fy * 0.5;
    }
    it++;
  }
}

参数是调出来的,不是抄来的。斥力系数 3400、除以距离平方,在 150px 间距下每轮贡献约 0.15 的位移倾向;弹簧参考长度 130,意思是"边希望两端相距 130px",比初始的 300px 环半径收紧一半,所以布局后图会明显向中心收拢;回中力 0.01 只是为了防止孤立节点飘出画布;位移乘 0.5 是阻尼,防止 90 轮里来回震荡。

复杂度是 O(轮数 × 节点数²)。8 节点时每轮约百次距离计算,90 轮总共不到一万次,在鸿蒙PC 上点一下是跟手的。但这个式子对规模非常敏感:节点涨到 100,90×100×100 就是 90 万次浮点开方,同步执行会直接吃掉几十毫秒,界面上就是一次可见的卡顿。真正要扩到上百节点,路线是三条而非一条——把迭代拆进 TaskPool 或按帧分批(每帧 10 轮并插值动画)、用格子桶做近邻剪枝把 O(n²) 降到接近 O(n)、或者只在数据变化时算一次布局并把结果缓存下来。当前版本选择了最直白的同步写法,代价就是这个上限。

六、ArkUI 跨平台边界:哪些代码能带走,哪些必须重写

写到这里可以回答那个最容易被含糊带过的问题:ArkUI 跨平台框架到底带走了什么?把工程按依赖切开看,答案很清楚。

文件依赖迁移成本
pages/Index.etsArkUI 组件、Canvas、TouchEvent、@State、@Builder直接复用
common/Theme.ets纯字符串常量直接复用
engine/GraphEngine.ets纯 TS 计算,无平台 API直接复用
entryability/EntryAbility.etsUIAbility、window、hilog平台适配层,按目标平台各写一份

这份切分不是事后整理出来的,而是写第一行代码时就定下的:页面层只允许出现 ArkUI 的东西,任何窗口、日志、文件、存储相关的能力一律上推到 Ability 层。结果是四份源文件、四百多行代码里,只有二十行与鸿蒙PC 强绑定。

ArkUI-X 的角色是提供这层"带走"的运行时与工程结构:代码以 shared 模块组织,各平台再各自提供入口与能力实现,组件模型、布局、状态管理、绘制接口都从 ArkUI 延续下来。必须把话说准确——本仓库是原生鸿蒙PC 工程,跑在 ArkUI 运行时上,不是 ArkUI-X 的编译产物;它的价值在于页面层没有任何鸿蒙PC 专有 API,所以迁到 ArkUI-X 的工程结构里时,改动集中在入口与能力适配,而不是重写界面。反过来,如果一开始就把窗口尺寸、路径、日志直接写在页面里,跨平台框架再好也救不回来。这就是我把它称为"边界纪律"而不是"技术选型"的原因。

七、真机现场:用状态回显判断界面是否真的在跑

工程在鸿蒙PC 上跑通之后,自检的方式不是先看日志,而是看状态是否"一眼可辨"。选中一颗节点,顶栏右侧胶囊立刻回显节点名,右下统计从"选中度 0"变成"选中度 2",被选中的圆环外侧光晕从 14 提到 26——同一份数据驱动了三处不同的视觉反馈,这是 ArkUI 声明式更新的典型收益:只需改一个 selected,不用手写任何显隐代码。

选中节点后的状态联动

图4:选中"计算内核"。顶栏胶囊、右下角统计、圆环光晕三处同时跟随,画布上的边因为端点高亮而呈现出更明显的渐变方向。

需要清醒的一点是:这三处联动里,只有前两处是 ArkUI 帮你刷的,第三处(画布光晕)仍然是 drawGraph() 手动重绘的结果。声明式与命令式混用时,一定要能分清哪一半归框架、哪一半归自己,否则就会写出"数据对了但画面不动"的代码,然后开始怀疑状态管理。

八、把坑记下来:鸿蒙PC 上写图形应用的十条经验

  1. deviceTypes 只写 ['2in1'] 之后,手机形态的设备在安装阶段就会被拦下。这是有意的:宁可装不上,也不要让用户在手机上看到一张 960px 宽、被压成窄条的关系图。
  2. compatibleSdkVersion 必须写三段式 26.0.0。这条在 API 26 上没有任何兼容空间,写 26 会直接编译失败。
  3. Canvas 的首次绘制只能放在 onReady 里。aboutToAppear 阶段上下文还没绑上绘制表面,此时调用 drawGraph() 不会报错,只是画面空白——排查时极容易被带偏。
  4. 画布内容不会随状态自动刷新,@State 改了必须手动重绘。这是声明式框架里唯一需要"记得"的地方。
  5. shadowBlur、globalAlpha、setLineDash、textAlign 都是上下文状态,用完必须复位。虚线的复位写法是 ctx.setLineDash([]),而光晕要写 ctx.shadowBlur = 0。
  6. 全屏延伸之后,右上角会有系统下发的窗口控制按钮压住内容。顶栏的右侧胶囊因此不能贴边,padding 要给够。
  7. TouchEvent 里的坐标是相对组件左上角的本地坐标,不是屏幕坐标。画布外面套了一层 2px 内边距的容器,所以坐标直接给 Canvas 用,不需要再减偏移——但一旦给容器加上大于 2px 的 padding,就必须补回这个偏移量。
  8. 用 concat 换引用而不是 push 原地改,是为了让依赖 nodes 的表达式重新求值,顺带省掉一次"数据改了但界面没动"的排查。
  9. 力导向布局不要放在 build() 或任何会被频繁重入的位置。当前实现是点击触发的一次性计算,所以 90 轮同步迭代还能接受。
  10. 渐变对象 createLinearGradient 每帧为每条边新建一次。8 节点 10 边时开销可以忽略,边数上百时应该缓存成按节点色对索引的字典,避免每帧重复构造。

九、小结:ArkUI 在鸿蒙PC 上的三个确定收益

回到最初的问题:在鸿蒙PC 电脑上写鸿蒙PC 应用,ArkUI 到底值不值得?Topograph 这份四百多行的工程给出了三个具体答案。

其一,布局表达力够用。一套 Column/Row/Scroll 加 layoutWeight 与 Blank,就撑起了桌面级的顶栏、工具条、大画布三种密度完全不同的区域,没有出现需要手写像素定位的场合。

其二,事件与状态够直接。鼠标和触屏共用 onTouch,@State 加 @Builder 把六个状态的界面表达压到两百行以内,改一个 selected 就能联动三处反馈。

其三,也是最重要的一点:平台边界可以画得很干净。能力全部收进 EntryAbility,页面层只剩 ArkUI 与 Canvas 2D,于是当需要把这套界面交给 ArkUI-X 跨平台框架去覆盖更多运行环境时,改动落点在入口与适配层,界面代码不用重写。ArkUI-X 在这条边界上提供的是运行时、组件映射与工程结构,它替不了任何人做架构决定;真正的可迁移性,来自你从第一行代码起就没在页面里写死平台。跨平台框架的价值从来不是让人少写一个页面,而是让"哪些属于平台、哪些属于产品"这件事在代码结构上被强制分清。

工程全部代码与清单托管在 AtomGit 的 OpenHarmony PC 开发者组织下,可按文中的清单文件、Ability、引擎、页面四层逐项对齐;如果你想直接在鸿蒙PC 上跑起来,从 deviceTypes 和 compatibleSdkVersion 这两行开始抄,能避开本节一半的坑。

Logo

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

更多推荐