纹渊 HarmonyOS 7 工程实战（17）：模块化拆分 Index 页的第一步

一、先把 Index 从“全能页面”改成编排入口一个 ArkUI 首页同时承载首页图谱、创作工坊、收藏历史、主题切换、AI 请求、文件导出和跨设备接续时最先恶化的通常不是运行速度而是变更的可预测性。新增一个按钮可能碰到主题字段调整创作步骤可能影响导出状态页面返回又会触发多组异步恢复。页面代码越长越难回答“哪个状态属于谁、失败由谁处理、哪个组件可以独立验证”。渐进拆分的第一步不是立即套一层庞大的架构而是让 Index 只保留三种职责接收页面级事件、持有跨区域状态、组合可复用视图。纯展示交给组件业务动作交给服务连续步骤交给可观察模型。这样每抽走一块页面行为都能保持不变回归范围也足够清晰。二、用责任矩阵找到第一批切口拆分前先按“变化原因”分类而不是按代码行数机械切文件。搜索框和筛选按钮一起变化适合成为头部组件轮播只关心页码和主题适合独立纹样卡片只接收数据和回调创作工坊的步骤、选中纹样、载体和导出格式则应该由一个状态模型维护。区域Index 保留什么下沉后的边界页面壳当前标签、断点、主题、页面路由只决定显示哪个区域头部与卡片传入属性、接收回调组件不读取页面私有字段创作流程持有一个状态模型所有阶段迁移集中在模型方法数据与系统能力触发动作、消费结果存储、分享、图库、网络由服务封装这张矩阵能避免一种常见的“假拆分”把一大段 UI 挪到新组件却仍让它读取十几个全局字段和直接调用系统能力。文件变多不等于边界变清楚依赖方向才是判断标准。三、先抽出可观察的创作状态模型创作工坊包含选纹样、选载体、渲染、选择格式和导出五类动作。若页面在多个点击回调里分别修改步骤编号、选中 ID 和导出格式很容易出现步骤已前进但阶段未同步的组合状态。集中迁移方法后每个动作都只有一个入口。export enum WorkshopPhase { IDLE 0, PATTERN_SELECTED 1, PRODUCT_SELECTED 2, RENDERED 3, READY_TO_EXPORT 4, EXPORTED 5 } Observed export class WorkshopStateModel { phase: WorkshopPhase WorkshopPhase.IDLE patternId: number 0 productId: string cup exportFormat: string workshopStepIndex: number 0 selectPattern(id: number): void { this.patternId id this.phase WorkshopPhase.PATTERN_SELECTED } confirmProduct(): void { this.workshopStepIndex 2 this.phase WorkshopPhase.RENDERED } }模型只描述业务状态不保存页面上下文也不弹提示。它因此可以被首页、详情返回和自动化入口共同驱动。页面只需观察模型字段避免同一业务事实出现多个真相源。四、组件接口只暴露最小输入与事件头部组件需要搜索文本、主题和断点信息还要把筛选动作通知页面。这里适合用Link表达双向文本用Prop表达只读样式用函数回调表达事件。组件不知道筛选抽屉如何实现也不直接切换页面状态。Component export struct AppHeader { Link searchText: string Prop isDark: boolean false Prop isTabletLayout: boolean false headingText: string 纹渊 subtitle: string 天工开物创作工坊 onActionClick: () void () {} build() { Column() { Row() { Column() { Text(this.headingText) Text(this.subtitle) } .layoutWeight(1) Button(筛选) .onClick(() this.onActionClick()) } if (!this.isTabletLayout) { TextInput({ text: this.searchText, placeholder: 搜索纹样… }) .onChange((value: string) this.searchText value) } } } }组件接口越小页面越容易替换布局。平板可以隐藏搜索框、把筛选移到侧栏手机仍使用顶部输入框而业务筛选逻辑不需要复制。五、系统能力通过结果模型回到页面文件导出、图库保存、网络请求和跨设备迁移都有失败路径。把这些逻辑直接写进点击回调页面会同时处理参数校验、异步调用、异常分类和提示文案。更稳妥的做法是让服务返回结构化结果页面只映射为加载态、成功态或可重试错误。export type ExportResult | { ok: true; uri: string; format: string } | { ok: false; reason: invalid_format | write_failed } export async function exportWork( snapshot: PixelMap, format: string ): PromiseExportResult { if (format ! png format ! jpg) { return { ok: false, reason: invalid_format } } try { const uri await encodeAndSave(snapshot, format) return { ok: true, uri, format } } catch (_) { return { ok: false, reason: write_failed } } }服务不引用任何 UI 组件页面也不需要知道编码器细节。以后增加 WebP 或更换图库接口时变更集中在服务和结果映射不会扩散到每个按钮。六、生命周期只做装配避免异步结果覆盖新状态页面出现时需要加载收藏、历史、主题和同步开关。多个任务并行可以缩短首屏等待但旧任务晚返回时不能覆盖用户刚刚修改的状态。给装载过程增加版本号是一种成本很低的保护方式。State loading: boolean false private loadVersion: number 0 async reloadPageState(): Promisevoid { const version this.loadVersion this.loading true const [favorites, recent, theme] await Promise.all([ loadFavorites(), loadRecentItems(), loadThemeMode() ]) if (version ! this.loadVersion) { return } this.favoriteIds favorites this.recentIds recent this.applyThemeMode(theme) this.loading false } aboutToDisappear(): void { this.loadVersion stopDeviceListener() }装配方法负责启动任务和写回页面级字段订阅解除也在同一生命周期成对出现。这样既避免重复监听也能解释返回页面后为什么不会出现陈旧结果闪回。七、Index 最终只组合区域和传递意图当状态模型、组件和服务边界建立后页面构建函数应该能直接读出信息架构。下面的组合代码没有存储细节和系统 API只描述头部、轮播、分类和卡片如何协作。Builder HomeTab() { List() { ListItem() { AppHeader({ searchText: $searchText, isDark: this.isDark, isTabletLayout: this.isTabletLayout, onActionClick: () this.filterVisible true }) } ListItem() { BannerCarousel({ isDark: this.isDark, isTabletLayout: this.isTabletLayout }) } ListItem() { PatternGrid({ items: this.filteredPatterns(), onSelect: (id: number) this.workshop.selectPattern(id) }) } } }依赖方向允许应避免页面到组件属性、链接、回调组件反向获取整页实例页面到模型调用明确的迁移方法分散修改多个阶段字段页面到服务传入参数、处理结果在回调里复制服务实现服务到系统能力封装平台调用服务直接弹 UI 提示八、按行为而不是按文件做回归拆分不应改变用户行为。回归时要同时覆盖正常链路、状态恢复和断点布局尤其关注组件移动后丢失的绑定关系以及异步服务返回后是否仍更新正确区域。场景操作通过信号搜索筛选输入关键词并切换类别卡片集合同步变化清空后恢复创作步骤选择纹样、载体并生成阶段与步骤指示保持一致页面返回从详情返回并进入创作选中项仍正确不重复订阅主题切换明暗主题各切换一次头部、卡片和背景同时更新窗口变化手机与平板宽度互换组件重排但业务状态不丢失异步失败让导出或网络动作失败提示可理解按钮可继续操作HarmonyOS 状态管理的观察与传递规则可参考状态管理概述。拆分时只要持续检查单一真相源、最小组件接口和成对生命周期页面规模就能逐步下降而不必一次性重写。九、总结模块化拆分 Index 页的第一步是把“渲染、状态、业务动作、系统能力”四类责任分开。可观察模型保证阶段一致组件用最小接口表达 UI服务把失败收敛为结果页面回到编排角色。这样的渐进拆分每次都能独立验收既降低大页面的变更风险也为后续继续抽取首页、创作工坊和个人中心留下稳定边界。