HarmonyOS 5.0 PC 窗口模式开发全流程详解｜窗口控制、大小调节、多窗口实战

启辰辰

410人浏览 · 2026-04-15 00:23:42

启辰辰 · 2026-04-15 00:23:42 发布

前言

在 HarmonyOS 5.0 PC 开发中，窗口模式是最核心、最具桌面特性的能力。它让应用不再是手机式的全屏运行，而是真正以 PC 程序形式呈现，支持缩放、拖拽、最大化、最小化、悬浮、多窗口等标准桌面体验。

本文基于HarmonyOS 5.0.0版本，从零讲解 PC 窗口开发：配置开启、窗口生命周期、窗口大小控制、多开新窗口、键鼠适配等全流程。内容实战、代码完整、步骤清晰

一、鸿蒙 PC 支持两种窗口模式：

window 标准窗口：带标题栏，支持缩放、最大化、最小化、关闭。
float 悬浮窗口：置顶显示，适合小工具、快捷操作类应用。

系统默认提供窗口管理能力，开发者只需简单配置即可使用。

二、开启窗口模式（必做配置）

应用要在 PC 上以窗口运行，必须修改module.json5，否则只能以手机模式运行。

2.1 完整配置代码

{
  "module": {
    "name": "entry",
    "type": "entry",
    "srcEntrance": "./ets/entryability/EntryAbility.ts",
    "mainElement": "EntryAbility",
    "deviceTypes": [
      "pc",
      "tablet"
    ],
    "abilities": [
      {
        "name": "EntryAbility",
        "srcEntrance": "./ets/entryability/EntryAbility.ts",
        "launchType": "standard",
        "exported": true,
        "type": "page",
        "supportPCHost": true,
        "supportedModes": [
          "window",
          "float"
        ]
      }
    ],
    "requestPermissions": [
      { "name": "ohos.permission.INTERNET" }
    ]
  }
}

2.2 关键配置说明

supportPCHost: true：允许运行在 PC 桌面环境
supportedModes: ["window","float"]：开启标准窗口 + 悬浮窗口
deviceTypes:["pc"]：明确支持 PC 设备

配置完成后，应用即可在 PC 模拟器 / 真机以窗口运行。

三、窗口生命周期与获取主窗口

窗口的创建、显示、销毁都有完整生命周期，我们通常在EntryAbility.ts中获取主窗口。

3.1 获取主窗口实例

import window from '@ohos.window';
import UIAbility from '@ohos.app.ability.UIAbility';

export default class EntryAbility extends UIAbility {
    private mainWindow: window.Window | null = null;

    onWindowStageCreate(windowStage: window.WindowStage) {
        // 获取主窗口
        windowStage.getMainWindow().then((win) => {
            this.mainWindow = win;
            // 设置窗口初始大小
            this.mainWindow.resetSize({ width: 960, height: 640 });
            // 设置窗口最小大小
            this.mainWindow.setMinSize({ width: 480, height: 320 });
            // 窗口居中
            this.mainWindow.center();
            // 设置标题
            this.mainWindow.setWindowTitle("鸿蒙PC窗口应用");
        });

        // 加载页面
        windowStage.loadContent('pages/index');
    }
}

3.2 常用窗口控制 API

// 最大化
this.mainWindow?.maximize();
// 最小化
this.mainWindow?.minimize();
// 还原
this.mainWindow?.restore();
// 关闭窗口
this.mainWindow?.close();
// 全屏
this.mainWindow?.setWindowMode(window.WindowMode.FULLSCREEN);

这些 API 覆盖日常开发 90% 场景，直接复制即可使用。

四、PC 窗口模式 UI 适配实战

4.1 弹性布局（必须）

PC 窗口可自由缩放，布局必须使用百分比、弹性权重，禁止固定像素。

@Entry
@Component
struct Index {
  build() {
    Column() {
      Text("鸿蒙PC窗口应用")
        .fontSize(32)
        .fontWeight(FontWeight.Bold)
        .margin({ bottom: 20 });

      Button("最大化")
        .width('60%')
        .height(50)
        .onClick(() => {
          // 调用窗口最大化
        });

      Button("最小化")
        .width('60%')
        .height(50)
        .margin({ top: 10 });
    }
    .width('100%')
    .height('100%')
    .justifyContent(FlexAlign.Center)
    .backgroundColor('#f8f8f8');
  }
}

4.2 鼠标悬停效果

@State bgColor: string = '#36adff';

Button("按钮")
  .backgroundColor(this.bgColor)
  .onMouseIn(() => { this.bgColor = '#2d8cf0' })
  .onMouseOut(() => { this.bgColor = '#36adff' })

4.3 右键菜单

Text("右键点击我")
  .bindContextMenu(ContextMenu({
    content: () => [
      MenuItem({ content: Text("复制") }),
      MenuItem({ content: Text("粘贴") }),
      MenuItem({ content: Text("打开新窗口") })
    ]
  }))

五、多窗口开发（高级特性） HarmonyOS 5.0 PC 支持多窗口实例，可同时打开多个独立窗口。

5.1 创建新窗口

onWindowStageCreate(windowStage: window.WindowStage) {
  // ...

  // 创建第二个窗口
  windowStage.createWindow({
    name: "secondWindow",
    supportedModes: ["window"]
  }).then((newWindow) => {
    newWindow.resetSize({ width: 600, height: 400 });
    newWindow.loadContent('pages/second');
    newWindow.show();
  });
}