XComponent 的 ArkUI 实践

HarmonyOS 原生 ArkTS / ArkUI 实战

本文围绕 X Component 的当前工程、源码和运行验证展开，所有示例以对应页面实现为准。

一、先列故障现象：问题从哪里暴露

X Component 不是把一个 API 放到页面上就算完成。用户进入页面时需要知道当前对象、当前阶段和下一步动作；执行操作后，还要能从文字、数值、颜色、列表或控件状态中确认结果。当前工程把 「XComponent 容器」、「高性能原生 surface 承载」、「033」、「surface_id: preview_01」、「生命周期：创建 → onLoad 绑定 → onRelease 释放」 组织成一条可以运行的路径，因此本文先从业务问题开始，再回到 ArkTS 的实现细节。

这类页面最容易出现的误区是只描述“用了什么组件”，却没有说明“组件解决了什么问题”。状态管理与页面协作关注的是状态怎样在多个区域之间保持一致。文章中的判断都会回到当前页面真实可见的文案和回调，不凭空增加工程能力。

阅读时可以把页面看成三个连续阶段：默认状态告诉用户页面是什么，操作阶段改变一个或多个权威字段，结果阶段把变化留在界面上。只要这三段能够互相解释，截图才有证据价值，源码也不会沦为没有上下文的代码堆。

先列出最容易被误判的现象，再按输入、状态、渲染和生命周期逐层缩小范围。

本篇切入角度：排错驱动

当 「XComponent 容器」、「高性能原生 surface 承载」、「033」、「surface_id: preview_01」、「生命周期：创建 → onLoad 绑定 → onRelease 释放」 没有按预期变化时，不要立即重写布局。本文先问事件是否到达，再问 source、running 是否变化，最后才检查组件是否被正确重绘。

权限或能力不可用：确认用户看到的是可行动的提示，而不是技术错误堆栈。

同一个工程可以从不同角度阅读：有人先看页面，有人先看状态，有人先看故障。这里采用“排错驱动”的顺序，但不会改变源码事实；X Component 的核心仍然由 source、running、「onClick」 和可见结果共同决定。

为了避免套用结论，后文会把这个角度落到当前页面的具体文案、组件和操作上，并在运行验证章节重新检查它是否成立。

二、能力边界决定排错入口

本页属于“状态管理与页面协作”。从 ArkUI 角度看，ArkUI 状态装饰器、声明式重绘和页面间数据传递负责提供能力，但它们不会自动替业务做出状态定义。开发者仍需决定输入的权威来源、回调的触发条件、结果的显示位置，以及页面离开或失败后如何恢复。

页面状态只描述当前可见事实，业务校验和外部数据放在独立的数据边界内。例如，把输入、处理中和结果文本塞进同一个字段，会让用户看到的文字与实际业务状态失去对应关系。更稳妥的方式是保留原始输入、处理中标记和结果反馈，让每个字段都有单一职责，并让 UI 只负责把已经整理好的事实呈现出来。

如果未来接入真实系统能力，建议先为能力层定义最小接口：输入是什么、成功返回什么、失败有哪些类别、是否可以重试。页面代码不应依赖某个模拟器恰好存在的环境，也不应把权限、网络或设备连接的技术错误直接显示给用户。

三、从可视区域定位布局问题

当前页面使用 「Column」、「Row」、「Text」、「Stack」、「Button」。这些组件不是平铺在同一层，而是分别承担标题或说明、主要内容、操作入口和反馈结果。首屏应先让读者找到页面主题，再找到可以执行的动作，最后看到动作会影响哪一块内容；如果三者距离过远，操作后的截图就很难证明状态真的发生了变化。

布局还要面对文字增长、系统字体放大、屏幕宽度变化和内容滚动。对于列表、日志或历史记录，应把滚动范围限制在内容区域；对于按钮和输入框，应给出清晰名称和足够触控面积；对于结果提示，应避免用颜色作为唯一表达。这样即使换成更长的业务文案，页面仍然有稳定的阅读顺序。

从源码阅读页面时，建议先找根组件的 build 方法，再找被调用的 Builder 或子组件，最后追踪事件回调写入了哪些状态。这个顺序比从第一行开始逐字阅读更快，因为它先建立结构地图，再定位状态变化和边界分支。

四、状态与数据模型：每个字段只表达一个事实

当前源码声明的状态字段如下。字段名、装饰器类型和默认值是文章中最可靠的事实来源，后面的交互说明都应能回指到其中至少一个字段。

字段	类型与来源	页面职责
source	State，类型 string	默认值：‘相机预览’；只表达一个稳定事实
running	State，类型 boolean	默认值：true；只表达一个稳定事实

source、running之间应保持清晰的依赖关系：输入变化不应偷偷改写历史结果，处理中状态不应通过清空内容来表示，失败提示也不应覆盖用户仍需查看的成功数据。状态来源、更新顺序、返回页面后的恢复策略，因此状态设计要特别关注“谁写入、何时写入、写入后谁重绘”这三个问题。

五、源码走读：把组件、文案和回调连成证据链

源码中可以直接确认的组件包括 「Column」、「Row」、「Text」、「Stack」、「Button」；页面文案包括 「XComponent 容器」、「高性能原生 surface 承载」、「033」、「surface_id: preview_01」、「生命周期：创建 → onLoad 绑定 → onRelease 释放」。事件入口为 「onClick」，条件分支围绕 默认状态和用户操作结果 展开。独立方法包括 Column()、Row()、Column({space:4})、Stack({alignContent:Alignment.Center})、Column({space:8})、Row({space:8})。

先看静态结构：「Column」、「Row」、「Text」、「Stack」、「Button」决定页面能够表达哪些信息；再看动态入口：「onClick」决定用户能够触发哪些变化；最后看分支：默认状态与操作结果决定同一个入口在不同条件下会给出什么结果。三者合起来，才是 X Component 的实际功能边界。

源码中出现的文字也值得认真对待。「XComponent 容器」、「高性能原生 surface 承载」、「033」、「surface_id: preview_01」、「生命周期：创建 → onLoad 绑定 → onRelease 释放」不是装饰，它们共同构成截图中的验收锚点。文章解释某个状态时，应尽量使用页面上真实出现的词，而不是用一个工程里没有的抽象名词替代；这样读者可以在模拟器中按原文操作并复现结果。

如果需要继续拆分代码，可以按“输入与状态、布局与呈现、事件与结果”三组阅读。输入与状态回答数据从哪里来，布局与呈现回答数据如何被看见，事件与结果回答一次操作是否留下了可验证的变化。这种分组也方便后续将页面接入真实数据源。

六、把一次点击拆成四个排查点

当前实现的事件入口为 「onClick」。一次完整操作至少包含四步：读取输入或当前选择，检查是否允许继续，更新 source、running 中的权威字段，再把结果写回文字、列表、颜色、进度或控件状态。只执行前三步而不渲染结果，用户仍然无法判断操作是否成功。

操作后的反馈应当具有方向性。例如数值递增要能看出递增前后的差异，选中态要同时改变文字或背景，加载完成要从等待切换到成功，失败时要保留重试入口。状态来源、更新顺序、返回页面后的恢复策略，所以反馈不能只依赖短暂动画或控制台日志，必须在页面上保留到下一次明确操作。

连续操作时还要观察覆盖关系：快速点击是否重复提交，旧回调返回时是否覆盖了新选择，切换页面后是否把结果写回已经不可见的界面。可以为每个事件记录“触发前字段值、动作、触发后字段值、页面差异”四列，这比只写“点击后正常”更容易定位问题。

七、异常分支的可见诊断

状态来源、更新顺序、返回页面后的恢复策略不只发生在正常路径。页面首次进入、暂时离开、重新进入、外部结果返回和用户主动重置，都可能改变状态的有效期。需要明确哪些数据应该保留，哪些数据回到默认值，哪些异步回调在页面不可见时必须停止或丢弃。

异常状态至少应区分输入不足、能力不可用、处理中、成功但无数据和操作失败。它们的处理动作不同：输入不足需要指出缺少什么；能力不可用需要说明如何恢复；无数据要保留页面结构；失败要保留可重试入口。把输入、处理中和结果文本塞进同一个字段，会让这些状态全部退化成一个难以解释的空白区域。

对于外部能力和异步任务，建议把请求标识、当前选择和结果写入顺序纳入设计。只有仍然对应当前页面上下文的结果，才允许更新可见状态；已经过期的结果应被忽略或记录为调试信息，而不能覆盖用户刚刚做出的新选择。

八、性能、兼容性与维护：把优化落到可观察现象

X Component进入真实项目后，优化不能停留在“减少代码”或“提升性能”的口号上。应先确定观察指标：首帧是否延迟、输入是否卡顿、列表滚动是否丢帧、内存是否持续上涨、媒体或订阅是否在页面离开后仍然占用资源。指标必须能由一次操作或一组回归步骤复现。

状态更新要尽量缩小影响范围，避免一个无关字段变化导致整棵复杂布局重建；列表和图片要考虑复用、缓存与释放；网络、设备或文件能力要有超时和重试上限。页面状态只描述当前可见事实，业务校验和外部数据放在独立的数据边界内，这样性能问题才不会被页面层的临时补丁掩盖。

兼容性检查还包括系统字体、深浅色背景、不同屏幕尺寸、横竖屏变化和无障碍阅读。截图只代表一个设备和一个时刻，发布前仍应使用更长文案、更大字体和连续操作复查布局边界，确保文字、按钮和结果区域不会互相遮挡。

九、用运行图验证修复是否成立

初始图用于确认页面默认结构、标题、主要数据和第一组操作入口。阅读图片时不要只看颜色是否好看，而要核对它是否与源码中的默认状态一致：默认选项、默认数值、默认提示和内容可见范围都应能在代码里找到来源。

操作图用于确认事件真的到达页面并留下结果。请对照 「onClick」 逐项检查操作前后的可见差异：哪些文字变化了，哪些颜色或选中态变化了，哪些数据仍应保持不变。如果图片看起来与初始图几乎相同，说明当前验证路径还不足以证明业务逻辑。

截图与文章必须来自同一份最终源码。修改页面后需要重新采集初始图和操作图，并同步更新本文中的描述；不能用旧截图解释新代码，也不能为了让图片“好看”而跳过异常和恢复路径。

十、排错矩阵：从现象反推状态和边界

排错时先记录现象，再定位负责它的状态和事件，不要直接修改样式掩盖问题。下面的矩阵把常见现象、优先检查点和修复方向放在一起，适合在模拟器中逐条复现。

现象	优先检查	处理方向
首屏内容缺失	默认状态、布局权重、滚动范围	先确认状态初始化，再检查容器是否被挤出可视区
点击无变化	事件是否绑定、控件是否可用	记录回调入口和触发前后字段值
结果被旧内容覆盖	异步返回顺序、当前选择	为结果绑定上下文，忽略过期回调
失败后空白	错误分支是否写入反馈	保留已有内容并提供可重试入口
连续操作卡顿	重绘范围、列表复用、定时器释放	缩小状态影响范围并设置资源生命周期

对于 X Component，最有价值的调试记录不是一堆日志，而是一组可以重现的步骤：进入页面、执行动作、观察字段、记录页面差异、恢复默认值。这样下一次修改 source、running 或 「Column」、「Row」、「Text」、「Stack」、「Button」 时，可以快速判断问题来自输入、业务规则、生命周期还是渲染。

十一、回归清单：把一次演示变成可重复验收

建议至少覆盖以下路径：

1. 首次进入页面，确认 「XComponent 容器」、「高性能原生 surface 承载」、「033」、「surface_id: preview_01」、「生命周期：创建 → onLoad 绑定 → onRelease 释放」 和主要内容完整可见。
2. 按正常顺序执行关键操作，确认 「onClick」 的结果留在页面上。
3. 快速重复操作或切换选项，确认旧结果不会覆盖新状态。
4. 覆盖空值、边界值、失败或能力不可用分支，确认反馈可读且有恢复入口。
5. 离开并重新进入页面，确认需要保留的 source、running 没有被无意清空。
6. 放大字体、缩窄宽度并检查滚动，确认布局没有重叠或截断。

回归记录应写清触发条件和观察结果。例如“点击一次后状态变为已完成”比“功能正常”更有用；“失败后保留上一条结果并出现重试按钮”比“异常处理完善”更容易复核。截图、源码和回归记录如果指向同一个状态变化，文章才具备可复现性。

当后续增加字段或入口时，应把新字段加入状态表，把新入口加入操作路径，把新异常加入排错矩阵。不要只在结尾追加一段泛泛的“可扩展”，因为真正的维护成本通常发生在默认值、恢复逻辑和多次连续操作这些细节上。

十二、完整 ArkTS 实现

下面的代码直接取自当前工程的 Index.ets，与前面的状态分析、交互说明和两张运行图保持同一版本。阅读完整代码时，可以先定位状态字段，再定位事件回调，最后确认回调写入的字段是否确实被页面使用。

@Entry
@Component
struct Index { @State source:string='相机预览'; @State running:boolean=true; build(){ Column(){ Row(){Column({space:4}){Text('XComponent 容器').fontSize(24).fontWeight(FontWeight.Bold);Text('高性能原生 surface 承载').fontSize(13).fontColor('#98A2B3')}.layoutWeight(1);Text('033').fontColor('#0F9D7A')}.padding(18).width('100%').backgroundColor('#101827'); Stack({alignContent:Alignment.Center}){Column({space:8}){Text(this.running?'● LIVE':'Ⅱ PAUSED').fontColor(this.running?'#64E6BD':'#FBC66A');Text(this.source).fontSize(22).fontColor(Color.White).fontWeight(FontWeight.Bold);Text('surface_id: preview_01').fontSize(12).fontColor('#AAB6CC')}.alignItems(HorizontalAlign.Center);Text('▣').fontSize(100).fontColor('#355074')}.height(240).width('100%').margin(18).backgroundColor('#121E31').borderRadius(20);Row({space:8}){ForEach(['相机预览','地图引擎','图形渲染'],(v:string)=>{Button(v).layoutWeight(1).fontColor(this.source===v?Color.White:'#0F9D7A').backgroundColor(this.source===v?'#0F9D7A':'#E8F8F2').onClick(()=>this.source=v)})}.padding(18).width('100%');Button(this.running?'暂停原生表面':'恢复原生表面').width('90%').fontColor(Color.White).backgroundColor('#0F9D7A').onClick(()=>this.running=!this.running);Text('生命周期：创建 → onLoad 绑定 → onRelease 释放').fontSize(14).fontColor('#667085').padding(20)}.width('100%').height('100%').backgroundColor('#F5F7FB') } }

代码截图用于快速查看整体实现，代码块用于复制、搜索和逐行核对。两者都不应替代工程内的实际文件；如果源码发生变化，应重新生成代码截图并同步更新文章。

十三、扩展方向：先稳定边界，再接入真实能力

X Component后续可以沿着三条线扩展。第一条是数据线：把当前本地或模拟数据替换成经过校验的真实来源，并保留加载、空数据和失败状态。第二条是能力线：根据 状态管理与页面协作 的边界接入系统服务、网络、存储或设备协同。第三条是体验线：补充无障碍、深色模式、国际化和更细的恢复提示。

把局部状态抽成可测试的状态模型，再接入真实数据源。扩展时仍应保持页面单向数据流：输入进入状态，状态经过规则处理，结果回到可见 UI；外部回调不能绕过这条路径直接修改多个互相不相关的控件。

如果新能力无法在页面中留下稳定的成功、失败或等待反馈，就说明接口和状态边界还没有定义完整。先补齐可验证的结果，再讨论抽象、复用和性能优化，通常比一次性引入大量框架能力更容易维护。

十四、总结

X Component的核心不是堆砌组件或 API，而是让业务目标、页面结构、状态来源、用户操作和结果反馈彼此对应。本文从当前源码提取事实，用初始图证明默认结构，用操作图证明状态变化，再用完整代码把结论落回工程文件。

发布前请再次确认三件事：文章描述的是当前工程真实存在的能力；图片展示的是当前代码可以复现的状态；异常和恢复路径没有被“正常显示”这类空泛表述掩盖。做到这三点，长文才是在解释工程，而不是用篇幅掩盖工程。

十五、状态到画面的映射：每一次变化都要有落点

可以把 X Component 的页面结果整理成一张映射表：输入字段决定用户正在编辑或选择的内容，过程字段决定页面是否显示等待、禁用或进度，结果字段决定成功、空数据和失败提示。映射表的价值在于，它迫使开发者回答“字段变化以后，哪一个组件应该重绘”，避免状态存在却没有任何可见反馈。

如果一个字段会同时改变多个区域，应明确这些区域共享的是同一个权威值，还是各自保存派生结果。共享权威值通常更容易保证一致；派生结果则应在渲染时计算，不能在多个回调里分别维护。对于 source、running，尤其要检查初始值、用户输入、外部回调和重置操作是否可能写入同一字段。

这张映射表也能帮助排查“看起来更新了但页面没变”的问题。先确认回调确实执行，再确认字段值发生变化，最后确认使用该字段的组件没有被条件分支排除。若三步中任何一步不成立，继续调整颜色或间距都不能解决根因。

十六、边界场景推演：把偶然成功变成稳定行为

默认路径通常只覆盖一次进入、一次操作和一次成功。真正容易暴露问题的是边界组合：用户不输入直接提交，连续快速点击，操作过程中切换选项，页面刚离开就收到回调，或者系统字体放大后结果文本变成两行。对 X Component 来说，这些场景都应有明确的状态保留和反馈策略。

边界推演可以按“前置条件—动作—预期结果”记录。例如前置条件是输入为空，动作是点击主要按钮，预期结果应是指出缺少内容且不覆盖上一次有效结果；前置条件是正在处理中，动作是重复点击，预期结果应是阻止重复提交或明确说明当前仍在处理。

对于 状态管理与页面协作，还应把系统条件纳入推演。设备不可用、权限被拒绝、网络超时、存储空间不足和生命周期变化并不是异常日志里的附注，而是用户会遇到的真实路径。页面反馈要告诉用户下一步能做什么，工程记录则保留足够信息供开发者定位。

十七、实现取舍：为什么当前写法适合这个示例

当前页面采用的写法应放回示例目标中理解。它首先追求可运行、可观察和可复现，因此状态字段保持直观，交互入口保持有限，反馈文案直接写在页面附近。这样的结构适合教程和验收，也便于读者把某一行代码与截图中的变化对应起来。

真实产品可能需要进一步拆分：把数据请求移到服务层，把复杂列表抽成子组件，把重复的状态转换抽成纯函数，把错误类型映射成统一的领域结果。但拆分不应改变页面对用户的承诺，仍要保留清晰的加载、成功、空数据、失败和恢复状态。

取舍的判断标准不是代码行数最少，而是修改一个需求时影响范围是否可预测。若更换文案不需要改状态，增加一个结果提示不需要重写输入逻辑，替换数据来源不需要调整布局，那么当前边界就是有效的；反之则应在下一轮迭代中收紧职责。

十八、验证记录模板：让截图、代码和文字对齐

一次合格的验证记录至少包含四项：运行环境、触发前状态、执行动作和触发后差异。运行环境写清设备尺寸、系统版本和字体设置；触发前状态对应初始图；动作使用页面真实文案；触发后差异对应操作图和源码中的状态赋值。

记录不要只保留最终截图，还应写出没有变化的部分。例如切换选项后，选中态和说明文本发生变化，但标题、输入内容和历史记录保持不变。没有变化的内容同样是状态边界的证据，可以防止一次回调意外重置整页。

当验证失败时，先判断是截图采集时机不对、操作路径不完整，还是页面本身没有留下结果。只有确认属于页面逻辑问题后才修改代码；如果只是等待资源或滚动位置造成的误判，应调整采集步骤并重新记录，不能用文字掩盖图片与代码的不一致。

十九、版本演进：修改一处时需要复查哪些地方

修改 X Component 时，可以按“字段—组件—事件—截图—文章”五个对象做影响分析。新增或改名字段会影响状态表和源码说明；组件属性变化会影响首屏或操作图；事件条件变化会影响回归步骤；页面尺寸变化会影响截图；任何可见行为变化都应同步修改正文中的判断。

如果只是调整颜色、间距或字号，也不能完全跳过验证。视觉属性可能改变换行、滚动高度和触控区域，尤其是在系统字体放大或较窄屏幕上。应至少重新检查默认图、操作图和回归清单中的关键动作，确认原有状态证据仍然成立。

版本记录最好包含改动原因、受影响状态、重新采集的图片和未覆盖的风险。这样的记录比“已优化页面”更有价值，因为下一位维护者可以直接知道应该从哪一个状态和哪一张图开始复查。

二十、从示例走向产品：保持可替换与可解释

教程工程和产品工程的差别不在于是否使用更多 API，而在于数据量、并发、权限和失败情况更复杂。将当前页面接入产品时，优先保留可解释的状态流，再逐步替换数据来源；不要一开始就把所有能力塞进页面组件，导致任何异常都只能通过猜测定位。

对于 状态管理与页面协作，可替换性尤其重要。连接、请求、文件、媒体或系统服务都可能在不同设备上不可用，页面应通过明确的接口接收结果，而不是直接读取全局变量或隐式单例。这样既方便测试，也能在能力不可用时展示稳定的降级页面。

可解释性则要求每个关键结果都有来源：标题来自哪一个对象，数量由哪个字段计算，提示由哪个分支写入，截图对应哪个操作。只要这些问题可以从文章、代码和运行结果中互相回答，后续扩展就不会因为“看起来能运行”而积累难以偿还的维护成本。

二十一、数据一致性：默认值、派生值与结果值分开

页面中的数值、标签和提示往往存在派生关系。默认值描述进入页面时的事实，派生值由当前输入或选择计算，结果值则来自一次操作或外部能力返回。三者混用时，重置、返回和失败恢复就会变得含糊；分开后，页面可以明确决定哪些值保留、哪些值重新计算。

对 source、running 的检查可以从写入点开始：初始化写入默认值，输入事件写入原始值，业务动作写入处理中或结果值，恢复动作写回约定的快照。每个写入点都应知道自己是否允许覆盖已有结果，以及覆盖后哪个组件负责展示变化。

当页面需要显示汇总数量、进度或状态文案时，优先在渲染阶段根据权威字段计算，而不是在多个回调中重复维护字符串。这样可以减少一个回调漏更新导致的“数据正确但文字错误”，也能让测试更容易覆盖不同组合。

二十二、交互可达性：让结果不依赖颜色和位置

可操作入口应通过名称、状态和结果文字表达含义，而不能只依赖颜色、图标或视觉位置。对于 「XComponent 容器」、「高性能原生 surface 承载」、「033」、「surface_id: preview_01」、「生命周期：创建 → onLoad 绑定 → onRelease 释放」，需要检查按钮名称是否说明动作，禁用或等待时是否解释原因，完成后是否提供可确认的结果。颜色可以加强层级，但不应成为唯一的成功或失败信号。

输入框和选择控件还要考虑清空、重复提交和焦点变化。用户删除内容后，页面应回到明确的空状态；用户快速切换选项时，旧的结果不能悄悄覆盖新的选择；用户返回页面后，焦点和滚动位置是否恢复也要有一致的策略。

无障碍和大字体验证不是额外装饰。文本变长后仍要能读出当前状态，按钮扩大后仍要能区分相邻动作，错误提示不能只显示一条红线。把这些条件加入回归清单，能够提前发现很多“截图看起来正常、真实使用却难以理解”的问题。

二十三、工程交付：文章、源码和资源保持同一版本

交付时要把 Markdown、ArkTS 源码、运行截图和生成记录看成一个版本单元。文章描述了哪些字段，源码就应存在这些字段；文章引用的图片编号应与工程编号一致；代码截图应来自同一次源码采集。任何一项单独更新，都会让读者在复现时遇到无法解释的差异。

建议在发布前做一次机械核对：读取标题，读取完整代码块，读取三个图片链接，统计正文中文字符数，检查是否存在旧模板短语，再抽取状态字段和事件名称做交叉比对。机械核对不能替代人工阅读，但能快速挡住最常见的遗漏和错配。

当文章需要后续修订时，先更新工程事实，再重新生成截图和正文，最后运行同一组检查。不要先手工改文章、再猜测工程是否仍然一致；事实源越明确，批量维护 250 篇文章的成本越可控。

二十四、最终复盘：用一条路径串起全文

读者读完本文后，应该能够沿着一条路径复现结果：从默认页面找到 「XComponent 容器」、「高性能原生 surface 承载」、「033」、「surface_id: preview_01」、「生命周期：创建 → onLoad 绑定 → onRelease 释放」，执行 「onClick」，观察 source、running 的变化，再用操作图和源码确认结果。若需要排错，可以从排错矩阵回到具体字段和分支，而不是重新通读所有段落。

这条路径也解释了为什么本文保留三张图。初始图说明页面从哪里开始，操作图说明一次关键动作留下什么差异，代码图帮助快速定位实现；它们各自承担不同证据，不在每个小节重复出现。

最终验收以可观察结果为准：默认页面有稳定结构，关键动作改变明确状态，失败分支保留可读反馈，页面离开后不继续写入失效上下文。对 X Component 而言，任何不能同时由截图、源码和回归步骤解释的现象，都应记录为待修问题，而不是用一句“显示正常”带过。

二十五、从字段变化定位重绘范围

source、running 中任一字段变化时，先确认真正依赖它的组件，再判断是否发生了不必要的大范围重绘。

这样既能解释页面为什么变化，也能为性能优化提供具体落点。

二十六、资源释放也属于故障处理

用户需要的是可理解的下一步，开发者需要的是可定位的上下文。权限拒绝、网络超时、设备不可达、数据格式错误和页面生命周期失效，应分别映射到用户提示和内部诊断信息；不能把堆栈、路径或敏感参数直接放进页面。

在 状态管理与页面协作 场景下，故障分层尤其重要。页面反馈应说明“暂时不可用、数据仍保留、可以重试”还是“需要先完成授权”；工程日志则记录能力名称、请求标识、状态转换和时间点。两者职责不同，但都必须能回到同一个失败分支。

复现故障时，优先固定前置条件，再只改变一个变量。例如先固定输入和选项，再模拟一次超时；先固定页面状态，再执行返回或重入。这样得到的结论才可以写进排错矩阵，并在下一次版本中自动回归。

二十七、从失败结果反推设计缺口

在 状态管理与页面协作 场景中，失败结果往往比成功结果更能暴露设计问题。请分别模拟 「onClick」 的输入不足、能力不可用和重复触发，记录页面是否仍然保留 source、running 的有效部分。

如果三种失败都只显示同一句提示，说明错误分类还不够；如果失败后页面变空，说明结果数据与反馈状态没有分离。

二十八、维护者真正需要的检查顺序

下一位维护者接手 X Component 时，应先看状态表，再看事件入口，最后看两张运行图。这个顺序能快速回答：默认值是什么、哪一个动作改变了什么、操作结果是否被截图证明。

不要从标题或颜色开始猜业务含义，先沿着 source、running 的赋值点查找使用点，能够明显减少误改。

二十九、结语：把一次演示变成可交接的工程

当 X Component 的页面、代码和验证记录能够相互解释时，它就不再是一次性的演示。后续接入真实数据、权限或设备能力时，可以沿用同一条状态和反馈链路。

这也是本文保留完整代码与运行图的原因：读者可以复现，维护者可以定位，发布者可以核对版本。

维护备忘：先改事实源

修改 X Component 时，先更新工程事实，再重新采集图片和文章。这样可以避免文字、截图和 source、running 的实际来源逐渐分离。事实源包括状态字段、默认值、事件回调、条件分支和页面可见文案；任何一项发生变化，都要判断是否影响初始图、操作图、代码截图和回归清单。批量文章维护尤其不能依靠人工记忆，应该让生成脚本从当前 Index.ets 读取代码和关键文案，再由人工检查主题表达是否自然。

读者练习：替换一个输入（补充）

可以只替换 X Component 的一项输入，然后按照 source、running 的写入点检查页面变化。一次只改一个变量，最容易看出当前实现的真实边界。练习时先保留原始截图，再生成替换后的运行结果，比较哪些区域应该变化、哪些区域不应变化；如果替换输入后页面出现与业务无关的重置，说明状态之间存在隐式耦合。这个练习也能帮助读者判断哪些代码适合抽成纯函数，哪些逻辑必须留在页面生命周期内。

追加验收说明：把差异写成证据

对 X Component 的最终检查不应只关注页面是否“看起来正常”，而要把差异写成可以复核的证据。进入页面时记录默认的 source、running，执行一次 「onClick」 后记录改变的字段、保持不变的区域和反馈出现的位置；如果涉及 状态管理与页面协作 的外部条件，还要记录条件成立、条件缺失和恢复后的三种结果。这样的证据描述能够区分初始化问题、事件问题、状态覆盖问题和布局问题，也能避免后续维护时根据一张旧截图猜测当前代码。发布前再将文章中的描述、Markdown 图片链接、代码块和工程文件逐项比对，确认它们指向同一版本。

复现补记：保留一次完整路径

保留一条完整复现路径即可说明 X Component 的核心行为：从默认页面开始，按照真实文案操作，观察 source、running 的变化，遇到失败时记录用户提示，恢复后再次确认结果没有被错误覆盖。路径中的每一步都应能在当前源码中找到对应状态或回调，图片则用于证明其中最关键的两个时刻。

复查清单：交付前再走一遍

最后再走一遍默认、操作、失败和恢复四条路径，确认 X Component 的文字、状态与图片仍然相互对应。默认路径要确认首屏内容和初始值，操作路径要确认 「onClick」 确实写入了预期字段，失败路径要确认用户提示不会泄露技术细节，恢复路径要确认旧结果不会覆盖新状态。若页面涉及滚动、输入或资源释放，还应在大字体、窄屏和快速重复操作下再看一次。