HarmonyOS Stage 模型架构解析与应用指南

2. WindowStage：窗口管理中枢

WindowStage 代表一个应用窗口实例，负责加载页面内容、管理窗口属性（大小、透明度、焦点）及处理窗口生命周期事件。

// 在 UIAbility 中获取并配置 WindowStage
onWindowStageCreate(windowStage: window.WindowStage) {
  const mainWindow = windowStage.getMainWindowSync();
  mainWindow.setWindowBackgroundColor('#FFFFFF');
  windowStage.loadContent('pages/Index', (err) => { /* ... */ });
}

典型应用场景：全屏游戏设置、悬浮窗创建、多窗口协同管理。

3. Context：上下文获取桥梁

Context 是访问系统服务、资源与能力的统一入口。在 ArkTS 页面组件中，可通过 getContext(this) 获取。

import common from '@ohos.app.ability.common';
import { getContext } from '@kit.ArkUI';

@Entry
@Component
struct MyPage {
  build() {
    Column() {
      Button("获取上下文信息").onClick(() => {
        const context = getContext(this) as common.UIAbilityContext;
        const config = context.config;
        console.info(`Screen: ${config.screenWidth} x ${config.screenHeight}`);
      })
    }
  }
}

关键 API：

• getContext(this)：在 @Component 中安全获取上下文（this 必须为组件实例）。
• context.config：获取设备配置（屏幕宽高、DPI、语言等）。
• context.getUIAbility()：获取当前 UIAbility 实例。
• context.resourceManager：访问字符串、图片等本地资源。

三、项目结构文件详解

Stage 模型引入了新的配置文件体系，取代了 FA 模型的 config.json。

1. main_pages.json：页面路由清单

路径：src/main/resources/base/profile/main_pages.json

{
  "src": [
    "pages/Index",
    "pages/Detail"
  ]
}

作用：声明所有可被 loadContent() 加载的页面路径（相对于 src/main/ets）。必须显式注册，否则加载会失败。建议按功能模块组织路径。

2. module.json5：模块级配置

路径：src/main/module.json5

{
  "module": {
    "name": "entry",
    "type": "entry",
    "description": "$string:module_desc",
    "mainElement": "EntryAbility",
    "deviceTypes": ["phone", "tablet"],
    "deliveryWithInstall": true,
    "installationFree": false,
    "pages": "$profile:main_pages",
    "abilities": [
      {
        "name": "EntryAbility",
        "srcEntry": "./ets/UIAbility.ts",
        "description": "$string:EntryAbility_desc",
        "icon": "$media:icon",
        "label": "$string:EntryAbility_label",
        "startWindowIcon": "$media:icon",
        "startWindowBackground": "$color:start_window_background",
        "exported": true,
        "skills": [
          {
            "entities": ["entity.system.home"],
            "actions": ["action.system.home"]
          }
        ]
      }
    ]
  }
}

关键字段：mainElement 指定入口 Ability 类名；pages 引用路由清单；abilities 数组定义模块包含的能力。

3. build-profile.json5：构建配置

路径：项目根目录 /build-profile.json5

{
  "app": {
    "signingConfigs": [],
    "products": [
      {
        "name": "default",
        "signingConfig": "default",
        "compatibleSdkVersion": "6.0.2(22)",
        "runtimeOS": "HarmonyOS"
      }
    ]
  }
}

作用：指定兼容的 SDK 版本、配置签名与产品变体。需确保 compatibleSdkVersion 与开发环境匹配。

四、实战：获取屏幕尺寸与窗口信息

场景：在页面中动态获取屏幕宽高并更新 UI。

import window from '@ohos.window';
import common from '@ohos.app.ability.common';
import { getContext } from '@kit.ArkUI';

@Entry
@Component
struct ScreenInfoPage {
  @State screenWidth: number = 0;
  @State screenHeight: number = 0;
  @State windowMode: string = '未知';

  aboutToAppear(): void {
    setTimeout(() => this.updateScreenInfo(), 300);
  }

  updateScreenInfo(): void {
    try {
      const context = getContext(this) as common.UIAbilityContext;
      if (!context) {
        console.error('获取 Context 失败');
        return;
      }

      const windowStage = context.windowStage;
      if (windowStage) {
        const mainWindow = windowStage.getMainWindowSync();
        const windowProperties = mainWindow.getWindowProperties();
        this.screenWidth = windowProperties.windowRect.width;
        this.screenHeight = windowProperties.windowRect.height;
      }

      if (context.abilityInfo) {
        console.info('UIAbility name:', context.abilityInfo.name);
      }
    } catch (e) {
      console.error('更新屏幕信息失败:', JSON.stringify(e));
    }
  }

  build() {
    Column() {
      Text(`屏幕尺寸：${this.screenWidth} x ${this.screenHeight}`)
        .fontSize(18)
      Text(`窗口模式：${this.windowMode}`)
        .fontSize(16)
        .margin({ top: 10 })
      Button("刷新信息")
        .onClick(() => this.updateScreenInfo())
        .margin({ top: 20 })
    }
    .justifyContent(FlexAlign.Center)
    .width('100%')
    .height('100%')
    .backgroundColor('#f0f0f0')
  }
}

代码解析：

• 使用 getContext(this) 安全获取上下文。
• 通过 context.windowStage.getMainWindowSync() 同步获取主窗口实例。
• 读取 windowRect 属性获取实时宽高，避免异步回调嵌套。

五、常见问题与最佳实践

❓ Q1：如何在非 UIAbility 中获取 Context？

A：可通过 Ability 的 context 属性进行传递，或使用 ApplicationContext（需申请相应权限）。

❓ Q2：main_pages.json 能否动态修改？

A：不能。所有页面必须在编译时静态注册，这是出于安全与路由性能优化的考虑。

✅ 最佳实践

• 职责单一：一个 UIAbility 仅负责一类核心功能（如主界面、独立设置页）。
• 避免强引用：Page 组件中避免直接持有 Ability 实例，建议通过事件总线或状态管理进行通信。
• 窗口管理下沉：窗口创建、属性设置等操作应集中在 UIAbility 中，Page 仅负责 UI 渲染与交互逻辑。

六、总结

Stage 模型通过 Ability、Window、Page 三层解耦，实现了更清晰的生命周期管理与多设备适配能力。作为 HarmonyOS 官方长期维护的架构标准，深入理解其核心机制是开发高质量鸿蒙应用的基础。建议新项目直接采用 Stage 模型，老项目可借助官方迁移工具逐步重构。