阅读时长约 18 分钟 | 难度★★★★☆ | 篇章第 1 篇 · 项目架构与设计哲学 对应源码entry/src/main/ets/entryability/EntryAbility.ets、entrybackupability/EntryBackupAbility.ets前言在 HarmonyOS Stage 模型下Ability是应用的功能载体。一个应用可以包含一个或多个 UIAbility每个 UIAbility 实例对应一个任务。玄象项目作为单入口应用采用了“一个 EntryAbility 一个 EntryBackupAbility 扩展能力“的最小化设计。本篇将深入剖析玄象项目的 Ability 设计决策何时该用单 Ability、何时该拆分多 Ability、备份扩展能力如何接入。提示Ability 数量直接决定了应用的任务管理行为、跨设备迁移能力、内存占用水平。错误的 Ability 拆分策略会导致用户体验割裂。一、Ability 分类与玄象项目选择1.1 HarmonyOS Ability 分类HarmonyOS 提供两类 Ability类型职责是否有 UI典型场景UIAbility包含 UI 界面的能力是主入口、设置页、独立功能区ExtensionAbility无 UI 的扩展能力否备份、卡片服务、输入法1.2 玄象项目的 Ability 配置玄象项目在module.json5中声明了 2 个 Ability{ abilities: [ { name: EntryAbility, srcEntry: ./ets/entryability/EntryAbility.ets, description: $string:EntryAbility_desc, icon: $media:layered_image, label: $string:EntryAbility_label, startWindowIcon: $media:startIcon, startWindowBackground: $color:start_window_background, exported: true, skills: [ { entities: [entity.system.home], actions: [ohos.want.action.home] } ] } ], extensionAbilities: [ { name: EntryBackupAbility, srcEntry: ./ets/entrybackupability/EntryBackupAbility.ets, type: backup, exported: false, metadata: [ { name: ohos.extension.backup, resource: $profile:backup_config } ] } ] }1.3 选择单 UIAbility 的考量玄象项目选择单一 EntryAbility的核心考量单入口应用玄象所有功能均从首页九宫格进入无独立入口。统一任务栈所有页面在同一任务中返回行为一致。简化生命周期单一 Ability 减少生命周期回调的复杂度。降低内存占用多 Ability 会创建多任务实例增加内存压力。提示如果玄象未来推出“独立罗盘“功能希望用户从桌面直接进入罗盘界面而非通过首页此时应该新增一个LuopanAbility。二、EntryAbility 深度解析2.1 完整源码import { AbilityConstant, ConfigurationConstant, UIAbility, Want } from kit.AbilityKit; import { hilog } from kit.PerformanceAnalysisKit; import { window } from kit.ArkUI; const DOMAIN 0x0000; export default class EntryAbility extends UIAbility { onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void { try { this.context.getApplicationContext().setColorMode(ConfigurationConstant.ColorMode.COLOR_MODE_NOT_SET); } catch (err) { hilog.error(DOMAIN, testTag, Failed to set colorMode. Cause: %{public}s, JSON.stringify(err)); } hilog.info(DOMAIN, testTag, %{public}s, Ability onCreate); } onDestroy(): void { hilog.info(DOMAIN, testTag, %{public}s, Ability onDestroy); } onWindowStageCreate(windowStage: window.WindowStage): void { hilog.info(DOMAIN, testTag, %{public}s, Ability onWindowStageCreate); windowStage.loadContent(pages/Index, (err) { if (err.code) { hilog.error(DOMAIN, testTag, Failed to load the content. Cause: %{public}s, JSON.stringify(err)); return; } hilog.info(DOMAIN, testTag, Succeeded in loading the content.); }); } onWindowStageDestroy(): void { hilog.info(DOMAIN, testTag, %{public}s, Ability onWindowStageDestroy); } onForeground(): void { hilog.info(DOMAIN, testTag, %{public}s, Ability onForeground); } onBackground(): void { hilog.info(DOMAIN, testTag, %{public}s, Ability onBackground); } }2.2 import 语句解析import { AbilityConstant, ConfigurationConstant, UIAbility, Want } from kit.AbilityKit; import { hilog } from kit.PerformanceAnalysisKit; import { window } from kit.ArkUI;玄象项目引入了三个 KitKit用途玄象使用kit.AbilityKitAbility 能力UIAbility基类、Want参数kit.PerformanceAnalysisKit性能分析hilog日志kit.ArkUIArkUI 框架window.WindowStage2.3 DOMAIN 日志域const DOMAIN 0x0000;玄象项目使用0x0000作为日志域。hilog是 HarmonyOS 的官方日志系统通过DOMAIN与tag双重标识日志来源。提示生产环境建议为不同模块分配不同的DOMAIN如 0x0001 为入口、0x0002 为星宿模块便于日志过滤与排查。2.4 onCreate 初始化onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void { try { this.context.getApplicationContext().setColorMode(ConfigurationConstant.ColorMode.COLOR_MODE_NOT_SET); } catch (err) { hilog.error(DOMAIN, testTag, Failed to set colorMode. Cause: %{public}s, JSON.stringify(err)); } hilog.info(DOMAIN, testTag, %{public}s, Ability onCreate); }玄象项目在onCreate中做了两件事设置颜色模式调用setColorMode(COLOR_MODE_NOT_SET)表示跟随系统颜色模式。输出日志记录 Ability 创建事件。try-catch包裹的意义setColorMode在某些低版本系统上可能抛出异常玄象项目通过try-catch防止应用崩溃。这是 HarmonyOS 应用兼容性处理的典型范式。2.5 onWindowStageCreate 加载首页onWindowStageCreate(windowStage: window.WindowStage): void { hilog.info(DOMAIN, testTag, %{public}s, Ability onWindowStageCreate); windowStage.loadContent(pages/Index, (err) { if (err.code) { hilog.error(DOMAIN, testTag, Failed to load the content. Cause: %{public}s, JSON.stringify(err)); return; } hilog.info(DOMAIN, testTag, Succeeded in loading the content.); }); }onWindowStageCreate是 UIAbility 最关键的回调玄象项目在此加载首页pages/Index。loadContent回调规范检查 err.code非 0 表示加载失败。错误日志用JSON.stringify(err)输出完整错误信息。成功日志记录加载成功事件。提示玄象项目的pages/Index内部用Navigation包裹了SplashPage启动页加载完后replaceUrl到HomePage。这种“启动页 → 首页“的 3 秒过渡是玄象项目精心设计的用户体验。三、EntryBackupAbility 备份扩展能力3.1 完整源码import { hilog } from kit.PerformanceAnalysisKit; import { BackupExtensionAbility, BundleVersion } from kit.CoreFileKit; const DOMAIN 0x0000; export default class EntryBackupAbility extends BackupExtensionAbility { async onBackup() { hilog.info(0x0000, testTag, onBackup ok); await Promise.resolve(); } async onRestore(bundleVersion: BundleVersion) { hilog.info(0x0000, testTag, onRestore ok %{public}s, JSON.stringify(bundleVersion)); await Promise.resolve(); } }3.2 BackupExtensionAbility 的作用BackupExtensionAbility是 HarmonyOS 提供的云端备份扩展能力允许应用在系统备份/恢复时介入处理onBackup系统备份时回调应用可在此保存关键状态。onRestore系统恢复时回调应用可在此恢复数据并处理版本迁移。3.3 备份配置文件玄象项目在module.json5中引用了$profile:backup_config该配置文件位于resources/base/profile/backup_config.json{ allowToBackupRestore: true }配置项说明字段类型说明allowToBackupRestoreboolean是否允许备份恢复提示玄象项目当前onBackup/onRestore仅输出日志未做实质性数据处理。未来可在onBackup中保存用户偏好如主题色、字体大小在onRestore中恢复这些偏好。四、UIAbility 生命周期详解4.1 生命周期总览玄象项目 EntryAbility 实现了全部 6 个生命周期回调应用启动 ↓ onCreate ← Ability 创建初始化配置 ↓ onWindowStageCreate ← 窗口创建加载首页 ↓ [用户使用应用] ↓ onForeground ← 切到前台 ↓ onBackground ← 切到后台 ↓ [用户切回应用] ↓ onWindowStageDestroy ← 窗口销毁 ↓ onDestroy ← Ability 销毁4.2 生命周期回调清单回调触发时机玄象用途典型操作onCreateAbility 创建设置颜色模式全局配置初始化onDestroyAbility 销毁输出日志资源释放onWindowStageCreate窗口创建加载pages/IndexloadContentonWindowStageDestroy窗口销毁输出日志UI 资源释放onForeground切到前台输出日志恢复计时器、刷新数据onBackground切到后台输出日志暂停计时器、保存状态4.3 玄象项目生命周期最佳实践玄象项目在生命周期回调中遵循以下原则onCreate只做轻量初始化避免阻塞应用启动。onWindowStageCreate加载首页使用loadContent异步加载。onForeground/onBackground处理状态切换恢复/暂停计时器。onDestroy释放资源清理定时器、关闭文件句柄。五、Want 与启动参数5.1 Want 的概念Want是 HarmonyOS 中描述“想要做什么“的对象用于 Ability 间通信。玄象项目的 EntryAbility 通过skills字段声明可接收的 Wantskills: [ { entities: [entity.system.home], actions: [ohos.want.action.home] } ]5.2 Want 的核心字段字段类型说明bundleNamestring目标应用包名abilityNamestring目标 Ability 名称uristring数据 URItypestring数据 MIME 类型actionstring操作类型entitiesstring[]实体类别parametersRecord自定义参数5.3 onCreate 中接收 Want玄象项目在onCreate中接收want参数onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void { // want.parameters 可获取外部传入的参数 // 玄象项目当前未使用 want 参数 // ... }提示如果玄象未来支持“通过通知跳转到特定星宿详情页“可在通知的 Want 中携带mansionId参数EntryAbility 在onCreate中读取并传给首页。六、context 上下文的能力访问6.1 context 的核心作用this.context是 UIAbility 的上下文对象提供应用级能力访问this.context.getApplicationContext().setColorMode(...);6.2 context 提供的关键 APIAPI用途getApplicationContext()获取应用级上下文getFilesDir()获取应用文件目录getCacheDir()获取缓存目录getExternalFilesDir()获取外部存储目录requestPermissionsFromUser()动态申请权限terminateSelf()销毁自身6.3 玄象项目对 context 的使用玄象项目当前仅在onCreate中通过context.getApplicationContext()设置颜色模式。未来在 GPS 风水、AI 拍照风水等功能中将更频繁地使用context.requestPermissionsFromUser()动态申请权限。七、单 Ability vs 多 Ability 决策矩阵7.1 何时选择单 UIAbility玄象项目选择单 UIAbility 的场景统一入口应用所有功能从首页进入。强关联页面页面间跳转频繁需要统一任务栈。共享状态页面间共享全局状态如登录态。资源节约减少多 Ability 创建的开销。7.2 何时选择多 UIAbility适合拆分多 UIAbility 的场景场景拆分理由独立功能入口用户可直接从桌面进入特定功能独立任务管理不同功能需要独立任务栈跨设备迁移不同功能需要独立迁移权限隔离不同功能需要不同权限集7.3 玄象项目的未来 Ability 拆分设想玄象项目若未来推出以下功能应考虑拆分多 UIAbilityLuopanAbility独立罗盘功能用户从桌面直接进入罗盘。WidgetAbility桌面卡片服务提供每日宜忌卡片。AssistantAbilityAI 助手独立任务便于多窗口协同。提示Ability 拆分是架构演进的核心议题。玄象项目当前阶段保持单 UIAbility 是合理决策未来扩展时再按需拆分。八、EntryAbility 与 EntryBackupAbility 的协同8.1 协同关系图[应用启动] ↓ EntryAbility.onCreate() ↓ EntryAbility.onWindowStageCreate() ↓ loadContent(pages/Index) ↓ [SplashPage 3 秒后] → [HomePage 渲染] ↓ [用户使用应用] ↓ [系统触发云备份] ↓ EntryBackupAbility.onBackup() ↓ [系统触发云恢复] ↓ EntryBackupAbility.onRestore()8.2 数据备份范围玄象项目未来可在onBackup中备份以下数据用户偏好主题色、字体大小、提醒开关。历史记录八字命盘、起卦历史、AI 对话记录。会员信息会员等级、到期时间、购买记录。8.3 版本迁移处理onRestore(bundleVersion)接收BundleVersion参数玄象项目可在此处理版本迁移async onRestore(bundleVersion: BundleVersion) { if (bundleVersion.versionCode 1000002) { // 旧版本数据迁移逻辑 await this.migrateOldData(); } await Promise.resolve(); }总结本篇以玄象项目EntryAbility与EntryBackupAbility为蓝本深入剖析了 HarmonyOS 应用 Ability 设计的取舍决策单 UIAbility 的优势、EntryAbility 生命周期、EntryBackupAbility 备份扩展能力以及未来多 Ability 拆分的设想。掌握这些决策框架能让您在面对不同业务场景时做出合理的 Ability 设计。下一篇《07 · code-linter.json5 配置ArkTS 严格模式下的代码规范》将带您深入玄象项目的代码静态检查体系。如果篇文章对你有帮助欢迎点赞、收藏⭐、关注你的支持是我持续创作的动力相关资源HarmonyOS 官方文档UIAbility 组件HarmonyOS 官方文档BackupExtensionAbilityHarmonyOS 官方文档WantHarmonyOS 官方文档Context 上下文开源鸿蒙跨平台社区https://openharmonycrossplatform.csdn.net