ArkTS 表单工程：保养录入页的换行胶囊与四字段表单-育师

ArkTS 表单工程：保养录入页的换行胶囊与四字段表单

App 58「车辆保养提醒」保养页（Func1Tab），主题色#008080青蓝。本页是保养记录的"录入页"——白色单行 Header（"记录保养"20 号加粗）+保养项目卡（"保养项目"标题 + 6 个换行胶囊：机油机滤/轮胎/刹车片/蓄电池/空调滤芯/其他，默认选中机油机滤）+四字段保养表单（保养里程（km）Number / 保养费用（元）Number / 保养店铺 TextInput / 备注 TextArea 多行）+青蓝全宽"记录保养"按钮（里程非空弹"保养已记录"，空则弹"请填写里程"）。本篇基于58-car-maintain/entry/src/main/ets/pages/Func1Tab.ets（共 89 行）逐段拆解，附 4 张实机截图。

一、整体结构：三区"Header + 项目 + 表单"布局

保养页是"项目选择 + 保养录入"的组合布局——3 个 @Builder 块：

build() { Column() { this.Header() Scroll() { Column({ space: 16 }) { this.ItemCard() this.FormCard() Button('记录保养').fontSize(15).fontColor('#FFFFFF').backgroundColor(C.primary) .width('100%').height(48).borderRadius(D.rMd) .onClick(() => { promptAction.showToast({ message: this.mileage.length > 0 ? '保养已记录' : '请填写里程' }); }) } .width('100%') .padding({ left: D.pad, right: D.pad, top: 16, bottom: D.pad + this.safeBottom + 20 }) } .layoutWeight(1).scrollBar(BarState.Off).align(Alignment.Top) } .width('100%').height('100%').backgroundColor(C.bg) }

3 块结构：

ItemCard— 保养项目 6 胶囊（机油/轮胎/刹车片/电池/空调滤芯/其他）
FormCard— 四字段保养表单（里程/费用/店铺/备注）
记录保养— 青蓝全宽 CTA 按钮（里程校验）

保养页是"录入页"——先选保养项目（机油机滤等 6 类），再填保养数据（里程/费用/店铺/备注），最后保存。项目 + 表单两卡分工：上卡选"做了什么保养"、下卡填"在多少公里、花了多少钱、在哪做的"。

项目源码开源：https://gitee.com/codenestFlow/HarmonyOSHub

二、Header：单行品牌头

Header() { Row() { Text('记录保养').fontSize(20).fontWeight(FontWeight.Bold).fontColor(C.text) } .width('100%').height(this.safeTop + 56).padding({ top: this.safeTop, left: D.pad, right: D.pad }) .backgroundColor(C.card).alignItems(VerticalAlign.Bottom) }

功能页 Header 标准范式（20 号、safeTop + 56固定高、文字贴底），与日志页、我的页同款。"记录保养"是动作型标题（动词短语），与系列录入页（App 52 上传票据、App 57 记录加油）一致。

三、ItemCard：保养项目换行胶囊

ItemCard() { Column({ space: 12 }) { Text('保养项目').fontSize(14).fontWeight(FontWeight.Bold).fontColor(C.text).width('100%') Flex({ wrap: FlexWrap.Wrap }) { ForEach(this.items, (it: string, idx: number) => { Text(it).fontSize(12) .fontColor(this.activeItem === idx ? '#FFFFFF' : C.textSub) .padding({ left: 14, right: 14, top: 8, bottom: 8 }) .backgroundColor(this.activeItem === idx ? C.primary : C.cardSoft).borderRadius(16) .margin({ right: 10, bottom: 10 }) .onClick(() => { this.activeItem = idx; }) }, (it: string) => it) }.width('100%') } .width('100%').padding(16).backgroundColor(C.card).borderRadius(D.rLg).border({ width: 1, color: C.stroke }) }

技术拆解：

6 个保养项目胶囊：机油机滤/轮胎/刹车片/蓄电池/空调滤芯/其他——Flex({ wrap: FlexWrap.Wrap })换行排布（4 个一行 + 2 个换行），默认选中"机油机滤"（activeItem = 0，最常做的保养项目）。
选中态：选中青底白字（C.primary+ 白字）、未选灰底灰字（cardSoft+textSub）——系列标准胶囊公式，圆角 16。
项目覆盖：6 类覆盖"常规保养"（机油机滤、空调滤芯）"更换件"（轮胎、刹车片）"检查件"（蓄电池）"兜底"（其他）——保养项目的典型分类，与首页 4 个保养项目（机油机滤/轮胎/蓄电池/刹车片）对应（首页展示的是"当前有状态的项目"，保养页可选全部）。
与首页联动：在保养页选"刹车片"记录后，首页的刹车片状态会更新（超期 → 正常）——记录项目 = 刷新首页状态。

四、FormCard：四字段保养表单

FormCard() { Column({ space: 14 }) { Column({ space: 6 }) { Text('保养里程（km）').fontSize(13).fontColor(C.textSub).width('100%') TextInput({ placeholder: '12580' }).type(InputType.Number) .backgroundColor(C.cardSoft).borderRadius(D.rSm).height(44) .onChange((v: string) => { this.mileage = v; }) } Column({ space: 6 }) { Text('保养费用（元）').fontSize(13).fontColor(C.textSub).width('100%') TextInput({ placeholder: '0.00' }).type(InputType.Number) .backgroundColor(C.cardSoft).borderRadius(D.rSm).height(44) .onChange((v: string) => { this.cost = v; }) } Column({ space: 6 }) { Text('保养店铺').fontSize(13).fontColor(C.textSub).width('100%') TextInput({ placeholder: '例如：4S店/维修厂' }) .backgroundColor(C.cardSoft).borderRadius(D.rSm).height(44) } Column({ space: 6 }) { Text('备注').fontSize(13).fontColor(C.textSub).width('100%') TextArea({ placeholder: '保养内容说明...' }) .backgroundColor(C.cardSoft).borderRadius(D.rSm).height(80) } } .width('100%').padding(16).backgroundColor(C.card).borderRadius(D.rLg).border({ width: 1, color: C.stroke }) }

四字段保养表单：

保养里程（km）：TextInput({ placeholder: '12580' }).type(InputType.Number)——保养时的仪表里程（保存校验的锚点字段），Number 键盘，占位符 12580 与首页当前里程一致。
保养费用（元）：TextInput({ placeholder: '0.00' }).type(InputType.Number)——保养花费（金额），占位符 0.00 暗示两位小数，费用进入日志页的"累计花费"统计。
保养店铺：TextInput({ placeholder: '例如：4S店/维修厂' })——保养地点（4S 店/维修厂），记录"在哪做的保养"，占位符示范两种类型。
备注（TextArea）：TextArea({ placeholder: '保养内容说明...' })——多行文本区（高 80、圆角 10），记录保养细节（"换了全合成机油""检查了刹车片厚度"），这是系列中少见的 TextArea 多行输入（其他录入页都是单行 TextInput），适合备注类长文本。

五、记录按钮：状态校验的交互闭环

Button('记录保养').fontSize(15).fontColor('#FFFFFF').backgroundColor(C.primary) .width('100%').height(48).borderRadius(D.rMd) .onClick(() => { promptAction.showToast({ message: this.mileage.length > 0 ? '保养已记录' : '请填写里程' }); })

技术拆解：

全宽青蓝 CTA：width('100%').height(48)+backgroundColor(C.primary)——主色全宽按钮（录入页标准 CTA）。
三元校验：this.mileage.length > 0 ? '保养已记录' : '请填写里程'——以里程为校验锚点（保养里程是保养记录的核心字段——没有里程就无法推算下次保养周期），里程非空 → 记录成功；为空 → 提示"请填写里程"（App 57 加油页校验"加油量"、本页校验"里程"，锚点字段都是"驱动后续计算的字段"）。

六、跨页数据自洽：保养录入的全局闭环

保养页与首页、日志、我的三页形成闭环：

保养"项目 + 里程"↔ 首页"刹车片已超期"→ 记录后更新——记录项目 = 刷新首页状态（在保养页记录"刹车片"后，首页刹车片从"已超期"变为"正常"、剩余里程重置）。
保养"费用"↔ 日志页"¥480 机油机滤更换"——录入的费用出现在日志页（机油机滤更换 480 元），并汇入日志页"累计花费 ¥3860"，录入 → 日志展示 → 累计统计。
保养"里程 12580"↔ 首页"当前里程 12,580 km"、我的页"本田雅阁 · 12,580 km"——里程一致（保养时记录的里程就是当前里程），保养记录是最新的里程来源。
保养"项目 6 胶囊"↔ 首页"4 个保养项目"——保养页 6 类包含首页 4 项（机油机滤/轮胎/蓄电池/刹车片），首页展示"有状态的项目"、保养页可选"全部项目"，项目体系同源。
保养"记录"↔ 日志页"保养历史"时间轴——每次保养记录进入日志页时间轴（机油机滤更换 12080 km 2026-07-28），录入即入日志。

七、系列横向对比：录入页的四字段表单变体

系列中"录入型"页面的表单对比：

App 58 保养页：项目胶囊 + 四字段（含 TextArea 备注）——"项目 + 长备注"，多行文本。
App 57 加油页：油品胶囊 + 三字段（全 Number）——"参数 + 数据质量开关"。
App 56 记录页：常用地点胶囊 + 四字段——"快捷回填 + 时间双列"。
App 55 添加页：四件套 + 提醒三档——"服务 + 提醒配置"。

58 的差异化在于**"TextArea 多行备注"**——四字段中备注用多行文本区（80 高），是系列录入页中唯一的"长文本输入"（其他录入页都是单行 TextInput），因为保养内容需要详细记录（换了什么件、检查了什么、建议下次何时保养），备注的长文本属性匹配保养场景的信息需求。同时"保养店铺"字段记录"在哪做的"，也是保养场景专属（加油不需要记录店铺、停车不需要）。

八、开发者避坑：保养录入的四个细节

从 Func1Tab 的实现提炼四个易踩坑点：

下次保养里程推算：当前录入里程但不推算下次保养——产品化应"记录里程 + 项目周期 → 下次保养里程"（机油机滤每 5000km，记录时自动设下次 = 本次里程 + 5000），首页剩余里程 = 下次 - 当前，录入驱动首页状态。
项目与周期的映射：不同项目保养周期不同（机油 5000km、刹车片 3 万 km、蓄电池检查 2 万 km）——产品化建立"项目 → 周期"映射表，选择项目自动带出对应周期，避免"所有项目都按 5000km"的错误。
费用校验与统计：费用 Number 输入但未校验——产品化校验费用非负、格式两位小数（费用为 0 可能是免费保养），且费用进入日志页"累计花费"统计（¥3860 = 各次费用之和）。
备注的长度限制：TextArea 无字数限制——产品化设备注长度上限（如 200 字）并显示计数（避免超长文本撑爆日志卡片），TextArea 的 onChange 也应绑定状态（当前未绑定this.note）。

九、常见问题 FAQ

问：保养项目和首页的保养项目是什么关系？答：保养页的 6 个项目（机油机滤/轮胎/刹车片/蓄电池/空调滤芯/其他）是"可选保养类型全集"，首页的 4 个项目（机油机滤/轮胎/蓄电池/刹车片）是"当前有状态的项目"（记录了保养计划/剩余里程的）——在保养页记录某个项目后，该项目在首页出现状态；首页的项目都能在保养页找到对应胶囊，两处项目体系同源。

问：记录保养时为什么只校验里程？答：因为里程是保养记录的核心字段——没有里程，无法推算"下次保养还剩多少公里"（首页剩余里程 = 下次保养里程 - 当前里程），保养记录就失去了周期管理价值。费用、店铺、备注可以后补或留空（记录的核心是"在多少公里做了保养"），校验只锁"驱动后续计算的字段"。

问：保养店铺填 4S 店和维修厂有什么区别？答：4S 店（原厂服务，价格高但保真、有保养记录联网）和维修厂（价格低、自主选择配件）是两类保养渠道——记录店铺后，日志页的保养历史能看出"哪次在 4S 店、哪次在维修厂"，方便对比价格与质量。产品化后可统计"4S 店 vs 维修厂的费用对比"，帮助用户决策下次去哪保养。

十、验收与总结

本篇对 58-car-maintain 保养页（Func1Tab，89 行）做了逐块拆解：

三区结构：Header（记录保养）+ ItemCard（6 项目胶囊）+ FormCard（四字段表单 + TextArea）+ 记录按钮
核心交互：项目胶囊单选（默认机油机滤）、TextArea 多行备注、保存按钮里程校验
主题色：#008080青蓝——胶囊选中态、保存按钮两处主色
数据闭环：记录项目 → 首页状态刷新，费用 → 日志页累计，里程 12580 → 首页/我的页

保养页是车辆保养提醒的"录入口"——选项目、填四字段、记录保存，一页完成保养记录。

十、扩展思考：从手工记录到智能保养

保养页的演进方向是"智能保养"：第一是保养周期自动推荐——当前项目胶囊是静态 6 类，演进方向是记录后自动计算下次保养（机油机滤每 5000km、刹车片每 3 万 km），并推荐"下次保养时间"（按里程或按时间哪个先到），保养页的里程字段是周期计算的基准；第二是保养项目价格参考——不同项目价格差异大（机油 500 元、四轮换位 60 元、常规保养 650 元），演进方向是记录常见项目的历史均价并预估下次费用（"机油保养上次 480 元"），让用户对保养花费有预期；第三是保养提醒推送——记录保养后按周期推送下次提醒（"距下次机油保养还剩 500km"），保养页的里程记录驱动首页告警与推送；第四是保养记录 OCR——保养单据/支付记录自动识别（项目/金额/里程自动填入），保养页的四字段是 OCR 的填充分区。这四个方向都从保养页已有的项目与四字段长出来，让"记一笔"变成"智能管家"。

十一、从设计稿到代码的映射

把保养页设计稿翻译成代码，有几组典型映射：第一，"保养项目"映射为"流式换行胶囊"——设计稿的六个项目选项，代码里用流式换行容器包裹六个文本胶囊，选中态青蓝底白字、默认选中第一项（机油机滤）；第二，"两个数字输入"映射为"单列数字输入组件"——设计稿的里程与费用，代码里用两个全宽数字输入组件，各配灰标签；第三，"店铺输入"映射为"单列文本输入"——设计稿的保养店铺，代码里用全宽文本输入组件，占位符示范格式；第四，"备注多行"映射为"文本区域组件"——设计稿的备注区，代码里用八十高的多行文本区域组件，支持换行长文本。这四组映射展示了"保养录入页"的完整翻译，其中"多行文本区域"是本页区别于其他录入页的技术要点。

十二、常见问题 FAQ

问：保养项目为什么要 6 个而不是更多？答：6 类覆盖了家用车保养的绝大多数场景——常规保养（机油机滤、空调滤芯）、更换件（轮胎、刹车片）、检查件（蓄电池）、兜底（其他）。更多细分（变速箱油、火花塞、防冻液）可通过"其他"备注记录，或产品化后在"保养周期"菜单自定义项目。6 类是"够用且不冗余"的平衡。

问：记录保养时为什么只校验里程？答：因为里程是保养记录的核心字段——没有里程，无法推算下次保养周期（下次 = 本次里程 + 周期），首页的剩余里程就无法更新。费用、店铺、备注是"补充信息"（可后补或留空），校验只锁"驱动后续计算"的字段，这与 App 57 加油页校验"加油量"（驱动金额与油耗计算）同理。

问：备注的 TextArea 和普通输入框有什么区别？答：TextArea 是多行文本区域（80 高、支持换行），适合记录长内容（"换了全合成机油、检查了刹车片厚度、建议下次 2 万公里换"）；普通 TextInput 是单行（44 高、不支持换行），适合短内容（店铺名）。本页备注用 TextArea 是因为保养内容需要详细记录，这是系列录入页中唯一的多行输入。

十三、补充要点：保养页三个细节再思考

第一，关于项目胶囊的默认值。默认选中"机油机滤"（数组第一项）——机油机滤是最常做的保养（每 5000km 一次，频率最高），默认选中它让多数用户"打开就能填"，不用改选；同时它是首页 4 个项目中第一个（机油机滤），与首页的优先级一致。第二，关于店铺占位符的信息价值。"例如：4S店/维修厂"不只是格式示范——它暗示了保养的两种主要渠道（4S 店原厂服务 vs 维修厂经济实惠），用户填店铺时自然会想"这次在哪做的"，记录店铺后日志页能对比"4S 店 vs 维修厂"的费用差异，占位符引导了信息的记录维度。第三，关于四字段的顺序。里程（驱动计算）→ 费用（金额统计）→ 店铺（来源记录）→ 备注（细节补充）——按"核心到补充"的顺序排列：先填最重要的（里程）、再填次要的（费用店铺）、最后填可选的（备注），用户按顺序填写自然完成"从必要到可选"的录入。

十四、最后总结

保养页是车辆保养提醒的"录入口"，也是系列"录入型"页面的代表。它用项目胶囊解决"做了什么保养"（6 类覆盖），用四字段表单解决"在多少公里、花了多少、在哪做的"（里程/费用/店铺/备注），用带校验的保存按钮保证记录有效（里程必填）。整页交互围绕"录入效率与数据价值"展开：项目胶囊默认机油、TextArea 记录细节、里程驱动周期、单一校验降低门槛。从演示到产品，保养页的进化路线清晰：周期自动推荐、价格参考预估、提醒推送、单据 OCR。作为"从保养到记录"的入口页面，它展示了录入类应用的标准骨架，也为首页告警、日志时间轴、累计统计提供了数据基础——没有记录，就没有后续的一切管理。四字段每一条都在为其他页面服务，这是"入口页面"的核心价值。

十五、补充要点：表单交互的细节再思考

保养页有几个容易被忽视的交互细节：第一，输入框的聚焦体验——里程、费用、店铺、备注四个输入框从上到下排列，用户应能通过键盘的"下一项"键在字段间跳转（产品化设置回车键的下一步行为），减少手指移动；第二，项目胶囊的即时反馈——点击保养项目立即变色（青底白字），用户无需等待或确认就能感知选中（"这次做的是刹车片"），这种"所见即所得"的单选交互比下拉列表更轻快；第三，里程输入的容错——里程是数字输入（Number 键盘），但用户可能输入带逗号（12,580）或空格，产品化应做输入清洗（去逗号空格）统一为纯数字；第四，记录成功的后续动作——当前弹 Toast"保养已记录"即结束，产品化应提供"继续记录"与"返回首页"两个动作（一次保养可能做多个项目，如机油 + 空调滤芯一起做），减少重复操作。这四个细节都围绕"录入效率"展开，把"能填完"提升为"填得快、填得对"。

十六、最后总结

保养页解析至此完整收尾：保养项目胶囊、四字段表单、多行备注、保存校验全部覆盖。读者可重点回顾"多行文本区域"的使用——它是系列录入页中唯一的长文本输入（80 高、支持换行），匹配保养备注的信息需求，也是本页区别于其他录入页的核心实现。车辆保养从这一页开始：选项目、填里程费用、记店铺备注，每一次保养的数据就这样被捕捉下来。