一个"拖动滑块数字不动"的小 Bug,掀出了四层连环坑

摘要:本文记录 MarkPin(鸿蒙 PC 端 Markdown 编辑器)开发中一次典型的"小 Bug 牵出大问题"经历。用户反馈设置面板滑块拖动后数值不实时刷新,排查发现根因并非早前 BUG-037 的状态通道问题,而是 @Builder 按值传参不建立响应式观察的渲染通道问题。修复过程中顺带走查出同族/关联缺陷共 4 个(BUG-040~043):行宽无法调回"不限制"、自动配对开关从未生效且会清空编辑扩展仓、开关 isOn 同族按值传参等。文中给出对象字面量按引用传参的修复模式、常量传参的"误伤提醒",以及"同现象不同根因"的分层排查心得。

这个系列记录我用 AI 从零开发鸿蒙 PC 端 Markdown 编辑器 MarkPin 的全过程。这一篇讲一次很典型的经历:一个用户可感知的小 Bug(滑块数值不实时刷新),修下去才发现不是孤例,而是一整族问题的入口——最终走查收尾出 4 个同族/关联缺陷(BUG-040~043,PROBLEM-LOG 第二十五/二十六轮)。

问题描述

设置面板 4 个滑块(字号/行宽/自动保存间隔/阅读速度),拖动后标题行右侧的数值文本不实时变化,退出设置重进才显示新值。

这个现象似曾相识:早前的 BUG-037(字号不实时更新)修过一次。所以第一反应不是"重新查一遍",而是先问:是老问题复发,还是同一现象的另一个根因?

分析定位

ArkUI 里一条"拖滑块 → 数字变"的链路有两段:状态通道(onChange 把值写进状态变量)和渲染通道(UI 观察状态变量并重绘)。BUG-037 修的是前者——状态变量到 AppStorage 的同步通道(@StorageProp 改 @StorageLink)。通道修好了,现象却还在,那问题大概率在后者。

逐段核查 SettingsPanel.ets 后定位到:sliderItem 是一个 @Builder 方法,value 以基本类型按值传入。ArkUI 中 @Builder 按值传参不建立响应式观察——Builder 内的 Text(String(value)) 拿到的是调用时的快照。所以 onChange 更新状态后,标题数值纹丝不动;退出重进时 build() 重新执行、Builder 重新调用,才"顺便"拿到新值。现象复发、根因与 BUG-037 不同层。

解决代码

修复模式:把基本类型参数收进一个接口,调用处改为单对象字面量按引用传参——ArkUI 对该形式建立观察(依 PROBLEM-LOG 记录精简):

// 修复前:按值传参,不建立观察
this.sliderItem('字号', this.fontSize, 12, 32, (v: number) => { ... })

// 修复后:对象字面量按引用传参
interface SliderItemParam {
  label: string
  value: number
  min: number
  max: number
  onChange: (v: number) => void
}

this.sliderItem({
  label: '字号',
  value: this.fontSize,   // 引用状态变量,ArkUI 建立观察
  min: 12,
  max: 32,
  onChange: (v: number) => { this.fontSize = v }
})

同一轮走查还带出三个关联缺陷,各有各的精彩:

BUG-041 行宽无法调回"不限制":case 'lineWidth' 条件写的是 lineWidth > 0 才桥接/持久化——0 被静默丢弃;web 侧 setLineWidth 又有 width <= 0 return。两处拦截叠加,行宽一旦拖大就永久失去"不限制"(重启也回不去)。更扎心的是,字符串资源里"不限制"的词条自始存在但全工程零引用——半成品遗留。修复是两处条件补 0 语义,并把"不限制"做成显式档位。

BUG-042 「自动配对」开关从未生效:这个最颠覆。定位发现三层缺陷叠加——① setAutoPair 的 if/else 两个分支代码完全相同(都 editCompartment.reconfigure([])),开关自上线起就没工作过;② reconfigure([]) 顺带清空了整个编辑扩展仓(表格/列表/块级 keymap、三击选块、引用粘贴补全全在里面),每次切换后编辑增强集体失效,直到下次模式切换才被重建——这就是用户"摸不清生效逻辑"的原因;③ 自动配对实际由视图模式硬编码,偏好值从未参与运行时。修复(依记录精简):

// 修复前:两分支相同 + 清空全部扩展
if (enabled) {
  editCompartment.reconfigure([])
} else {
  editCompartment.reconfigure([])   // 和 if 一模一样
}

// 修复后:偏好 + 只换配对扩展,立即生效
autoPairPrefEnabled = enabled
editCompartment.reconfigure(buildEditExtensions(enabled))

BUG-043 开关同族收尾:主动走查发现 toggleItem/toggleItemWithDesc 的 isOn 也是按值传参——和滑块同一机制层。当时没有视觉异常是因为 Toggle 点击会自翻转外观"看起来同步",但这掩盖了通道断裂:一旦状态被外部改变(比如未来加"恢复默认"),开关就显示旧态且无自愈通道。修复同样走对象字面量模式。

一个重要的"误伤提醒"

走查时也核查了看似同病的 themeOption/languageOption/lineWidthOption:它们虽按值传参,但传的是常量(id/label 运行期不变),选中态判定直读 this.currentXxx——等价于 build 内直读,响应式没问题(主题/语言切换高亮实时刷新长期正常就是实证)。不要看到"按值传参"就无差别改,先分清传的是状态还是常量。

验证与效果

deveco-mcp check 零诊断 + devecocli build 通过;装机后用户确认滑块实时刷新、行宽三档切换正常、自动配对开关立即生效且三模式行为一致、编辑增强无连带失效。四个缺陷全部闭环。

能力边界表

环节AI 表现结论
定位 @Builder 传参层准确区分"BUG-037 通道层"与"本条渲染层",避免重复修同一现象可信
发现 BUG-042 两分支相同靠逐行核查而非"相信开关应该工作过"可信,值得推广的走查姿势
判断常量传参面安全给出等价性论证而非一刀切避免误伤
提前发现 BUG-043修复后主动走查同族,而非等用户报主动性有价值的实例

心得收尾

这轮最大的收获是**“同现象不同根因"的分层意识**:BUG-037 和第二十五轮的现象一模一样,但一个在状态通道、一个在渲染通道。如果第二次直接照抄第一次的修法,就会得出"修好了又坏了"的错误结论。AI 协作里,让 AI 先回答"这是复发还是新根因”,往往比直接要修复代码更值钱。

如果你也在试 AI 开发鸿蒙,或者想看后续,关注专栏,所有踩坑都会持续更新。

Logo

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

更多推荐