Qt for HarmonyOS/user development/qt for harmonyos fullscreen main window zh

Qt for HarmonyOS 全屏启动主窗口功能开发指南

简介

本文档详细介绍如何在 Qt for HarmonyOS 应用中实现主窗口的 全屏 / 最大化启动功能。

HarmonyOS 平台对窗口显示模式具有特定的支持策略。Qt 通过标准的窗口状态 API， 为开发者提供了创建全屏主窗口的能力。

本指南将详细说明该功能的使用方法、实现机制，并提供完整的代码示例。

---

功能架构概述

在 HarmonyOS 平台上使用 Qt 全屏主窗口功能时，需要理解以下架构原理。

应用启动流程

Qt for HarmonyOS 应用的窗口创建遵循特定的启动流程：

1. 主应用启动（首个窗口）
   • 以标准窗口模式显示
   • 受 HarmonyOS 系统启动机制限制，无法直接全屏
2. 后续窗口创建
   • 完全支持全屏 / 最大化模式启动
   • 具备完整的窗口状态控制能力

---

Qt API 详解

showFullScreen() 函数

void QWidget::showFullScreen();

该函数是 Qt 标准的全屏显示 API，在 HarmonyOS 平台上得到完整支持。

功能机制

在 HarmonyOS 平台上，showFullScreen() 的行为特点如下：

1. 即时全屏：窗口创建后立即以全屏模式显示
2. 状态保持：窗口状态被正确设置为全屏
3. 系统集成：与 HarmonyOS 原生全屏机制兼容
4. 可逆操作：支持切换回其他窗口状态

---

相关窗口状态 API

API 函数	功能说明	使用场景
showFullScreen()	全屏显示窗口	沉浸式体验、游戏、媒体播放
showMaximized()	最大化显示窗口	保留标题栏的最大化显示
showNormal()	正常窗口模式	标准应用窗口
showMinimized()	最小化窗口	窗口隐藏到后台

---

开发实现

核心实现原理

实现全屏主窗口功能的关键在于：

• 动态创建窗口
• 在创建后立即调用 showFullScreen()

---

关键代码示例

1. 动态创建全屏主窗口

// mainwindow.cpp
void MainWindow::on_pushButton_clicked()
{
    // 创建新的窗口实例
    CustomWidget *widget = new CustomWidget();

    // 关键：调用 showFullScreen() 实现全屏启动
    widget->showFullScreen();
}

说明：

• 通过用户交互（按钮点击）创建新窗口
• 新创建的窗口可以直接全屏显示
• showFullScreen()是实现全屏的核心 API

---

2. 全屏窗口的基础结构

// customwidget.cpp
CustomWidget::CustomWidget(QWidget *parent)
    : QWidget(parent)
{
    QLabel *label = new QLabel("2nd Main Window", this);

    QVBoxLayout *layout = new QVBoxLayout(this);
    layout->addWidget(label);
    setLayout(layout);

    // 窗口关闭时自动释放内存
    setAttribute(Qt::WA_DeleteOnClose);
}

说明：

• 继承自 QWidget，可作为独立主窗口
• 布局和内容可根据实际需求定制
• 使用 Qt::WA_DeleteOnClose 确保资源释放

---

3. 应用入口（首窗口标准模式）

// main.cpp
int main(int argc, char *argv[])
{
    QApplication app(argc, argv);

    // 首个窗口：只能以标准模式启动
    MainWindow mainWindow;
    mainWindow.show();

    return app.exec();
}

说明：

• 应用启动的首个窗口受 HarmonyOS 系统限制
• 首窗口无法直接全屏
• 后续窗口可通过用户交互创建并全屏显示

---

应用场景

适用场景

• 媒体播放：视频播放器、图片浏览器的沉浸式体验
• 游戏应用：全屏游戏界面
• 演示工具：演示文稿、展示类应用
• 专业软件：设计、编辑类应用需要最大显示区域

---

基本使用模式

void createFullScreenWindow()
{
    // 1. 创建窗口实例
    YourWindow *window = new YourWindow();

    // 2. 初始化窗口内容
    window->setupContent();

    // 3. 全屏显示
    window->showFullScreen();
}

---

编译和测试

编译步骤

qmake testMainWindowFullScreen.pro && make

测试验证

1. 启动应用：首个窗口以标准模式显示
2. 点击 “Open Main Window” 按钮
3. 验证新窗口是否以全屏模式显示
4. 测试窗口状态切换是否正常

---

开发注意事项

窗口显示模式限制

窗口类型	是否支持全屏启动	说明
应用启动首窗口	否	受 HarmonyOS 启动机制限制
动态创建窗口	是	Qt 窗口状态 API 正常工作

建议方案：

• 首窗口使用标准模式
• 通过用户操作创建后续窗口并调用 showFullScreen()

---

相关资源

• [1] - HarmonyOS 原生窗口管理相关文档
• [2] - Qt QWidget 类参考文档（窗口状态 API）