配套工程源码、测试材料与运行说明

前言

我先定下一条重置规则。配方从 225 g 改到 256 g,把「滤纸」这条冲煮笔记展开,再按重置。用水量回到 225 g,阅读位置仍留着。接下来按这条操作回看父页、参数控件和笔记三个地方。配方值通过 ArkUI 的 @Prop 读入,控件用回调通知父页;笔记是否展开只在自己的组件里变化。两种状态由不同位置持有,正好解释为什么一次重置有明确边界。

从 225 到 256,点一下走过哪些组件

DoseStepper 收到 grams 和 change 两个参数,一个用于显示,一个在按键时发出变化。加号并不自己把目标水量写成 240。父页收到 delta 后通过 adjustDose 加到当前克数,再将结果限制在 10 到 30。左栏的 WaterReadout 从父页拿的是 grams 乘 ratio。这条链上水量只算一次,子组件没有另一份可变的用水量。如果后来增加键盘加减,它也能把同样的增量交给 adjustDose,不需要复制边界规则。

private adjustDose(delta: number): void {
  this.grams = Math.max(10, Math.min(30, this.grams + delta));
}

把尺度放进真实操作里看。初始 grams 是 15,ratio 是 15,所以显示 225。按「加」触发 change(1),父页先接住这个值,把克数设成 16,用水显示就变成 240。接着选择一比十六,只改 ratio,不需要再调用 adjustDose,结果自然是 256。若读者顺着源码抓日志,可以先在两个事件回调各留一次,再在水量读数的参数观察最终乘积。这比在 WaterReadout 内新增一个可写字段容易定位。乘积变了但页面没变,优先查收到的参数;乘积算错,再看父页本轮到底用的两个数。

也可以测一次相反的动作。保持一比十六时减一克,预期由 256 走到 240。只换回一比十五时,仍用当前克数,预期读回 225。这里两条路得到同一个数字的可能性很高,所以验收应同时看 grams、ratio 与水量三处。只盯结果 240,可能误把改倍率当成了改粉量。未来要把两个入口接到键盘快捷键,也可用这组连贯动作区分具体哪个事件没有传到父页。

越过边界的情况可以拿同一个值来推演。30 克时再按加号,若子组件先写自己的 31,父页通过 adjustDose 仍保留 30,页面就可能同时出现 31 克和按 30 克算出的用水。现在 DoseStepper 只发 change(1),显示回读父页传入的 grams。倍率也是同一方向:预置按钮只上报选择,乘积由父页派发。改成历史配方输入时,验证应在导入值写入父页之前,按钮内的增减限制保护不了其他入口。

想检查左栏有无重复保存状态,可以临时在父页只记录一次 change 收到的值,再观察右边的用水文字。点击加号应先收增量,然后看到新的 grams 和水量;点击倍率不会经过 change。若两种操作都能改读数,却有一个分支触发了两次父页写入,就可以顺着这条日志追到多余的绑定。

父页的连线

RecipeTitle()
Row({ space: 24 }) {
  Column({ space: 15 }) {
    RecipeLegend()
    DoseStepper({ grams: this.grams, change: (delta: number): void => this.adjustDose(delta) })
    RatioPicker({ ratio: this.ratio, choose: (value: number): void => { this.ratio = value; } })
    WaterReadout({ water: this.grams * this.ratio })
    BrewFooter()
  }.padding(22).layoutWeight(6).backgroundColor('#F8F7FF').borderRadius(23)
  Column({ space: 26 }) {
    PhaseDisplay({ phase: this.phase })
    StepTimeline({ phase: this.phase })
    BrewControl({
      phase: this.phase,
      advance: (): void => { this.phase = Math.min(3, this.phase + 1); },
      resetRecipe: (): void => this.restore()
    })
  }.padding(24).layoutWeight(5).height(306).justifyContent(FlexAlign.SpaceBetween)
    .backgroundColor('#282450').borderRadius(23)
}.width('100%').alignItems(VerticalAlign.Top)
TasteNote()

完整页从上到下的视觉布局并不直接决定状态归属。左边排克数、倍率和值,右边用 phase 给时间线、卡片和两个动作。点「下一步」,父页最多推进到 3;出杯以后按钮使用这个结果禁用。右栏自己若新增「回看上一页」,建议让阅读位置单独管理,避免浏览一下旧卡片就把真实冲煮状态重置。做前进和回看时,可以分别留一条可重复的点击路径。

重置后为什么还能看到「滤纸」

private restore(): void {
  this.grams = 15;
  this.ratio = 15;
  this.phase = 0;
}

restore 把父页三个字段恢复。TasteNote 展开状态属于笔记自己的交互,父页没有传一份外部 expanded 过去,也不需要了解用户读到了哪行。点击恢复时组件仍在原来位置,不会因为三项业务状态变化就主动清空展开。这个边界在换布局时会暴露另一层问题。若窄窗口和宽窗口用两个条件分支各造一份 TasteNote,切换到另一分支时旧组件可能销毁。此时要保留原来的展开状态,可以给两种布局保住一个实例,或者让展开状态放到跨布局仍在的拥有者。

完整复测中,从准备点了一次「下一步」,右边到了闷蒸。随后展开笔记,核对提示正文出现「滤纸」。这才按重置,同时查三件事:水量回到 225,冲煮阶段回到「准备」,「滤纸」仍能读到。后面再次改克数和倍率,按顺序走闷蒸、注水、出杯,确保出杯后按钮已经禁用。把笔记内容当作状态证据要比只看图标朝向有用。有些控件在折叠时也保留箭头,只有正文出现才能确认展开仍有效。

模拟器操作

用水读数

另外核对的状态

开页、加一克、换一比十六

225、240、256

两个输入分别生效

闷蒸时开笔记,再重置

225

回准备,笔记仍见「滤纸」

再改配方,依次推进

256

出杯,下一步按钮不可用

最后一次「出杯」能看见阶段卡已经换值、下一步不可用;这是另一条验收,不能用一张 256 的读数图代替。出问题时把可见读数与源头分开定位:左栏水量正确、右栏不推进,先检查 BrewControl 发出的 advance 和父页 phase 的上限。重置后三个业务值正确而笔记消失,要查父级有没有替换整个 TasteNote 节点,而不是去改 restore 的计算。

十个部件有必要放在十个文件吗

这个小项目的入口保留了十个部件的定义,读到页面最后就能看到它们如何接在一起。拆组件的理由是职责和数据方向。比如 RecipeTitle 只显示版头,PhaseDisplay 用当前阶段画说明,DoseStepper 可以从「给一个数,收一次变动」独立理解。先把这几个接口讲清楚。等第二个配方页也需要克数控件,再抽成单独文件。若在拆文件时创建一个全局可写状态给所有组件,依赖反而比起初更难追。

实际修界面也能拿这些边界做自查。把左边「目标注水」文案改为「计划用水」,只涉及显示就不必碰父页克数。以后加一个计时器,先确定它属于某个步骤还是页面的整个冲煮过程;阶段回退、离开、重置是否停止,都和数字应该在哪里显示是不同的问题。按下出杯键再看计时器是否结束,比只读初始截图更能验新连接。

拆之前可以在旧页面上写一张按键记录,左边是动作,右边是必须变化的数。比如改一比十六只改 ratio 和派生的 water,不应该推进右栏步骤。下一步只推进 phase,粉量和比例应继续留着。笔记开合只改它自己的状态。切成新组合后按原样重做,哪一列多变一步,就沿这列的写入点找。把测试按真实操作排,而不是按组件数量排,能发现两个组件分别更新同一份字段的问题。

十个部件里并非每个都要提供修改入口。StepTimeline 只读 phase,展示当前与前后阶段;BrewControl 才把推进和重置交回给父页。若把事件从时间线也开出来,需要说明直接点「出杯」是否允许越过前面两步。视觉上看起来差不多的两张薄卡片,操作权限可能完全不同。让它们都拿一套通用的可写对象,会把这个决定藏到每个组件里。

再往下考虑配方保存。现在的 restore 恢复的是一个固定起点。如果应用允许把新的一组克数和比例存到历史,恢复默认、切到历史配方、撤销当前编辑应成为各自明确的动作。刷新成历史配方之前先请求的是克数和倍率,到了页面侧再装入有效状态。没有完成读取时可保留旧配方并提示。这些动作会影响多个显示组件,但业务判断仍可放在一起。

从完整入口复查三条状态链

运行文首工程的 entry 后,先按加号,再选一比十六。在父页记下 225、240、256 三个读数,用它们核对参数回调。接着进入闷蒸,展开笔记,按「重置配方」,观察步骤回到准备而笔记仍展开。想改构造时,先翻到 Index 查状态和事件接线,再进入小组件找展示部分。若不小心在每次重置后重新创建笔记组件,第二组动作会首先暴露变化。

const STEPS: string[] = ['准备', '闷蒸', '注水', '出杯'];

@Component
struct RecipeTitle {
  build() {
    Column({ space: 8 }) {
      Text('星期天手冲').fontSize(45).fontWeight(FontWeight.Bold).fontColor('#202253')
      Text('用量先定,冲煮按步骤走').fontSize(17).fontColor('#56587B')
    }.width('100%').alignItems(HorizontalAlign.Start)
  }
}

@Component
struct DoseStepper {
  @Prop grams: number = 15;
  change: (delta: number) => void = (_delta: number): void => {};
  build() {
    Row({ space: 10 }) {
      Text('咖啡粉').fontSize(19).fontColor('#202253').layoutWeight(1)
      Button('−').id('brew-minus').type(ButtonType.Circle).width(44).height(44)
        .fontColor('#28274D').backgroundColor('#DBDCF6').enabled(this.grams > 10)
        .onClick(() => this.change(-1))
      Text(this.grams + ' g').id('brew-grams').fontSize(24).fontColor('#202253')
        .fontWeight(FontWeight.Bold).width(76).textAlign(TextAlign.Center)
      Button('+').id('brew-plus').type(ButtonType.Circle).width(44).height(44)
        .fontColor('#FFFFFF').backgroundColor('#3E3A8B').enabled(this.grams < 30)
        .onClick(() => this.change(1))
    }.width('100%')
  }
}

@Component
struct RatioPicker {
  @Prop ratio: number = 15;
  choose: (value: number) => void = (_value: number): void => {};
  build() {
    Row({ space: 8 }) {
      Text('粉水比').fontSize(19).fontColor('#202253').layoutWeight(1)
      ForEach([14, 15, 16], (option: number) => {
        Button('1:' + option).id('brew-ratio-' + option)
          .backgroundColor(option === this.ratio ? '#3E3A8B' : '#DBDCF6')
          .fontColor(option === this.ratio ? '#FFFFFF' : '#28274D')
          .onClick(() => this.choose(option))
      }, (option: number): string => option.toString())
    }.width('100%')
  }
}

@Component
struct WaterReadout {
  @Prop water: number = 0;
  build() {
    Column({ space: 2 }) {
      Text('目标注水').fontSize(15).fontColor('#4F4D79')
      Row({ space: 9 }) {
        Text(this.water.toString()).id('brew-water')
          .fontWeight(FontWeight.Bold).fontSize(67).fontColor('#302868')
        Text('g').fontSize(24).fontColor('#4F4D79').margin({ top: 25 })
      }
    }.width('100%').alignItems(HorizontalAlign.Start).padding(18).backgroundColor('#E8E5FB').borderRadius(20)
  }
}

@Component
struct StepTimeline {
  @Prop phase: number = 0;
  build() {
    Row({ space: 5 }) {
      ForEach(STEPS, (label: string, index: number) => {
        Column({ space: 8 }) {
          Circle({ width: 12, height: 12 }).fill(index <= this.phase ? '#FFBFA5' : '#8580B3')
          Text(label).fontSize(15).fontColor(index === this.phase ? '#FFFFFF' : '#C4BFEB')
        }.layoutWeight(1)
      }, (label: string): string => label)
    }.width('100%')
  }
}

@Component
struct PhaseDisplay {
  @Prop phase: number = 0;
  build() {
    Column({ space: 7 }) {
      Text('当前步骤  /  ' + (this.phase + 1) + ' OF 4').fontSize(14).fontColor('#D7CEF4')
      Text(STEPS[this.phase]).id('brew-phase').fontSize(46).fontWeight(FontWeight.Bold).fontColor('#FFE9DC')
    }.width('100%').alignItems(HorizontalAlign.Start)
  }
}

@Component
struct BrewControl {
  @Prop phase: number = 0;
  advance: () => void = (): void => {};
  resetRecipe: () => void = (): void => {};
  build() {
    Row({ space: 12 }) {
      Button('下一步').id('brew-next').enabled(this.phase < 3).onClick(() => this.advance())
        .fontColor('#39264B').backgroundColor('#FFBFA5')
      Button('重置配方').id('brew-reset').onClick(() => this.resetRecipe())
        .fontColor('#F1EAFB').backgroundColor('#4F477C')
    }.width('100%')
  }
}

@Component
struct TasteNote {
  @State expanded: boolean = false;
  build() {
    Column({ space: 7 }) {
      Button(this.expanded ? '收起冲煮笔记' : '展开冲煮笔记').id('brew-note')
        .fontColor('#29275B').backgroundColor('#DBDCF6').onClick(() => { this.expanded = !this.expanded; })
      if (this.expanded) {
        Text('先润湿滤纸。闷蒸时从中心慢慢注水,避免直接冲刷滤杯边缘。')
          .id('brew-tip').fontSize(16).fontColor('#4F4D79')
      }
    }.width('100%').alignItems(HorizontalAlign.Start)
  }
}

@Component
struct RecipeLegend {
  build() {
    Text('配方计算').fontSize(22).fontWeight(FontWeight.Bold).fontColor('#202253')
      .width('100%').margin({ bottom: 1 })
  }
}

@Component
struct BrewFooter {
  build() {
    Text('注水量 = 咖啡粉用量 × 粉水比右侧数字').fontSize(15).fontColor('#56587B').width('100%')
  }
}

@Entry
@Component
struct Index {
  @State grams: number = 15;
  @State ratio: number = 15;
  @State phase: number = 0;

  private adjustDose(delta: number): void {
    this.grams = Math.max(10, Math.min(30, this.grams + delta));
  }

  private restore(): void {
    this.grams = 15;
    this.ratio = 15;
    this.phase = 0;
  }

  build() {
    Scroll() {
      Column({ space: 22 }) {
        RecipeTitle()
        Row({ space: 24 }) {
          Column({ space: 15 }) {
            RecipeLegend()
            DoseStepper({ grams: this.grams, change: (delta: number): void => this.adjustDose(delta) })
            RatioPicker({ ratio: this.ratio, choose: (value: number): void => { this.ratio = value; } })
            WaterReadout({ water: this.grams * this.ratio })
            BrewFooter()
          }.padding(22).layoutWeight(6).backgroundColor('#F8F7FF').borderRadius(23)
          Column({ space: 26 }) {
            PhaseDisplay({ phase: this.phase })
            StepTimeline({ phase: this.phase })
            BrewControl({
              phase: this.phase,
              advance: (): void => { this.phase = Math.min(3, this.phase + 1); },
              resetRecipe: (): void => this.restore()
            })
          }.padding(24).layoutWeight(5).height(306).justifyContent(FlexAlign.SpaceBetween)
            .backgroundColor('#282450').borderRadius(23)
        }.width('100%').alignItems(VerticalAlign.Top)
        TasteNote()
      }.width('100%').padding({ left: '6%', right: '6%', top: 29, bottom: 28 })
    }.height('100%').width('100%').align(Alignment.Top).backgroundColor('#F0EFFA')
  }
}

在 DevEco Studio 新建 ArkTS 空白 Stage 应用,保留默认路由,然后替换完整 Index.ets。选 MateBook Pro 的 API 24 模拟器系统 6.1.0.125(SP12DEVC00E47R1P3)。页面出现后按左栏,再到右栏和下部笔记;先开笔记再重置,不要从默认折叠状态开始判断重置规则。若重置后右侧卡片没回准备,查 BrewControl 是否调用 resetRecipe;若父页 phase 是 0 而卡片仍显示旧阶段,查显示组件是否错误缓存了一份初始值。出杯后回看按钮可用性,也能发现状态显示对了但事件仍能触发的错接。

想把例子搬进宽窄两套界面,可以先只换父页布局的 Row 和 Column,并重做读数路径。把 DoseStepper、RatioPicker 切到独立模块只是另一项重构,放在布局改变以后会更容易判断错因。截窄版时先关键信息可见:克数和倍率能读,用水没有被挡,右栏下一步可以操作,板底的笔记仍能打开。条件渲染整块替换时尤其要加一次重置后尺寸切换,确定展开是按需求恢复还是跟旧部件失效。这项额外验证与图中的固定窗口操作区别开。

FAQ

为什么下面的读数可以从乘法直接给? 它没有独立历史,水量应当随克数和比例立刻改变。单独存一份状态就必须在恢复、改粉、改比例三处保持同步。若以后改为实际称重,称出来的克数与计划水量是两份业务数据,应各自给名字。那时读数可以并排,不要共用一个可变值。

如果笔记也必须重置呢? 那是新的操作要求。可以把展开变成父页可控状态或给组件明确的重置输入,同时把用户已经写的品尝内容与展开状态分开。重置配方、关闭笔记、清空记录是否都应执行,要用真的业务动作试一轮。当前只有展开演示,不包含持久化品尝文本。

怎么检查加减已经到了边界? 直接给两个边界值的正例和一次越界尝试。比如连续加到 30 后再按,读数还应来自同一倍数;降到 10 后尝试再减,也应保住合法值。任何新增输入路径都用同一规则验。到出杯以后同样按一次前进查上限,这里的防护在父页和按钮显示都能看到。

父页是不是应该接管所有状态? 要看变化是不是需要跨组件解释。克数、倍率与阶段会给多个部件使用,统一放父页可以保证显示同时对齐。笔记开合只提供一个阅读交互,保留在局部比较简单。如果另一个区域要显示「笔记已打开」,这时才需要向上报告或提升数据的所有权。遇到这样的小需求,可以画出谁读、谁改,以及出现两个读取方的那一处,再安排新回调。

这套检查也适用于产品回归。把真实操作改成从历史配方加载以后,先检查读回的两个输入,再检查水量是否自动更新,笔记是否按规定复原。再选一次状态推进,看看新配方没有误把冲煮阶段推进。如果少了中间读数,左侧关键信息被意外重置也可能被最后一张出杯图掩盖。用操作顺序保护数据方向,界面要继续改配色和排列也有明确的对照。

总结

先沿加号把一个增量追到父页,再跟着恢复按钮看哪些字段归它改。克数、倍率和阶段有一个共同的主人,笔记独自记展开。下一次改配方板,只要这两条动作和边界还说得通,组件数量与文件位置就有调整空间。

复查时记一张带笔记的重置画面,再配上出杯端的状态,左右两条链都能对回原操作。

Logo

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

更多推荐