Qt for HarmonyOS/user development/floating window guild zh

Qt for HarmonyOS 悬浮窗功能开发指导

简介

本文档详细介绍如何在 Qt for HarmonyOS 应用中实现 悬浮窗（Floating Window）功能。

HarmonyOS 平台提供了原生的悬浮窗能力，Qt 通过 QtOhosExtras 模块， 为开发者提供了基于 HarmonyOS 悬浮窗能力的 Widget / QWindow 创建与管理接口。

本指南将详细说明悬浮窗功能的 使用方法、实现机制，并提供关键代码示例。

---

功能架构概述

在 HarmonyOS 中使用 Qt 悬浮窗功能时，需要理解以下架构原理。

应用窗口类型

Qt for HarmonyOS 支持多种窗口类型的创建：

1. 标准主窗口
   • 基于 HarmonyOS 主窗口能力
   • 在应用任务栈中显示
   • 遵循标准应用生命周期
2. 悬浮窗口
   • 基于 HarmonyOS 原生悬浮窗能力
   • 可显示在其他应用之上
   • 具有独立的显示层级

---

窗口层级关系

Qt 悬浮窗支持复杂的窗口层级结构：

窗口类型	父子关系支持	使用场景
主窗口	支持子窗口	应用主界面
悬浮窗	支持子窗口	悬浮工具、通知窗口
子窗口	可嵌套	对话框、弹窗

---

核心特性

Qt for HarmonyOS 的悬浮窗功能具有以下特点：

1. 底层集成：基于 HarmonyOS 原生悬浮窗能力实现
2. Qt 对象接口：支持通过标准 Qt 接口进行创建、销毁和属性设置
3. 内容渲染：与普通 QWidget 使用相同的内容加载和绘制方式
4. 子窗口支持：支持在悬浮窗中创建模态和非模态子窗口

---

Qt API 详解

setShowWindowAsFloatWindowHint()

void QtOhosExtras::setShowWindowAsFloatWindowHint(
    QWidget *widget,
    bool enable
);

该函数是 Qt for HarmonyOS 提供的核心悬浮窗设置 API， 用于将指定的 Qt 窗口设置为 HarmonyOS 悬浮窗模式。

---

参数说明

参数	类型	说明
widget	QWidget*	需要设置为悬浮窗的窗口对象
enable	bool	true 表示启用悬浮窗模式，false 表示普通窗口模式

---

功能机制

该函数在 HarmonyOS 平台上的工作原理如下：

1. 窗口提示设置：为指定 QWidget 设置悬浮窗显示提示
2. 底层映射：将 Qt 窗口映射为 HarmonyOS 原生悬浮窗
3. 属性继承：保持 Qt 窗口的所有标准属性和行为
4. 生命周期管理：悬浮窗遵循 Qt 对象的标准生命周期

---

开发实现

核心实现原理

实现悬浮窗功能的关键在于：

必须在窗口调用 show()之前，调用 setShowWindowAsFloatWindowHint()

---

关键代码示例

1. 创建悬浮窗

// 创建悬浮窗的核心实现
void MainWindow::openFloatingWindow()
{
    // 创建窗口实例
    SecondWindow *win = new SecondWindow();

    // 关键：设置为悬浮窗模式（必须在 show() 之前）
    QtOhosExtras::setShowWindowAsFloatWindowHint(win, true);

    // 设置窗口属性
    win->setAttribute(Qt::WA_DeleteOnClose);
    win->resize(300, 300);

    // 显示窗口
    win->show();
}

说明：

• 必须在 show() 之前调用悬浮窗设置接口
• 悬浮窗可像普通 QWidget 一样设置大小和属性
• 建议使用 Qt::WA_DeleteOnClose 自动释放资源

---

2. 在悬浮窗中创建子窗口

// 在悬浮窗中创建模态对话框
void SecondWindow::modalWithParent()
{
    SimpleDialog dlg(this); // 以悬浮窗为父窗口
    dlg.setWindowTitle("Modal with Parent");
    dlg.exec();
}

// 在悬浮窗中创建非模态子窗口
void SecondWindow::nonModalWithParent()
{
    SimpleDialog *dlg = new SimpleDialog(this);
    dlg->setWindowTitle("Non-Modal with Parent");
    dlg->setAttribute(Qt::WA_DeleteOnClose);
    dlg->show();
}

说明：

• 悬浮窗可作为父窗口创建子窗口
• 支持模态（exec()）和非模态（show()）窗口
• 子窗口遵循标准 Qt 父子关系和生命周期管理

---

项目配置

# FloatWindowChilds.pro
QT += core gui widgets ohosextras
SOURCES += main.cpp

关键配置说明：

• 必须添加

  ohosextras
  

  模块以使用悬浮窗 API

---

应用场景

适用场景

• 悬浮工具：计算器、便签等小工具
• 系统通知：消息提醒、状态显示窗口
• 辅助功能：屏幕录制控制、音量调节等
• 多任务协作：需要与其他应用同时显示的功能窗口

---

基本使用模式

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

    // 2. 设置为悬浮窗
    QtOhosExtras::setShowWindowAsFloatWindowHint(window, true);

    // 3. 配置窗口属性
    window->setAttribute(Qt::WA_DeleteOnClose);
    window->resize(desiredWidth, desiredHeight);

    // 4. 显示窗口
    window->show();
}

---

编译和测试

编译步骤

qmake FloatWindowChilds.pro && make

---

测试验证

1. 启动应用：主窗口正常显示
2. 点击 “Open OHOS floating window” 按钮
3. 验证悬浮窗是否以悬浮模式显示，并可覆盖其他应用
4. 在悬浮窗中创建子窗口，验证模态与非模态行为
5. 验证悬浮窗是否支持拖拽移动

---

开发注意事项

悬浮窗权限

使用悬浮窗功能时，需要注意 HarmonyOS 的权限要求：

• 悬浮窗权限：应用需申请悬浮窗显示权限
• 系统级权限：部分场景可能需要系统级权限支持
• 用户授权：首次使用时需用户手动授权

---

相关资源

• [1] - Qt QWidget 类参考文档