【共创稿事节】不想上班:用 HarmonyOS Dev Assistant 做折叠屏一多适配,只需要三句话
不想上班:用 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 为什么这样改「稳定」
这套方案稳定,来自三个层面的约束:
- 单一事实源:全工程只有
BreakpointSystem.state一个断点状态,所有页面消费同一状态,杜绝了「每页各自读一次 windowWidth、结果不一致」的隐患。本次适配的第一个 Issue(见 3.3)正是先修掉这个隐患,才让后续限宽有了可靠的地基。 - 幂等注册:
register()重复调用只刷新、不叠加监听,页面反复进出不会造成监听器泄漏。 - 状态由框架托管:断点状态用
@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) | 尺寸布局 | low | 8 |
| B02 | 图片预览页 PicturePreviewPage + ImageItemView + ThumbnailView | 尺寸布局 | low | 1 |
确认模式为 aggregate(聚合确认):一次性产出全部批次 SPEC 再统一确认,适合这种改动同构、风险可控的任务。
3.2 五步闭环总览
Dev Assistant 的一次完整一多适配遵循固定的五步闭环,每一步的产出物都落盘在工程根目录的 .onemulti/ 下,可随时审计:
| 步骤 | 名称 | 用户要做的 | 助手自动做的 | 产出物 |
|---|---|---|---|---|
| 1 | 确认范围与批次计划 | 指定页面/目录/模块、目标形态 | 工程扫描、基线构建、路由表、风险分批 | route-map.json、批次计划 |
| 2 | 逐批生成并确认 SPEC | 确认方案 / 选择高保真预览 | 断点诊断、根因、改法、验证计划、高保真 HTML | decisions.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 做:
- 执行
devecocli build记录适配前基线; - 运行
project-scan.py扫描候选页面与动态路由; - 生成
output/route-map.json——这是一张可执行的验证路由表,记录从入口到目标页的有序步骤。本任务生成两条验证路由:R-B01-ONBOARDING(启动即达引导页,1 步)、R-B02-PICTURE-PREVIEW(启动 → 点「跳过」进主页 → 点「随手记」页签 → 点日志中的图片,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-001 | BreakpointSystem(地基) | 工程无断点基础设施,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 五个设计亮点
- 账本即唯一事实源:范围、批次、Issue、施工状态、验证结论全部收敛进
decisions.json,Issue 直接充当 SPEC——不存在「第二份文档」漂移问题。 - 高保真前置确认:先确认「改什么、怎么改、改完长什么样」,再动手。你只在一个认知负担最低的节点(看图)做决定,而不是在代码里猜。
- 证据与结论分离:
evidence/只存客观证据(命令、截图、组件树),「验证是否通过」由证据判定,「流程是否完成」由步骤状态判定,两个维度互不污染。 - 确定性报告:报告由脚本读账本与证据生成,同一份账本永远得到同一份报告。
- 范围冻结与止损:流程 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 都有独立的验证计划、变更文件、变更摘要,可以精确到「哪一行改动引入、如何复现、如何验收」,修复成本被锁定在最小范围。
五、总结
回看这次适配,作为使用方,我全程只做了三件事:
- 说清范围与形态(一句话);
- 看高保真、点确认(一次决策);
- 选验证方式(一次选择)。
剩下的大量动作——扫描、路由表、断点诊断、根因分析、SPEC 起草、改码、回写账本、构建、报告——全部由 Dev Assistant 自动完成。没有一处要求我手写断点判断、手改栅格、手算列宽。
以 9 个 Issue、2 个批次、1 次方案确认、1 次验证方式选择的极轻投入,「不想上班」的引导页与图片预览页完成了折叠屏展开态/折叠态的稳定适配:全工程只有一套断点事实源、一种限宽范式,8 个页面改动同构,后续新页面可套用同一模板。这套「统一资产复用」的思路,让适配改动是机械的、可预期的,不会越改越复杂。
也有仍需人工补位的地方:当前多设备适配不支持 2in1/PC;多模态验证的模型判读仍需人复核;而设备端的实机体验验证,这次也如实在账本里记了 not_verified——工具可以收敛 80% 的机械劳动,剩下 20% 的形态判断与体验取舍,依然属于理解业务的人。
对开发者而言,真正需要记住的只有一句:把「范围、方案、验证方式」定好,把「扫描、诊断、施工、报告」剩下的都交给 Dev Assistant。
更多推荐

所有评论(0)