不想上班:用 HarmonyOS Dev Assistant 做折叠屏一多适配,我只确认了三次

本文基于应用「不想上班」——一款打工人自用工具箱(待办、工资计算、退休倒计时、打工人法务部、随手记、图片预览等)——在 HUAWEI Pura X Max / Mate XT 2 折叠屏上的一多适配实战,系统梳理 HarmonyOS Dev Assistant 插件的安装配置、一多适配原理、从范围确认到报告收口的五步闭环全流程,并结合插件源码拆解它的四层工作方式。

全程我只做了三次确认:说清范围、看图拍板、选验证方式。剩下的扫描、诊断、施工、报告,全部由插件自动完成。


一、HarmonyOS Dev Assistant:把一多适配变成对话

1.1 它是什么

HarmonyOS Dev Assistant(鸿蒙开发助手)是一款面向 HarmonyOS 应用/元服务开发者的 AI 插件,支持在 DevEco Studio、VS Code 等主流 IDE 中安装使用。它以自然语言对话为核心交互,把鸿蒙开发中几类高门槛任务收敛成「说清需求 → 生成方案 → 确认 → 落地」的对话式流程:

功能模块能力说明
一站式生成元服务通过文字描述需求,生成开箱即用的元服务工程和代码
小程序转换元服务微信/支付宝/taro 小程序转 ASCF 元服务;uni-app 小程序对话式转换
三方库鸿蒙化通过对话方式将非鸿蒙版本的三方库鸿蒙化
多设备适配「一次开发,多端部署」(简称"一多"):输入文字指令,插件为工程设计适配方案、生成适配代码并完成验证,输出适配报告

本文聚焦多设备适配。它不是一个问答机器人,而是一套「能力可编排、流程可闭环」的工程助手:对话面板之下,由若干可独立加载的领域 Skill、一条 devecocli 命令行工具链和一个 MCP 代码智能服务协作支撑(四层架构详见第四章)。

它的核心价值可以概括为三个词:

  • 一次开发:源码只写一份,形态差异通过「断点 + 网格」表达,而非为每种设备各写一套页面;
  • 过程可确认:范围、方案、高保真预览都在动手改代码之前由你拍板,改错方向的成本趋近于零;
  • 结果可追溯:每个改动点都有 Issue、有验证计划、有账本记录,能回答「改了什么、为什么改、验证到哪一步」。

1.2 安装与登录

安装与配置见之前的文章,或者HarmonyOS Dev Assistant 官方文档 。

二、一多适配原理:断点驱动,而不是型号驱动

2.1 断点的本质

传统「多设备适配」的误区是按设备型号写死判断(if (model === 'Mate XT'))。这既脆弱又无法覆盖新设备。HarmonyOS 的一多范式是按窗口断点(Breakpoint)做响应式:

  • 系统根据当前窗口宽度(不是物理屏幕尺寸)划分五档横向断点:xs / sm / md / lg / xl;
  • 同一台设备,折叠态走窄窗口档,展开态自动落到宽窗口档;
  • 代码只对「断点档位」做分支,从而天然覆盖折叠、平板、分屏、自由窗口等所有形态。

本次适配沉淀的统一断点资产 BreakpointSystem.ets 就是这个原理的标准落地:

// entry/src/main/ets/utils/BreakpointSystem.ets
export enum BreakpointTypeEnum {
  XS = 'xs',  // [0, 320)vp     — 超小窗口
  SM = 'sm',  // [320, 600)vp   — 直板机竖屏、折叠外屏
  MD = 'md',  // [600, 840)vp   — 折叠内屏展开、小平板竖屏
  LG = 'lg',  // [840, 1440)vp  — 平板横屏、三折展开
  XL = 'xl',  // [1440, +∞)vp   — 超宽窗口
}

断点的事实源不是自存的一份宽高,而是系统实时能力:

// entry/src/main/ets/utils/BreakpointSystem.ets(refresh() 内部)
globalBreakpointState.value = BreakpointSystem.fromSystemBreakpoint(
  uiContext.getWindowWidthBreakpoint()   // 系统断点,唯一事实源
);

同时监听两个变化事件,保证折叠/旋转/分屏时页面即时重排:

// entry/src/main/ets/utils/BreakpointSystem.ets(register() 内部)
mainWindow.on('windowSizeChange', BreakpointSystem.windowSizeChangeCallback);
if (canIUse('SystemCapability.Window.SessionManager')) {
  mainWindow.on('systemDensityChange', BreakpointSystem.systemDensityChangeCallback);
}

2.2 布局手段:12 列网格 + 居中限宽

拿到断点之后,布局改造并不需要推翻原有代码。ArkUI 的 GridRow / GridCol 提供了一套 12 列栅格语义:

  • 手机窄窗口:内容占满 12 列(span: 12);
  • 折叠展开 / 平板横屏:内容收窄到中间 8 列,左右各留 2 列留白(span: 8, offset: 2)。

这就是本次适配核心决策(D-001)确定的方案——展开态居中限宽:

对应到每个页面组件,只加一层 GridRow + GridCol 包裹即可,原有子内容原样保留:

// entry/src/main/ets/views/onboarding/WelcomeView.ets(引导视图,7 个视图同模板)
GridRow({
  breakpoints: {
    value: ['320vp', '600vp', '840vp', '1440vp'],
    reference: BreakpointsReference.WindowSize,
  },
  columns: { sm: 12, md: 12, lg: 12, xl: 12 },
}) {
  GridCol({ span: { xs: 12, sm: 12, md: 12, lg: 8 }, offset: { lg: 2 } }) {
    // ... 原有内容,逐字未动 ...
  }
}

2.3 数量型内容:断点增数,而不是收窄

对「数量型」内容(如图片预览页的底部缩略图条),宽屏下断点语义不是收窄而是增数——屏幕宽了,该多看几张,而不是把 8 张拉成胖图:

// entry/src/main/ets/pages/PicturePreviewPage.ets
@ComponentV2
export struct PicturePreviewPage {
  /** 断点状态(底部缩略图条数量按横向断点取值) */
  @Local bpState: BreakpointState = BreakpointSystem.state;

  /** 底部缩略图条显示数量:sm 8 / md 12 / lg 16 */
  private thumbCount(): number {
    return new BreakpointType<number>(8, 12, 16).getValue(this.bpState.value);
    //                                sm  md  lg  → 折叠外屏 8 / 内屏 12 / 展开 16
  }
}

BreakpointType 工具类还内置了档位向下回退语义(如 lg 未配时回退 md,再回退 sm),保证任意设备即使命中了未显式配置的档位,也永远能拿到一个合法值:

// entry/src/main/ets/utils/BreakpointSystem.ets
getValue(breakpoint: BreakpointTypeEnum): T {
  switch (breakpoint) {
    case BreakpointTypeEnum.XL:
      return this.xl ?? this.lg ?? this.md ?? this.sm;
    case BreakpointTypeEnum.LG:
      return this.lg ?? this.md ?? this.sm;
    case BreakpointTypeEnum.MD:
      return this.md ?? this.sm;
    case BreakpointTypeEnum.XS:
      return this.xs ?? this.sm;
    default:
      return this.sm;
  }
}

2.4 为什么这样改「稳定」

这套方案稳定,来自三个层面的约束:

  1. 单一事实源:全工程只有 BreakpointSystem.state 一个断点状态,所有页面消费同一状态,杜绝了「每页各自读一次 windowWidth、结果不一致」的隐患。本次适配的第一个 Issue(见 3.3)正是先修掉这个隐患,才让后续限宽有了可靠的地基。
  2. 幂等注册:register() 重复调用只刷新、不叠加监听,页面反复进出不会造成监听器泄漏。
  3. 状态由框架托管:断点状态用 @ObservedV2 + @Trace 声明,窗口变化 → 系统事件 → 刷新状态 → UI 自动重排,全程无手动 setState,减少人为时序错误。
// entry/src/main/ets/utils/BreakpointSystem.ets
@ObservedV2
export class BreakpointState {
  @Trace value: BreakpointTypeEnum = BreakpointTypeEnum.SM;
  @Trace vertical: VerticalBreakpointEnum = VerticalBreakpointEnum.LG;
  // ...
}

三、实战复盘:五步闭环

3.1 任务与范围

「不想上班」的页面大多是典型的窄屏单列布局。折叠屏展开态下,全宽内容会被横向拉伸——引导页的词球、工资演示卡、功能矩阵网格都会变得松散难看。所以本次适配的目标形态是折叠屏(foldable):展开态 lg + 外屏折叠态 sm。

适配范围与批次划分(由插件按页面依赖与风险自动完成):

批次页面领域风险Issue 数
B01首启页 FirstPage + 引导页 7 个子视图(Welcome / SalaryDemo / WordBall / CardEdit / FeatureGrid / QuickSetup)尺寸布局low8
B02图片预览页 PicturePreviewPage + ImageItemView + ThumbnailView尺寸布局low1

确认模式为 aggregate(聚合确认):一次性产出全部批次 SPEC 再统一确认,适合这种改动同构、风险可控的任务。

3.2 五步闭环总览

Dev Assistant 的一次完整一多适配遵循固定的五步闭环,每一步的产出物都落盘在工程根目录的 .onemulti/ 下,可随时审计:

步骤名称用户要做的助手自动做的产出物
1确认范围与批次计划指定页面/目录/模块、目标形态工程扫描、基线构建、路由表、风险分批route-map.json、批次计划
2逐批生成并确认 SPEC确认方案 / 选择高保真预览断点诊断、根因、改法、验证计划、高保真 HTMLdecisions.json(SPEC)、hifi-B*.html
3按已确认 Issue 施工无需操作按确认边界改代码、回写变更源码改动
4验证、修复、回写证据选择设备验证方式构建、静态检查、设备验证、证据归档evidence/
5生成报告与汇总确认是否继续下一批渲染批次报告、最终汇总adaptation-report-B*.html、汇总

在插件面板左下角把模式切换为「一多适配」,输入包含适配范围、适配项目与目标设备的提示语即可启动:

在这里插入图片描述

3.3 逐轮对话复盘

第 1 轮:提出诉求

我说:为当前项目的引导页和图片预览页进行Pure X Max和 Mate XT 2适配,实施前生成高保真让我确认。
在这里插入图片描述

Dev Assistant 做:

  1. 执行 devecocli build 记录适配前基线;
  2. 运行 project-scan.py 扫描候选页面与动态路由;
  3. 生成 output/route-map.json——这是一张可执行的验证路由表,记录从入口到目标页的有序步骤。本任务生成两条验证路由:R-B01-ONBOARDING(启动即达引导页,1 步)、R-B02-PICTURE-PREVIEW(启动 → 点「跳过」进主页 → 点「随手记」页签 → 点日志中的图片,4 步);
  4. 按依赖与风险划分 B01 / B02 两个批次。

产出:范围锁定,批次计划成型。

第 2 轮:确认方案(含高保真)

Dev Assistant 诊断出 9 个 Issue,其中有一个是「地基」问题:

B01-UI-001:工程原本没有统一断点基础设施,Index.windowWidth 是一次性取值、无尺寸监听,导致首启页拿不到断点、无法驱动 lg 限宽。

其余 8 个都是「内容区全宽、lg 下过度拉伸」的同类问题。给你看的是高保真 HTML(hifi-B01.html、hifi-B02.html),直观预览展开态/折叠态的布局效果:

在这里插入图片描述
在这里插入图片描述
在这里插入图片描述
我确认:通过高保真拍板,选定「展开态 lg 居中限宽(GridCol span8/offset2)+ 缩略图按断点增数,外屏折叠态沿用 sm 布局」。每个 Issue 携带现象、证据、根因、方案、计划文件与验证方法,确认后放行施工:

产出:决策 D-001 落账本,方案冻结。

第 3 轮:自动施工

这一轮我无需操作。Dev Assistant 按冻结的方案边界逐 Issue 改码,并实时回写变更状态。实际改动 9 处,可归纳为两类:

一类:地基(1 处)——新增 BreakpointSystem.ets 并在入口页注册:

// entry/src/main/ets/pages/FirstPage.ets(aboutToAppear 内)
// 注册断点系统(loadContent 入口页唯一注册点;断点全局存活,供后续页面消费)
try {
  const mainWindow = windowStage.getMainWindowSync();
  if (mainWindow) {
    BreakpointSystem.register(this.getUIContext(), mainWindow);
  }
} catch (e) {
  console.error(`FirstPage register breakpoint failed: ${JSON.stringify(e)}`);
}

一类:限宽(8 处)——引导页 7 个子视图 + 首启页底部按钮区统一加 GridCol 居中限宽(见 2.2 的模板代码),图片预览缩略图条按断点增数(见 2.3)。其中功能矩阵网格(FeatureGridView)保持 6 列不变,只做限宽——宽屏下把图标网格改成 8 列反而破坏节奏,这是方案确认阶段就定下的边界。

适配产生的代码改动会进入「待审批文件」栏,可逐个接纳或撤销:

第 4 轮:验证

Dev Assistant 做:构建(devecocli build)与静态检查,适配改动未引入编译回归。

我选择:设备端视觉验证由我自行完成。流程据此在账本中以 not_verified / multimodal_declined_by_user 显式记录,而非把「编译通过」冒充成「视觉验证通过」。

这不是流程「失败」,而是流程强制要求的结果诚实:把「编译通过」和「视觉验证通过」严格区分开,避免用前者冒充后者。每一次交付的可信边界都是清晰、可追溯的——适配后各形态的实机效果由我补验:

Mate XT 2上实际适配效果如下:
在这里插入图片描述在这里插入图片描述
在这里插入图片描述
Pura X Max 适配后:
在这里插入图片描述

不想上班

第 5 轮:报告与收尾

Dev Assistant 做:渲染 B01、B02 批次报告与最终汇总,归档证据索引。报告由脚本读账本与证据确定性生成,而不是让模型「写」一份报告:

python3 .onemulti/scripts/render-report.py .onemulti --batch-id B01
# 全部批次终态后
python3 .onemulti/scripts/render-report.py .onemulti --summary

在这里插入图片描述
在这里插入图片描述

至此,decisions.json 状态置为 completed,任务闭环。

3.4 9 个 Issue 全景

Issue组件问题修法
B01-UI-001BreakpointSystem(地基)工程无断点基础设施,windowWidth 一次性取值、无监听新增统一断点系统,入口页注册,全局存活
B01-UI-002首启页底部按钮区指示器 + 主按钮全宽,lg 下按钮过长GridCol span8/offset2 居中限宽
B01-UI-003欢迎内容区icon + 文案全宽,lg 下横向过度拉伸GridCol 居中限宽
B01-UI-004工资 demo 内容区demo 卡 + 冷知识卡全宽,lg 下过宽GridCol 居中限宽
B01-UI-005词球内容区词球 + 选中卡全宽,lg 下过宽GridCol 居中限宽
B01-UI-006卡片编辑演示区演示舞台全宽,lg 下过宽GridCol 居中限宽
B01-UI-007功能矩阵网格6 列网格全宽,lg 下图标间距过大GridCol 居中限宽,保持 6 列不变
B01-UI-008快速设置表单区预览卡 + 薪资卡 + 退休卡全宽,lg 下表单过宽GridCol 居中限宽
B02-UI-001底部缩略图条displayCount(8) 固定,lg 下单个缩略图被拉伸过宽按断点取值 sm 8 / md 12 / lg 16,V2 壳消费断点后传入子组件

四、拆开看:插件的四层工作方式

用完一整轮适配后,值得把插件「怎么工作」拆开看。HarmonyOS Dev Assistant 并不是一个大而全的黑盒,而是一个四层协作体——这一点可以直接从本地安装的插件目录(plugins/codegenie-plugin,含对话面板、代码智能与 UI 验证等模块)和 npm 包 @deveco/deveco-cli 的源码结构里得到印证。每层职责单一、边界清晰,靠明确的契约衔接:

┌─────────────────────────────────────────────────────┐
│ IDE 插件层    对话面板 / 模式切换 / 模型与路径配置 /   │
│              待审批文件管理(Diff 接纳或撤销)          │
├─────────────────────────────────────────────────────┤
│ Agent+Skill 层  领域 Skill 注入宿主 Agent:           │
│              deveco-cli / harmonyos-ui-multi /        │
│              harmonyos-camera-multi /                 │
│              harmonyos-workflow-multi                 │
├─────────────────────────────────────────────────────┤
│ CLI 执行层    devecocli:build / run / device /       │
│              emulator / ui / log / docs / auth /      │
│              signature / skills / serve …             │
├─────────────────────────────────────────────────────┤
│ MCP 服务层    deveco-mcp(devecocli serve mcp):     │
│              ArkTS/C++ 代码智能(诊断/符号/引用/层级) │
└─────────────────────────────────────────────────────┘
  • IDE 插件层是对话式编排入口:模式切换(一多适配等)、上下文与提示语输入、模型/DevEco Studio 路径配置,以及适配产物的「待审批文件」管理。
  • Agent+Skill 层按需加载领域知识。最有意思的设计是它的边界纪律——流程 Skill(harmonyos-workflow-multi,即安装到工程 .onemulti/ 的那份源码)在文档中明确写有「不可破坏的边界」:

不在 workflow 中复制领域根因、修法、API 矩阵或代码资产。
全流程中只由 workflow 管理 .onemulti、批次、用户确认、证据和报告。

流程只编排、修法来自领域、工具只执行。UI 断点怎么改是 harmonyos-ui-multi 的事,相机切镜是 harmonyos-camera-multi 的事,流程 Skill 只负责范围、批次、确认、证据和报告的编排。

  • CLI 执行层把 DevEco Studio 的构建、签名、模拟器工具链包装成稳定命令,是所有「动手」动作的唯一出口。
  • MCP 服务层把 IDE 级的代码智能暴露给任意 MCP 兼容的 Agent 宿主,提供 check(静态诊断)、references(符号引用)、callHierarchy(调用层级)等工具,在施工阶段做毫秒级的「改得对不对」自检;分钟级的 devecocli build 才是编译验证的最终口径。两者互补:MCP 管「改得对不对」,CLI 管「能不能编译成包」。

4.1 五个设计亮点

  1. 账本即唯一事实源:范围、批次、Issue、施工状态、验证结论全部收敛进 decisions.json,Issue 直接充当 SPEC——不存在「第二份文档」漂移问题。
  2. 高保真前置确认:先确认「改什么、怎么改、改完长什么样」,再动手。你只在一个认知负担最低的节点(看图)做决定,而不是在代码里猜。
  3. 证据与结论分离:evidence/ 只存客观证据(命令、截图、组件树),「验证是否通过」由证据判定,「流程是否完成」由步骤状态判定,两个维度互不污染。
  4. 确定性报告:报告由脚本读账本与证据生成,同一份账本永远得到同一份报告。
  5. 范围冻结与止损:流程 Skill 明确约束——只修有证据表明由本批修改引起的问题,每批最多 5 轮验证修复,「连续两轮无新增证据或根因进展时停止」,防止验证阶段无限扩散。

4.2 工程里留下了什么

任务完成后,.onemulti/ 下沉淀了一条完整证据链:

产物说明
decisions.json任务账本:范围、决策 D-001、两批次、9 个 Issue 的根因/方案/验证/变更
output/route-map.json验证路由表(引导页、图片预览两条验证路径)
output/html/hifi-B01.html、hifi-B02.html两批次高保真预览
adaptation-report-B01.html、adaptation-report-B02.html两批次报告
adaptation-summary.html最终汇总报告
evidence/验证证据索引

即便后续发现问题,也无需推倒重来:每个 Issue 都有独立的验证计划、变更文件、变更摘要,可以精确到「哪一行改动引入、如何复现、如何验收」,修复成本被锁定在最小范围。


五、总结

回看这次适配,作为使用方,我全程只做了三件事:

  1. 说清范围与形态(一句话);
  2. 看高保真、点确认(一次决策);
  3. 选验证方式(一次选择)。

剩下的大量动作——扫描、路由表、断点诊断、根因分析、SPEC 起草、改码、回写账本、构建、报告——全部由 Dev Assistant 自动完成。没有一处要求我手写断点判断、手改栅格、手算列宽。

以 9 个 Issue、2 个批次、1 次方案确认、1 次验证方式选择的极轻投入,「不想上班」的引导页与图片预览页完成了折叠屏展开态/折叠态的稳定适配:全工程只有一套断点事实源、一种限宽范式,8 个页面改动同构,后续新页面可套用同一模板。这套「统一资产复用」的思路,让适配改动是机械的、可预期的,不会越改越复杂。

也有仍需人工补位的地方:当前多设备适配不支持 2in1/PC;多模态验证的模型判读仍需人复核;而设备端的实机体验验证,这次也如实在账本里记了 not_verified——工具可以收敛 80% 的机械劳动,剩下 20% 的形态判断与体验取舍,依然属于理解业务的人。

对开发者而言,真正需要记住的只有一句:把「范围、方案、验证方式」定好,把「扫描、诊断、施工、报告」剩下的都交给 Dev Assistant。


Logo

讨论HarmonyOS开发技术,专注于API与组件、DevEco Studio、测试、元服务和应用上架分发等。

更多推荐