鸿蒙PC上的ArkUI跨平台开发实战:用ArkTS与Canvas构建Somafield声波显微台

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

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

前言

这是一份"在鸿蒙PC电脑上开发鸿蒙PC应用"的完整记录。Somafield(声波显微台)是一款只面向二合一/PC形态的鸿蒙PC应用,从工程清单、声明式布局、状态流到 Canvas 绘制,全部在鸿蒙PC本机完成,没有借助手机形态的缩放适配来凑效果。技术栈很纯粹:ArkUI 是鸿蒙生态的声明式 UI 框架,ArkTS 是它的开发语言;当我们谈 ArkUI 跨平台框架时,指的是同一套组件模型、状态机制与渲染管线覆盖手机、平板、二合一与鸿蒙PC 等多种设备形态,而不是把 ArkTS 代码直接编译出 Windows 或 iOS 版本。这个区别必须先讲清楚,否则后面所有关于"跨平台"的表述都会被误读。

数据边界同样要先交代。Somafield 不采集声卡输入,画面里的波形由本地谐波合成引擎按当前基频实时计算,音名走标准十二平均律换算,频谱能量按"低频抬升、高频衰减"的包络生成,节拍值每次由函数区间取值。所以它是一台观测声波形状的可视化工作台,不是录音软件,也不是专业声学分析仪。下文出现的绘制坐标、采样点数、刷新间隔全部来自工程实现,可以照着复现。

关键词:鸿蒙PC、ArkUI跨平台框架、ArkTS、Canvas绘制、OpenHarmony PC、桌面应用开发、声明式UI

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

图1:鸿蒙PC 上的开发现场。左侧是鸿蒙PC 本机的 DevEco Studio 工程树(Somafield_ohos),右侧悬浮着应用窗口,底部系统桌面 Dock 与顶部状态栏都在画面里,这是判断"确实跑在鸿蒙PC 上"最直接的证据。

一、工程骨架:先把设备形态写进清单文件

鸿蒙PC 应用与手机应用的第一处差别不在界面代码,而在工程清单。很多人写跨端项目时习惯先做页面、最后才补 deviceTypes,结果是在 PC 上装不上、或者装上了却带着手机视角的窄栏布局。Somafield 反过来:先定设备目标,再写第一行 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 里锁定了编译目标与模块化规则。compatibleSdkVersion 写的是三段式版本号 26.0.0,从 API 26 起这个字段不再接受整数;runtimeOS 指明运行底座;useNormalizedOHMUrl 打开规范化模块地址,配合多模块依赖时能避免路径解析歧义:

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

入口 Ability 做两件事:让主窗口进入全屏布局,再加载首页。鸿蒙PC 的窗口默认带系统装饰(标题栏、关闭按钮),对一台"观测仪器"来说这些装饰会挤占宝贵的纵向空间,所以这里主动去掉:

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, 'Somafield', 'Somafield 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, 'Somafield', 'load fail %{public}s', JSON.stringify(err));
      }
    });
  }
}

注意 getMainWindow() 与 setWindowLayoutFullScreen() 都返回 Promise,这里做了双层 catch 兜底:窗口相关能力在不同设备与不同系统版本上可用的范围并不一致,失败时不应该让首页加载被拖住。真正做产品时,如果希望用户能同时开两个 Somafield 窗口对比不同频段,就不该无脑全屏,而应保留系统标题栏并自行管理窗口控制按钮——这是鸿蒙PC 场景里必须提前决策的一件事,补做代价很高。

二、ArkUI 声明式布局:宽屏上的三段式信息结构

鸿蒙PC 的可用宽度通常是手机的两倍以上,信息密度却受限于人眼在桌面距离下的可读性。Somafield 的取舍是:纵向一条主流程,底部一分为二。页面骨架只有五行:

build() {
  Scroll() {
    Column({ space: 22 }) {
      this.topBar()      // 品牌、音名、信号状态
      this.hero()        // 主题句
      this.transport()   // 播放控制、基频滑杆、预设音
      this.waveCard()    // 时域波形
      Row({ space: 24 }) {
        this.meterCard() // 响度电平、BPM、主音
        this.specCard()  // 48 频段能量柱
      }
      .width('100%')
    }
    .width('100%')
    .padding({ left: 28, right: 28, top: 6, bottom: 40 })
  }
  .scrollable(ScrollDirection.Vertical)
  .scrollBar(BarState.Off)
  .width('100%').height('100%')
  .backgroundColor(S.BG)
}

ArkUI 的线性布局没有 Web 那套百分比栅格,宽屏适配靠三种手段混合:Row 里的 Blank() 当弹簧,把标题推到左边、状态推到右边;layoutWeight(1) 做等比切分;padding 与 space 控制留白节奏。底部那一行两列各自 layoutWeight(1),所以窗口变宽时它们会同步变宽,而不是固定宽度挤在左边。Scroll 承担纵向溢出,scrollBar(BarState.Off) 隐藏滚动条——桌面端滚动条常驻会破坏卡片之间的呼吸感。

最值得单独说的一段是 transport()。它一行里塞了三块:渐变主按钮、可伸缩的基频滑杆、四颗预设音按钮。滑杆用 layoutWeight(1) 吃掉剩余空间,按钮固定宽高,预设组固定内边距:

@Builder
transport() {
  Row({ space: 24 }) {
    Button() {
      Row({ space: 10 }) {
        Text(this.running ? '暂停' : '播放')
          .fontSize(20).fontWeight(FontWeight.Medium).fontColor('#07131A')
        Text(this.running ? '■' : '▶').fontSize(20).fontColor('#07131A')
      }
    }
    .width(160).height(54).borderRadius(27)
    .linearGradient({ colors: [[S.CYAN, 0], [S.VIOLET, 1]] })
    .shadow({ radius: 18, color: 'rgba(34,230,200,0.3)' })
    .onClick(() => { this.running = !this.running; })

    Column({ space: 6 }) {
      Text(`基频 ${Math.round(this.freq)} Hz · ${this.note}`)
        .fontSize(16).fontColor(S.SUB)
      Slider({ value: this.freq, min: 40, max: 1000, style: SliderStyle.OutSet })
        .width('100%').selectedColor(S.VIOLET).trackThickness(8)
        .onChange((v: number, md: SliderChangeMode) => {
          this.freq = v;
          this.note = AudioSim.noteName(v);
        })
    }
    .layoutWeight(1)

    Row({ space: 10 }) {
      ForEach(this.PRESET, (p: FreqPreset, idx: number) => {
        Text(p.label)
          .fontSize(16)
          .fontColor(Math.abs(this.freq - p.freq) < 5 ? '#07131A' : S.SUB)
          .padding({ left: 18, right: 18, top: 9, bottom: 9 })
          .linearGradient({
            colors: Math.abs(this.freq - p.freq) < 5
              ? [[S.CYAN, 0], [S.VIOLET, 1]]
              : [['rgba(255,255,255,0.04)', 0], ['rgba(255,255,255,0.04)', 1]]
          })
          .borderRadius(18)
          .onClick(() => { this.freq = p.freq; this.note = AudioSim.noteName(p.freq); })
      }, (p: FreqPreset, idx: number) => `${idx}_${p.label}`)
    }
  }
  .width('100%')
}

这里有三个在鸿蒙PC 上很实用的细节。第一,Button() 用无参构造 + 子组件的形式,才能在里面放 Row 组合文字与符号,单纯的 Button('文本') 无法做这种排版。第二,预设按钮的选中态是"基频落在预设值的 ±5 Hz 内",而不是记录一个选中索引——这样从滑杆拖到 261 Hz 时 C4 会自动亮起,状态只有一个来源,不会有滑杆与按钮不一致的情况。第三,.linearGradient() 的 colors 是二维数组,每项 [颜色, 位置],位置必须显式给 0 和 1,省略会得不到预期的渐变。

主题色统一收在 Theme.ets 里,用静态只读字段而不是枚举:

export class S {
  static readonly BG: string = '#0B0F1F';
  static readonly SURFACE: string = '#11172C';
  static readonly LINE: string = 'rgba(124,108,255,0.16)';
  static readonly TEXT: string = '#EEF2FF';
  static readonly SUB: string = '#9AA4CF';
  static readonly DIM: string = '#5D6789';
  static readonly CYAN: string = '#22E6C8';
  static readonly VIOLET: string = '#7C6CFF';
  static readonly PINK: string = '#FF5C8A';
}

深色底 + 青紫双色高亮是这类观测工具常见的视觉语言:暗背景降低暗部噪声感,青紫对比在小面积数据元素上更容易分辨。把它抽成一个类,好处是后面调色只改一处,卡片、文字、柱状条不会各自为政。

三、状态流:@State 到 @Prop 再到 @Watch 的三级传递

ArkUI 的数据驱动不是"改数据自动找控件",而是"声明依赖关系,框架负责重算最小子树"。Somafield 的依赖链只有三级:页面持有 @State,子组件用 @Prop 接收快照,再用 @Watch 挂一个重绘回调。页面侧几乎所有状态都集中在这几个字段上:

@Entry
@Component
struct Index {
  @State running: boolean = true;
  @State freq: number = 220;
  @State phase: number = 0;
  @State tick: number = 0;
  @State wave: number[] = [];
  @State bands: number[] = [];
  @State volume: number = 0.5;
  @State bpm: number = 96;
  @State note: string = '-';

  private timer: number = -1;
  private bpmChange: number = 0;

  aboutToAppear(): void {
    this.wave = AudioSim.wave(this.freq, 0);
    this.bands = AudioSim.bands(this.freq);
    this.note = AudioSim.noteName(this.freq);
    this.timer = setInterval(() => {
      if (!this.running) { return; }
      this.phase += 0.05;
      this.wave = AudioSim.wave(this.freq, this.phase);
      this.bands = AudioSim.bands(this.freq);
      this.volume = AudioSim.volume(this.freq);
      this.tick += 1;
      this.bpmChange += 1;
      if (this.bpmChange % 10 === 0) { this.bpm = AudioSim.bpm(); }
    }, 66);
  }

  aboutToDisappear(): void {
    if (this.timer !== -1) { clearInterval(this.timer); }
  }
}

第一处必须讲透的坑是数组赋值方式。@Prop 对数组做的是浅拷贝下发,框架判断"变了没有"看的是引用,不是内容。所以 this.wave = AudioSim.wave(...) 每次返回一个全新数组是对的;如果图省事写成 this.wave.push(x) 或 this.wave[i] = y,引用没变,子组件的 @Watch 不会触发,画布就停在前一帧。这是 Canvas 类组件在鸿蒙PC 上最常见的"画面不动"原因。

第二处是定时器与生命周期的绑定。setInterval 返回的句柄必须存下来,在 aboutToDisappear() 里清理;鸿蒙PC 上应用窗口可以被最小化、被切到后台但不销毁,如果只在不可见时停表、可见时恢复,就还要额外监听窗口可见性事件。当前实现选择"暂停按钮即停表",靠 running 一个布尔量短路回调,逻辑更简单,也不会在切后台时继续吃 CPU——回调里第一行就 return 了,代价接近零。

子组件的接收端是这样写的:

@Component
export struct WaveCanvas {
  @Prop @Watch('onTick') data: number[] = [];
  @Prop phase: number = 0;
  @Prop tick: number = 0;
  private ctx: CanvasRenderingContext2D = new CanvasRenderingContext2D(new RenderingContextSettings(true));

  onTick(): void {
    if (this.ctx) {
      this.ctx.clearRect(0, 0, W, H);
      this.draw();
    }
  }
}

new RenderingContextSettings(true) 打开抗锯齿,看不到锯齿的曲线在暗底上才不会显得脏。clearRect 这一行不能省:ArkUI 的 Canvas 不是每帧重建的位图容器,不清屏就是反复叠画,几秒后会糊成一片亮斑。@Watch 挂的是方法名(字符串),不是函数引用,这是 ArkTS 的语法约束,写错不会报错、只会静默不触发,排查时容易走弯路。

四、Canvas 时域波形:三层绘制与坐标映射

波形区域是一块 920×260 的画布,绘制分三层:中线网格、面积渐变填充、波线与扫描游标。核心是先把 240 个采样值映射到画布纵坐标,再按顺序连线:

const W = 920;
const H = 260;

private draw(): void {
  const ctx = this.ctx;
  const d = this.data;
  const mid = H / 2;
  const pad = 14;
  if (!d || d.length < 2) { return; }
  const n = d.length;
  const stepX = (W - pad * 2) / (n - 1);
  const yOf = (v: number) => mid - v * (mid - pad);

  ctx.strokeStyle = 'rgba(124,108,255,0.12)';
  ctx.lineWidth = 1;
  ctx.beginPath();
  ctx.moveTo(0, mid); ctx.lineTo(W, mid);
  for (let i = 1; i < 6; i++) {
    const y = (mid / 6) * i;
    ctx.moveTo(0, y); ctx.lineTo(W, y);
    ctx.moveTo(0, H - y); ctx.lineTo(W, H - y);
  }
  ctx.stroke();

  const grad = ctx.createLinearGradient(0, mid, 0, H);
  grad.addColorStop(0, 'rgba(34,230,200,0.30)');
  grad.addColorStop(1, 'rgba(34,230,200,0)');
  ctx.fillStyle = grad;
  ctx.beginPath();
  ctx.moveTo(pad, mid);
  for (let i = 0; i < n; i++) { ctx.lineTo(pad + i * stepX, yOf(d[i])); }
  ctx.lineTo(pad + (n - 1) * stepX, mid);
  ctx.closePath();
  ctx.fill();

  ctx.strokeStyle = '#22E6C8';
  ctx.lineWidth = 3;
  ctx.lineCap = 'round';
  ctx.lineJoin = 'round';
  ctx.beginPath();
  for (let i = 0; i < n; i++) {
    const x = pad + i * stepX;
    const y = yOf(d[i]);
    if (i === 0) { ctx.moveTo(x, y); } else { ctx.lineTo(x, y); }
  }
  ctx.stroke();

  const curX = pad + ((this.phase - Math.floor(this.phase)) % 1) * (W - pad * 2);
  ctx.strokeStyle = 'rgba(124,108,255,0.8)';
  ctx.lineWidth = 2;
  ctx.beginPath();
  ctx.moveTo(curX, 6); ctx.lineTo(curX, H - 6);
  ctx.stroke();
}

坐标映射的关键是 yOf:样本值域大致在 ±0.9 之间,画布纵轴向下为正,所以用 mid - v * (mid - pad) 把正值抬到上半、负值压到下半,同时留出 pad 的边距避免波峰贴边被裁。横向步长由样本数决定,n - 1 保证首尾点正好落在 pad 与 W - pad 上,不会出现最后一小段空白。

面积填充用了闭合路径技巧:从图像中线起笔,沿所有数据点连线,再落回中线并 closePath(),然后一次性 fill()。这样填充的只是"曲线与中线之间"的部分,正半周填在中线上方、负半周填在中线下方,视觉上就像示波器的双极性显示。渐变方向是从中线向下,所以下方比上方更透明——它暗示了"这里是负半周",而不是单纯装饰。

扫描游标单独一支竖线,位置由 phase 的小数部分决定。phase 每帧加 0.05,取小数部分后正好在 0 到 1 之间循环,游标就匀速从左扫到右。这里刻意用 ((x - Math.floor(x)) % 1) 而不是直接用 x % 1:后者对负数会返回负值,一旦以后允许相位回绕就会出现游标跳出画布的情况。

一个必须承认的边界:画布宽高是常量 920×260,而外层卡片内宽由窗口宽度决定。Column 默认把子组件水平居中,所以窗口够宽时画布居中、两侧对称留白;一旦窗口被拖窄到卡片内宽小于 920,画布是以居中方式溢出的,两侧都会各被裁掉一截,而不是只裁右边。更稳妥的做法是用 onAreaChange 拿到容器实际尺寸,把 W、H 改成组件字段,并在尺寸变化时重绘。这一步在鸿蒙PC 上尤其重要,因为用户随时可以拖拽改变窗口宽度——固定画布在手机上不明显,在桌面上是用户第一眼就会碰到的问题。

五、谐波合成与十二平均律音名

波形不是随机噪声,而是三次谐波叠加的结果。基频决定波形疏密,相位决定横向平移,每 7 个采样点做一次小幅扰动,让曲线看起来有真实的毛刺感:

export class AudioSim {
  private static readonly N = 240;
  private static readonly BANDS = 48;

  private static sample(freq: number, phase: number, i: number): number {
    const t = phase + (i / AudioSim.N) * 2;
    const f = freq / 120;
    let v = 0.55 * Math.sin(2 * Math.PI * f * t)
      + 0.25 * Math.sin(2 * Math.PI * f * 2 * t + 0.6)
      + 0.12 * Math.sin(2 * Math.PI * f * 3 * t + 1.2);
    if (i % 7 === 0) { v += (Math.random() - 0.5) * 0.12; }
    return v;
  }

  static wave(freq: number, phase: number): number[] {
    const out: number[] = [];
    for (let i = 0; i < AudioSim.N; i++) {
      out.push(AudioSim.sample(freq, phase, i));
    }
    return out;
  }
}

三次谐波的系数是 0.55、0.25、0.12,能量按 1、1/2、1/4 递减,这是接近锯齿波的谐波衰减规律;二次与三次谐波各带一个固定相位偏移(0.6 与 1.2 弧度),让波峰不对称,避免画出一条过于"教科书"的对称曲线。f = freq / 120 是频率归一化:分母取 120 而不是采样率,是为了让 40 到 1000 Hz 的整个滑杆区间在画布上都能呈现 1 到 8 个完整周期,既不会密到看不清,也不会稀到只有半个波。如果直接按 1:1 映射,1000 Hz 在 240 个点上会产生 2000 个周期,画面立刻变成一块实心色块——这是可视化里典型的"没有做视觉归一化"的翻车点。

音名换算是标准十二平均律,用 MIDI 音高编号反解:

static noteName(freq: number): string {
  const names = ['C', 'C#', 'D', 'D#', 'E', 'F', 'F#', 'G', 'G#', 'A', 'A#', 'B'];
  const idx = Math.round(12 * Math.log2(freq / 440) + 69);
  const n = names[((idx % 12) + 12) % 12];
  const oct = Math.floor(idx / 12) - 1;
  return `${n}${oct}`;
}

static bpm(): number {
  return 60 + Math.floor(Math.random() * 80);
}

440 Hz 代入得到 idx = 69,69 % 12 = 9,取到 A;Math.floor(69 / 12) - 1 = 4,输出 A4。滑到 261.6 Hz 附近时得到 C4,这正是截图里预设按钮和顶栏音名同步变化的原因。((idx % 12) + 12) % 12 的二次取模是为了兜住低于 8.18 Hz 的极端输入——JS 的 % 对负数返回负值,直接拿去索引数组会得到 undefined,界面上就会出现空音名。这种一行防御在 ArkTS 里同样必要,它的数值语义与 TS 一致。

频谱能量走另一条路径,48 个频段各取一个 0.04 到 1 之间的值,包络随频段号线性衰减,并在低频区随基频抬升:

static bands(freq: number): number[] {
  const out: number[] = [];
  for (let i = 0; i < AudioSim.BANDS; i++) {
    const t = i / AudioSim.BANDS;
    const env = (1 - t) * 0.9 + 0.1;
    let e = env * (0.45 + 0.55 * Math.random());
    if (t < 0.25) { e += ((freq - 40) / 900) * 0.3; }
    out.push(Math.max(0.04, Math.min(1, e)));
  }
  return out;
}

Math.max(0.04, Math.min(1, e)) 做上下钳制,保证每根柱子至少有 4% 高度——否则低能量频段会缩成一条 6 像素的圆角块,看起来像渲染失败;同时上限锁在 1,防止"低频抬升"把前几个频段顶出容器。这种"视觉下限"在仪表类界面里几乎是必需品。

六、频谱柱与 ForEach 键:一个容易踩的渲染坑

48 根柱子用 ForEach 渲染,柱高由数据直接决定,颜色按三档能量切换:

@Component
export struct SpecBars {
  @Prop @Watch('onTick') data: number[] = [];
  @Prop tick: number = 0;

  onTick(): void {}

  private barColor(e: number): string {
    if (e > 0.72) { return '#FF5C8A'; }
    if (e > 0.45) { return '#7C6CFF'; }
    return '#22E6C8';
  }

  build() {
    Row({ space: 5 }) {
      ForEach(this.data, (e: number, idx: number) => {
        Column() {
          Blank()
          Row()
            .width(12)
            .height((e * 190) + 6)
            .borderRadius(6)
            .linearGradient({ colors: [['#22E6C8', 0], [this.barColor(e), 1]] })
        }
        .width(16).height(220).justifyContent(FlexAlign.End)
        .alignItems(HorizontalAlign.Center)
      }, (e: number, idx: number) => `${idx}_${e.toFixed(3)}`)
    }
    .width('100%').height(220)
    .justifyContent(FlexAlign.Center)
    .alignItems(VerticalAlign.Bottom)
  }
}

注意 onTick() 是空实现。这不是遗漏:柱子的视觉完全由数据与键决定,ForEach 的差异比对已经把"高变了"这件事处理掉了,再在 onTick 里做一次重绘反而是重复劳动。与之相对,WaveCanvas 必须在 onTick 里重绘,因为 Canvas 是一块位图,ArkUI 无法从数据推出该画哪条线。这是同一个页面里两种完全不同的更新机制,混用会既慢又不准。

键函数 `${idx}_${e.toFixed(3)}` 里的 e.toFixed(3) 是三份实现里最关键的一处。如果只用索引 idx 作键,ForEach 认为"第 3 项还是第 3 项",就不会重建那一根柱子,柱高永远停在首帧。把数值打进键,值变了键就变了,框架才会重建对应项。toFixed(3) 而不是直接拼浮点数,是为了把键的长度控制在稳定范围内,同时避免 0.1 + 0.2 这类尾数噪声让键无谓抖动。

柱子容器的写法也值得一说:外层 Column 高 220、justifyContent(FlexAlign.End),内层用一个 Blank() 把柱体顶到底部,柱体自身只声明高度。这样柱子从底部长上来,而不是从顶部掉下去,符合频谱仪的心理模型。

这里有一处我在截图里发现的真实问题,正好拿来说明"鸿蒙PC 上宽屏不等于够宽"。每根柱子占 16 vp、间距 5 vp,48 根的水平总需求是 48 × 16 + 47 × 5 = 1003 vp。而这块卡片只占底部一行的一半——窗口宽 1080 左右时,减去两侧 28 的页面边距与 24 的行间距、再减去卡片 26×2 的内边距,可用宽度远小于 1003。结果是 Row 的 width('100%') 被撑开后,右侧的十几根柱子直接被卡片边界裁掉,图2 到图4 中右侧柱子贴着窗口边缘断掉,就是这件事的现场证据。

修法有三条,按代价从低到高:一是把柱宽改成 layoutWeight(1),让 48 根柱子平分容器,柱宽随窗口变化,间距由 space 控制;二是保留固定柱宽,但把柱数改成按容器宽度动态计算(宽度除以 21,取整后封顶 48);三是把频谱区改成可横向滚动的容器,牺牲"一眼看全"。第一条最省事,也最符合 ArkUI 的布局思路——只要一个元素能由父容器分配尺寸,就不要给它写死宽度。我保留了当前的硬编码,是因为它把"宽度预算"这个问题暴露在了截图里,比藏起来更有讨论价值。

七、帧预算:定时器为什么是 66 毫秒而不是 16 毫秒

这是全文最容易被质疑、也最该讲清楚的一个决定。60 帧的帧间隔是 16.7 ms,而这里用的是 66 ms,大约 15 帧。原因不是性能不够,而是这个界面的"信息更新率"本来就不需要 60 Hz:一台频谱仪的读数每秒刷新十几次,人眼已经读不出滞后,反而是每秒 60 次跳动会让数字看不清、看着累。

单次 tick 的计算量可以估出来:240 个采样点,每点 3 次 Math.sin,合计 720 次三角函数;再加 48 个频段的随机包络;最后是一次完整画布重绘,包含 240 次 lineTo、一次 fill、两次 stroke。三角函数的开销远高于画线,所以真正的成本集中在数据生成而不是绘制。把间隔从 66 ms 提到 16 ms,等于把这套计算量乘以 4,换来的是用户根本感知不到的流畅度。

这里还有一个诚实的取舍:setInterval 与屏幕刷新并不同步,绘制节奏和 vsync 不对齐。ArkUI 提供了与刷新率同步的帧回调能力(每帧触发一次,适合做逐帧动画),用它可以得到更均匀的推进;但那样波形推进速度会随设备刷新率变化——同一份代码在 60 Hz 与 120 Hz 的鸿蒙PC 上扫过的周期数会翻倍。对一个"观测工具"来说,稳定的时间基准比极致顺滑更重要,所以我选了固定间隔。

如果以后要做真正的实时分析(比如接麦克风),这个结构必须改:数据生成应该放进 TaskPool 或 Worker,主线程只负责把算好的数组画出来。ArkTS 的并发模型对跨线程数据有序列化约束,number[] 这类纯数据结构正好适合传过去,把计算挪走之后主线程的帧预算就能回到 16 ms 以内,也不会有"拖动滑杆时界面卡一下"的观感。当前实现把计算留在主线程,是因为 240 点这个量级确实撑得住;什么时候该拆,取决于采样点数而不是代码洁癖。

另外,if (!this.running) { return; } 这一行让暂停变得真正省电:定时器还在跑,但每 66 ms 只是判断一个布尔量。相比 clearInterval 再重建,这种写法避免了重复注册带来的句柄泄漏风险——尤其在鸿蒙PC 上用户反复点暂停/播放时,句柄管理出错是最难复现的一类问题。

八、鸿蒙PC 适配清单:从清单文件到绘制坐标

把这一路的经验收拢成一份可执行的检查清单,按从大到小的顺序:

首先是清单层。deviceTypes: ['2in1'] 决定了应用出现在哪类设备的安装通道里,也决定了系统会按 PC 形态给它分配窗口与输入方式。compatibleSdkVersion 用三段式字符串,runtimeOS 与 useNormalizedOHMUrl 跟目标底座和模块解析规则绑定,这三项配错往往表现为"能编译、装不上"或"装上了、页面全白"。

其次是布局层。ArkUI 的长度单位默认是 vp,它按屏幕密度换算,保证在不同鸿蒙PC 上视觉尺寸一致。所有间距、圆角、字号都应该用 vp 语义的数字表达,不要按物理像素去想。宽屏适配优先用 layoutWeight 与 Blank(),少用 position 绝对定位——绝对定位在窗口宽度变化时会立刻露馅。

第三是绘制层。Canvas 的绘制坐标与组件尺寸共用同一套 vp 单位,所以 920×260 的常量在缩放比例不同的设备上视觉尺寸是稳定的;但"稳定"不等于"自适应",容器变窄时它照样会被裁。判断标准很简单:把窗口从最大拖到最小,看有没有元素被切掉、有没有文字重叠。

第四是交互层。桌面端主输入是鼠标,点击热区建议不小于 32 vp,滑杆的拖动把手要有可见的悬停反馈。鸿蒙PC 用户习惯连续微调,滑杆的 onChange 每帧都回调,所以回调里只能做轻量计算——本项目里就是一次除法与一次对数,代价可以忽略;如果要在 onChange 里重算整块频谱,就必须加节流。

第五是生命周期。aboutToDisappear() 里清理定时器、解绑监听;窗格被关闭、页面被替换时都会走到这里。遗漏这一步的表现是后台 CPU 占用持续偏高,在笔记本形态的鸿蒙PC 上直接反映为续航下降。

最后是验证方式。不要只在预览器里看,预览器不代表真实的窗口管理与输入行为;也不要用手机截图充当桌面证据。图1 那种同时露出系统桌面、Dock 与应用窗口的截图,才是能证明"跑在鸿蒙PC 上"的证据。

九、ArkUI 跨平台框架的边界要讲准确

写鸿蒙PC 技术文章最容易滑向两个极端:一边是把 ArkUI 说成"一套代码跑遍全平台",另一边是只谈这一台机器上的界面效果、不谈框架定位。准确的说法介于两者之间——ArkUI 跨平台框架提供的是统一的声明式 UI 抽象与组件模型,同一套 ArkTS 组件可以面向手机、平板、二合一与鸿蒙PC 构建,设备差异通过工程清单、布局断点与能力查询来消化;但它不承诺把鸿蒙PC 应用原样搬到 Windows 或 iOS 上运行。本项目里能看到这条边界的两个痕迹:deviceTypes: ['2in1'] 是清单级别的设备收窄,layoutWeight 与 Blank() 是布局级别的自适应手段,两者都属于"在一个平台生态内跨设备形态",而不是"跨操作系统"。

把这条边界讲清楚,对使用 ArkUI 跨平台框架做桌面应用的团队反而有利:它意味着性能模型、渲染管线、状态机制都是同一套,你不需要为鸿蒙PC 单独维护一份渲染层;需要投入的地方集中在窗口尺寸、输入方式与信息密度这些产品层面的判断上。Somafield 之所以敢只用一个 Index 页面和两个自定义组件就撑起整个鸿蒙PC 界面,正是因为 ArkUI 跨平台框架把控件、布局、动画与 Canvas 能力都收敛到了同一套 API 里,跨平台框架的价值在这里体现为"不用重学",而不是"到处都能跑"。

十、运行截图与总结

下面三张来自同一台鸿蒙PC,分别对应三个状态,可以对照着看状态是如何驱动的。

Somafield鸿蒙PC运行界面:示波器、响度电平与48频段频谱

图2:基频 220 Hz,音名落到 A3,主按钮显示"暂停"即处于运行态。示波器显示三个完整周期,响度电平 84%,节拍 78 BPM。频谱柱呈典型的低频抬升、高频衰减包络,能量超过 0.72 的频段被染成粉色。

Somafield在鸿蒙PC上切换到155Hz时的界面

图3:基频拖到 155 Hz,音名自动落到 D#3,波形周期数减少、波峰变宽,频谱整体重心左移。注意按钮文字变成了"播放"——此时处于暂停态,所有数值停在最后一帧,不再变化。

Somafield在鸿蒙PC上以440Hz运行并处于暂停状态

图4:右上角信号灯转为灰色并显示"已暂停",顶栏音名与 A4 预设按钮同步高亮。这一刻能量最集中:基频 440 Hz 对应标准音 A4,波形在一个可视区间内只走两三个周期,曲线最舒展。

四张截图放在一起,其实已经把整个数据流走了一遍:滑杆改的是 freq,freq 同时驱动三处——音名换算、波形生成、频谱包络;点击主按钮改的是 running,它只短路定时器回调,不重置任何数据;预设按钮则是"写入 freq + 立刻重算音名"的复合动作。三个入口、一个状态源,没有冗余的中间状态,这也是为什么截图里的顶栏音名、滑杆下方文字、按钮高亮三者永远一致。

Somafield 这个项目要证明的事情很朴素:在鸿蒙PC 电脑上,用 ArkUI 这套声明式框架可以完整地做一个桌面形态应用——清单层锁设备形态,布局层用线性布局吃满宽屏,状态层靠 @State/@Prop/@Watch 传递,绘制层交给 Canvas 做自定义图形,最后用定时器给一个可控的刷新节奏。它没有用任何第三方 UI 库,没有一行 Web 技术,全部是 ArkTS 与 ArkUI 组件。

必须承认的不足同样清楚:画布尺寸是常量,窗口缩到很窄时会被裁;波形来自本地谐波合成而非真实采集;频谱包络是规则生成而非 FFT 结果;节拍值只是区间随机。这些不是掩饰,而是这个工具当前的定位——它是一台"看得见形状"的观测台,而不是分析仪。若要往下走,优先级应该是:先把画布改成跟随容器尺寸,再把数据生成挪进并发线程,最后才是接真实音频源并做 FFT。顺序不能反,因为前两步决定这个鸿蒙PC 应用在任意窗口尺寸和任意负载下是否还站得住,而真实数据只是换一个输入源而已。

对一个刚接触鸿蒙PC 开发的团队来说,ArkUI 跨平台框架最大的价值也在这里:你不需要为桌面形态重学一套渲染栈,需要重学的是"宽屏怎么组织信息"“鼠标怎么调参数”"窗口被拖拽时布局怎么不塌"这些工程判断。前者是框架给的,后者是项目练出来的——Somafield 就是后者的一次练习。

Logo

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

更多推荐