企业官网建设流程全解析

前言

在 ArkUI 中，router.pushUrl/router.replaceUrl是页面跳转的核心 API，但很多人会遇到「页面找不到」的错误，原因往往是main_pages.json中漏注册了页面。本篇以小分享 App 的 16 个页面为例，深入讲解路由表的配置与维护。详细 API 可参考 HarmonyOS Router 官方文档。

一、完整配置

1.1 main_pages.json 全文

小分享 App 的entry/src/main/resources/base/profile/main_pages.json如下：

{ "src": [ "pages/Index", "pages/SplashPage", "pages/HomePage", "pages/CreateSelectPage", "pages/TextEditPage", "pages/PreviewPage", "pages/TemplateSelectPage", "pages/ImageEditPage", "pages/LinkEditPage", "pages/SharePreviewPage", "pages/FavoritesPage", "pages/ProfilePage", "pages/DiscoverPage", "pages/TemplateDetailPage", "pages/MoreFunctionsPage", "pages/SettingsPage" ] }

1.2 文件结构

整个文件只有一个src数组，列出所有可访问的页面。每个路径必须以pages/开头，且不带.ets后缀。

提示：DevEco Studio 新建 Page 时会自动追加到此文件，但手动复制 Page 文件时务必同步更新。

二、页面路径规则

2.1 不带后缀

"pages/Index" ✅ "pages/Index.ets" ❌

src数组中的路径不需要.ets后缀，系统会自动映射到entry/src/main/ets/pages/Index.ets。

2.2 前缀必须为 pages

"pages/HomePage" ✅ "HomePage" ❌ "subpages/DetailPage" ❌

ArkUI 默认约定页面位于src/main/ets/pages/目录下，路径前缀固定为pages/。

2.3 子目录页面

若把页面放在pages/profile/SettingsPage.ets，则src数组需要写成：

"src": [ "pages/profile/SettingsPage" ]

跳转时也要带上完整路径：

router.pushUrl({ url: 'pages/profile/SettingsPage' });

三、跳转 API 对比

3.1 四大路由 API

HarmonyOS 提供四种核心路由 API：

3.2 小分享 App 的典型用法

小分享 App 的典型用法如下：

// SplashPage 跳到 HomePage：用 replaceUrl，避免返回时回到启动页 aboutToAppear(): void { setTimeout(() => { router.replaceUrl({ url: 'pages/HomePage' }); }, 2000); } // HomePage 跳到 TextEditPage：用 pushUrl，保留返回入口 router.pushUrl({ url: 'pages/TextEditPage' }); // 编辑页返回上一级 router.back();

3.3 路由选型建议

路由选型建议如下：

1. 启动页跳首页：用replaceUrl，避免返回启动页
2. 列表页跳详情页：用pushUrl，保留返回入口
3. 表单页跳成功页：用replaceUrl，避免返回修改
4. 底部 Tab 切换：用replaceUrl，避免路由栈膨胀

四、main_pages.json 的两种生成方式

4.1 方式 1：DevEco Studio 自动注册

在 DevEco Studio 中新建 Page 时，IDE 会自动把页面路径追加到main_pages.json。这是最推荐的方式。

4.2 方式 2：手动维护

某些场景下，开发者会手动复制 Page 文件，此时必须手动修改main_pages.json，否则跳转会失败。

提示：建议在工程根目录配置 git pre-commit 钩子，校验main_pages.json与实际 Page 文件的一致性。

五、跳转失败的常见原因

5.1 原因 1：页面未注册

router.pushUrl({ url: 'pages/NewPage' }); // 报错：page not found

解决：把"pages/NewPage"加入main_pages.json的src数组。

5.2 原因 2：路径大小写不匹配

router.pushUrl({ url: 'pages/Homepage' }); // ❌ 实际文件名是 HomePage

HarmonyOS 路径区分大小写，必须与文件名完全一致。

5.3 原因 3：路由栈溢出

ArkUI 默认路由栈上限为 32。当页面深度过大时（如无限详情页嵌套），会出现：

The route stack cannot exceed 32 pages

解决：使用router.replaceUrl替代pushUrl，或使用Navigation组件实现无限层路由。

六、带参数跳转

6.1 params 传递参数

router.pushUrl支持params字段传递参数：

router.pushUrl({ url: 'pages/TemplateDetailPage', params: { templateId: 'ink-001', title: '水墨古风' } });

6.2 目标页接收参数

目标页通过router.getParams()获取：

aboutToAppear(): void { const params = router.getParams() as Record<string, string>; this.templateId = params.templateId; this.title = params.title; }

提示：getParams()返回Object，必须做类型断言，否则在严格模式下会编译失败。

七、本篇核心知识点

7.1 main_pages.json 核心规则

main_pages.json 核心规则总结如下：

1. 路径不带后缀
2. 前缀固定为pages/
3. 子目录页面需带完整路径
4. 路径区分大小写

7.2 路由 API 选型

路由 API 选型建议如下：

• pushUrl：入栈跳转，保留返回入口
• replaceUrl：替换当前页，避免返回
• back：出栈返回
• clear：清空栈

7.3 实战开发要点

实战开发中需要重点关注以下几个要点：

• 跳转失败通常是路径写错或漏注册
• 复杂嵌套场景建议使用Navigation组件
• 带参数跳转用params字段
• 目标页用router.getParams()接收参数

总结

本文深入剖析了 HarmonyOS main_pages.json 路由表的配置规则，结合小分享 App 的 16 个页面讲解了路径规范、跳转 API 对比、常见陷阱、带参数跳转等关键知识点。下一篇我们将看app.json5全局配置，理解 bundleName、版本号等元数据。

附录：完整实现细节

1. 核心 API 参考

2. 完整代码示例

// 核心功能代码 // 详见正文中的完整实现

3. 常见问题排查

4. 最佳实践

1. 错误处理完善，使用 try/catch 包裹
2. 资源及时释放，避免内存泄漏
3. 异步操作使用 async/await
4. 权限配置完整，按需申请

5. 完整代码文件索引

6. 实现要点总结

核心实现要点：

1. API 的正确使用方法和参数说明
2. 完整的代码实现流程
3. 常见问题的排查方案
4. 性能优化和安全建议

7. 总结

本文详细讲解了小分享 App 中对应功能的完整实现。通过本文的学习，读者可以掌握 HarmonyOS 开发的核心 API 使用方法和最佳实践。

开发注意事项

1. API 版本兼容性

确保使用的 API 在目标 SDK 版本中可用。不同版本的 HarmonyOS 可能对 API 的支持有所不同，建议查阅官方文档确认。

2. 权限配置

根据功能需求配置相应的系统权限。权限在 module.json5 中声明，运行时通过 abilityAccessCtrl 申请。

3. 错误处理

所有异步操作使用 try/catch 包裹，确保异常不会导致应用崩溃。错误信息通过 hilog 输出，便于调试。

4. 资源释放

使用完毕后及时释放系统资源，避免内存泄漏。例如：文件操作后关闭文件句柄，数据库操作后关闭 ResultSet。

5. 性能优化

避免在主线程执行耗时操作，使用异步 API 处理耗时任务。大量数据渲染时使用 LazyForEach 懒加载。

完整代码文件索引

核心 API 参考

总结

本文详细讲解了小分享 App 中对应功能的完整实现，涵盖 API 使用、代码示例、常见问题、性能优化等核心知识点。通过本文的学习，读者可以掌握 HarmonyOS 开发的完整流程。

如果这篇文章对你有帮助，欢迎点赞👍、收藏⭐、关注🔔，你的支持是我持续创作的动力！