Qt for OpenHarmony 能用的预编译 SDK 是 5.12.12,桌面这边是 Qt 6.11 加 CMake。两边跑同一份
src/和同一份 QML,差别全在包装层:一边靠qt_add_qml_module()自动注册类型,另一边靠qmlRegisterType()手写。旋转窗口最后被做成 static 纯函数,两边各自只负责把类型注册回去。
仓库地址:https://atomgit.com/lqjmac/tablet-adaptive-qt
三方框架版本:https://wiki.qt.io/Qt_for_HarmonyOS
组织仓库链接:https://atomgit.com/ohos-qt
0. 环境与实测设备
三方库适配信息:
| 三方库 | 版本 | 形态 | 仓库地址 |
|---|---|---|---|
| tablet-adaptive-qt | 1.0.0 | Qt Quick / QML 库(桌面 Qt 6.5+ CMake;Qt for OpenHarmony 5.12.12 + qmake 交叉编译,同一份源码) | https://atomgit.com/lqjmac/tablet-adaptive-qt |
实测环境:
| 项 | 版本/型号 |
|---|---|
| 桌面构建链 | Qt 6.11.0、CMake 4.3.2(要求 Qt 6.5+ / CMake 3.21+ / C++17) |
| OHOS 构建链 | Qt for OpenHarmony 5.12.12 预编译 SDK(qmake,arm64-v8a)+ OpenHarmony Native SDK |
| QML 语法基线 | 2.12(兼容 Qt 5.12.12;桌面与鸿蒙共享同一份 QML 源文件) |
| 测试 | Qt Test:SPEC 2.2 全部 12 组向量、4 组断点边界(10 条用例)、NaN/Inf/负数归一化、QObject 属性与窗口监听、旋转几何(中心保持/工作区钳制/正方形/无屏幕) |
| 实测设备 | HUAWEI MOR-M1(2in1 真机,3120×2080),OpenHarmony 7.0.0.109 / API 26 |
| 真机实测 | 1280×730 横屏 large 双栏/侧轨/12 栏(列表单列、详情 760 阅读宽度);窗口旋转 730×1280 竖屏单栏/底栏即时重算;单栏详情与返回正常,选中目标、条目与列表状态保持 |
构建输出、测试计数和窗口日志抄自验证记录。ctest 输出 1/1 Test #1: tst_tabletlayout 和 Passed 0.99 sec,测试进程报 Totals: 37 passed, 0 failed。
1. 2.15 的 QML 在 5.12 的 qmake 上过不去
桌面那份 AdaptiveTabletWorkspace.qml 第一次进 Qt for OpenHarmony 工程,停在第一行 import:import QtQuick 2.15。预编译 SDK 是 5.12.12,2.15 的文件它不解析。版本号改成 2.12,required property 又报错,那是 5.15 才加的语法。C++ 侧同样断一截:桌面用 QML_ELEMENT 让 CMake 在构建时生成类型注册,5.12 根本不认识这个宏。
这三处与配置无关,是版本基线不同。官方预编译 SDK 只有 5.12.12,没有 qt_add_qml_module(),也没有 QML_ELEMENT。绕开它的办法是把 Qt 6 才有的东西全挤进包装层,不必给鸿蒙抄一份源码:QML 统一写成 2.12 的版本号,Qt 6 也接受;TABLETRESPONSIVE_QML_ELEMENT 在 Qt 6 下展开成 QML_ELEMENT,在 qmake 构建里展开成空,类型改由 plugin.cpp 的 qmlRegisterType() 注册;demo/main.cpp 在 Qt < 5.14 时用 root object 属性回填启动参数。
编译期还撞上一个。桌面 demo 用 setInitialProperties() 传窗口宽高和 --open-first,5.12 的头文件里没有它。现在的写法是一段条件编译:Qt 6 走 initial properties,5.12 在 engine.load() 之后拿 rootObjects().constFirst() 逐个 setProperty()。代价是启动参数在两个时机生效,好处是同一份 demo/ 能同时喂给桌面和鸿蒙。截图回归能过,说明这条兼容路径没有改变渲染:两张预览图重新生成后逐像素比较,差异为空。
布局的输入也吵过一轮。PC 上拖窗口不改方向,折叠屏展开也不触发旋转,QScreen 的方向、窗口宽高、可用区域各说各话。最后的约定只有一句:方向是 width > height 的推导值,布局只认容器尺寸,TabletLayout 不读 screen.orientation。
旋转本身也不省心。resize(交换宽高) 写出来三行,跑起来窗口跳位:左上角不动,中心漂到右下方,多转几次标题栏出屏幕。所以几何被拆成三个 static 函数,Qt Test 不开窗口就能断言矩形,rotate() 只剩"取窗口、调函数、setGeometry"。
2. 跑起来是什么样
示例是"田野笔记"工作台,跑在鸿蒙 2in1 真机的自由窗口里。横屏态:

窗口 1280×730,尺寸提示条汇报 1280 × 730 · 横屏 · large · 12 栏。左侧 88px 深绿侧轨,主体双栏:列表栏限制在 listWidth(300–400)内单列排卡片,详情拿到 760px 的阅读宽度。点左侧卡片只有右侧详情换内容,列表的 GridView 是同一个实例,滚动位置不动。
切到「今天」之后是另一个状态:

列表按 item.section == destination.id 过滤,双栏规则是切换目标时选中新目标里最靠前的一项。窗口右上角的「旋转窗口」调用 TabletWindowController.rotate():交换宽高、保持中心、钳制进屏幕可用区域。实机 hilog 里能看到两次几何变化:
windowRectChanged window: Main_QMLTYPE_6 rect: QRect(790,6 730x1350)
window: geometry change to: QRect(790,76 730x1280)
前一行是窗口管理器的中间态,后一行是控制器算完的落地值。布局从 large 双栏重算成 medium 单栏底部导航,选中的目标、条目和列表状态原样保留。
桌面侧的预览图由 demo 自己生成,全部走 --screenshot 参数,后端是 offscreen/software,验证记录再把它们和仓库里的基准做逐像素比较。
3. 布局从窗口尺寸来:resolve() 和它的纪律
整条链路是"窗口 → 绑定 → 纯函数 → QML 属性":
QQuickWindow(拖拽 / 旋转 / 分屏 / 折叠,全部只是宽高变化)
│ TabletLayout.window 绑定;widthChanged/heightChanged 触发
▼
TabletLayout::resolve(width, height, config) ← static 纯函数,无状态线程安全
│ sizeClass / columns / margin / gutter / navigation / paneMode / listWidth / density
▼
TabletLayout(QML_ELEMENT) ← 布局属性投影 + layoutChanged()
▼
AdaptiveTabletWorkspace.qml ← 零 Controls 的 list-detail 工作台
断点与家族各篇同源,三档加派生规则:
| 宽度 | sizeClass | columns | margin / gutter |
|---|---|---|---|
| <600 | compact | 4 | 16 / 8 |
| 600–839 | medium | 8 | 24 / 16 |
| 840–1199 | expanded | 12 | 32 / 24 |
| >=1200 | large | 12 | 40 / 32 |
导航形态:w >= 840,或 w >= 600 且横屏 → 侧轨;否则底部导航。单双栏:w >= 840,或 w >= 720 且横屏 → 双栏;否则单栏。列表宽度是 clamp(round(w × 0.34), 300, 400),双栏列表强制单列。density 按 h < 500 切紧凑,headerHeight 从 64 变 56。isTablet 只看 min(w, h) >= 600,不封顶 sizeClass:844×390 的手机横屏是 expanded / 12 栏 / isTablet == false。
唯一的实现是 TabletLayout::resolve():
// src/TabletResponsive/TabletLayout.cpp
TabletLayoutMetrics TabletLayout::resolve(qreal width, qreal height,
const TabletLayoutConfig &config)
{
TabletLayoutMetrics metrics;
metrics.width = normalizedDimension(width);
metrics.height = normalizedDimension(height);
const bool landscape = metrics.width > metrics.height;
metrics.orientation = landscape ? QStringLiteral("landscape")
: QStringLiteral("portrait");
metrics.sizeClass = sizeClassFor(metrics.width);
metrics.columns = columnsFor(metrics.sizeClass);
metrics.cardColumns = cardColumnsFor(metrics.width, metrics.orientation);
metrics.margin = marginFor(metrics.sizeClass);
metrics.gutter = gutterFor(metrics.sizeClass);
metrics.navigation = navigationFor(metrics.width, metrics.orientation);
metrics.paneMode = paneModeFor(metrics.width, metrics.orientation);
metrics.listWidth = std::clamp(
static_cast<int>(std::lround(static_cast<double>(metrics.width) * 0.34)),
kListWidthMin, kListWidthMax);
metrics.railWidth = configDimension(config.railWidth, 88);
metrics.bottomBarHeight = configDimension(config.bottomBarHeight, 76);
metrics.density = metrics.height < kCompactDensityHeight
? QStringLiteral("compact")
: QStringLiteral("comfortable");
metrics.headerHeight = metrics.density == QLatin1String("compact")
? configDimension(config.compactHeaderHeight, 56)
: configDimension(config.comfortableHeaderHeight, 64);
metrics.isTablet = std::min(metrics.width, metrics.height) >= kTabletMinShortSide;
metrics.summary = QStringLiteral("%1 × %2 · %3 · %4 · %5 栏")
.arg(metrics.width)
.arg(metrics.height)
.arg(orientationLabel(landscape))
.arg(metrics.sizeClass)
.arg(metrics.columns);
return metrics;
}
输入归一化由一个独立的小函数兜底:
// src/TabletResponsive/TabletLayout.cpp
int normalizedDimension(qreal value)
{
if (!std::isfinite(value) || value <= 0.0)
return 0;
const qreal intMax = static_cast<qreal>(std::numeric_limits<int>::max());
if (value >= intMax)
return std::numeric_limits<int>::max();
return static_cast<int>(std::llround(value));
}
normalizedDimension() 先吃掉垃圾输入:NaN、Inf、负数归零,超过 int 上限的钳到 INT_MAX,其余四舍五入。0×0 因此返回 compact 默认值(竖屏、底部导航、单栏、4 栏、16/8、300 宽、紧凑密度、56 头高),不抛异常。窗口初始化、屏幕拔插、容器还没挂载都会短暂量到 0 或非法值,抛异常只会把问题推给调用方。Qt Test 里 resolve(qQNaN(), qQNaN())、resolve(qInf(), -qInf())、resolve(-100.0, -1.0) 各断言了一遍。
resolve() 不读任何成员变量,只读参数和 TabletLayoutConfig。C++ 消费方可以绕开 QML 直接调 resolve(1280, 800),12 组向量、10 条断点用例、归一化和自定义配置也全部离线跑。QML 类型那层只是投影:布局 token 都从同一次 resolve() 的 TabletLayoutMetrics 里读,layoutChanged() 一次性通知,绑定不会出现 orientation 新、paneMode 旧的撕裂帧。TabletLayout.window 只回答"什么时候重算"。
属性这层值得单独说。TabletLayout 挂了 20 个 Q_PROPERTY:15 个只读,4 个可写的尺寸配置,外加一个 window。只读项和 4 个尺寸配置都 NOTIFY layoutChanged,window 单独用 windowChanged。原因在 resolve() 的原子性:一次调用产出的是一份完整快照,orientation、paneMode、listWidth 之间有推导关系;如果每个属性各发 xxxChanged,applyMetrics() 就要逐字段比较、逐字段 emit,漏掉一处,QML 就会拿到半新半旧的状态。现在的写法是整体替换 m_metrics、发一次信号,布局绑定各重算一次。拖动窗口时每帧一次,这个量级在 Qt 里是微秒级的。
也考虑过只暴露一个 QVariantMap layout。QML 里写 layout.paneMode 能跑,但没有类型检查、没有补全,绑定依赖也不好跟踪,每次读还要从 map 里取键。20 个具名属性啰嗦,可 layout.paneMode === "split" 这种写法最直接。布局尺寸里可写的只有 railWidth、bottomBarHeight 和两个 header 高度,它们是宿主可以调的物理尺寸,setter 里做一次 refresh(),复用同一个信号。这套属性最大的好处是可测:纯函数给出快照,QObject 只负责把快照广播出去,Qt Test 断言前者,QML 看到后者,两边不会各算一遍。
setWindow() 除了连接 widthChanged / heightChanged,还连接了 destroyed。窗口销毁时 clearWindow() 把指针置空并重算一次 resolve(0, 0),宿主换窗口或重建窗口时不会读到悬空对象;sync() 在窗口存在时读实际宽高,窗口不在时保留上一次的有效尺寸,setViewportSize() 手动喂进来的值不会被空窗口状态清掉。
4. 旋转:中心保持与工作区钳制
一开始我写的旋转只有三行:取窗口尺寸、交换宽高、resize。跑起来窗口左上角没动,中心漂到右下,多转几次标题栏出屏。setGeometry 以左上角为锚点,交换宽高不会自动保持中心。
旋转的语义是原地转,所以先取当前矩形的中心,再用目标尺寸反推左上角,最后把完整窗口夹进 availableGeometry():
// src/TabletResponsive/TabletWindowController.cpp
QRect TabletWindowController::centeredForSize(const QRect ¤t,
const QSize &requestedTarget,
const QRect &available)
{
QSize target(qMax(1, requestedTarget.width()), qMax(1, requestedTarget.height()));
const qreal centerX = current.x() + current.width() / 2.0;
const qreal centerY = current.y() + current.height() / 2.0;
if (!validAvailable(available)) {
return QRect(qRound(centerX - target.width() / 2.0),
qRound(centerY - target.height() / 2.0),
target.width(), target.height());
}
target.setWidth(qMin(target.width(), available.width()));
target.setHeight(qMin(target.height(), available.height()));
const int maxX = available.x() + available.width() - target.width();
const int maxY = available.y() + available.height() - target.height();
const int x = qBound(available.x(),
qRound(centerX - target.width() / 2.0), maxX);
const int y = qBound(available.y(),
qRound(centerY - target.height() / 2.0), maxY);
return QRect(QPoint(x, y), target);
}
QRect TabletWindowController::rotatedGeometry(const QRect ¤t,
const QRect &available)
{
if (current.isEmpty())
return current;
return centeredForSize(current, rotatedSize(current.size()), available);
}
顺序不能换。先按可用区域收缩目标尺寸,再以原中心求位置,最后 qBound 把左上角夹回工作区内。availableGeometry() 优先取窗口当前 screen,拿不到回退主屏,再拿不到返回空矩形;空矩形时 centeredForSize() 走提前返回的分支,只保持中心和尺寸。旁边那个 clampToAvailable() 是给「只想把任意矩形夹进屏幕、不想改尺寸语义」的调用方用的兜底版本。
真机日志里 730×1280 就这么来的:窗口原来是 1280×730,旋转后目标 730×1280,屏幕工作区放得下,于是 x 从中心推回 790、y 落到 76。桌面测试里 keeps-centre 那组 QRect(600,300,800,400) 在 1920×1080 上转成 QRect(800,100,400,800);clamps-both-axes 那组 800×400 在 1000×700 上转成 QRect(600,0,400,700),y 被夹到 0。no-available-rect 的期望值是 QRect(250,-140,400,800),y 是负的——拿不到屏幕信息时保持中心比瞎猜工作区更诚实。
rotatedSize() 只做交换,不管放不放得下;放不下由 centeredForSize() 兜:先把目标宽高压到 available 以内,再按原中心求左上角,最后 qBound 夹回来。测试里 clamps-to-screen 走的就是这条路径:QRect(100,100,1280,800) 在 1920×1080 上旋转,交换得到 800×1280,高度超过工作区,压到 1080,x 按中心换算得 340,y 被夹到 0,结果 QRect(340,0,800,1080)。
所以旋转不保证"转满"。窗口比屏幕高时,转完的宽高就是工作区尺寸,观感上像被压掉一截。库不做缩放补偿,也不改 DPI,只保证窗口完整落在工作区内、中心尽量不跳。真机上 1280×730 能转成 730×1280,是因为工作区高度够;换一块更矮的屏幕,同一个窗口就转不满。
rotate() 的失败路径分三种:没窗口、窗口是正方形、目标尺寸和当前一样。setOrientation() 再加一种:只认 portrait / landscape,其余直接返回 false。方向参数做了 trimmed().toLower(),所以 PORTRAIT 能进,diagonal 返回 false;正方形请求横屏时 target.width() == target.height(),同样返回 false:交换宽高变不出横屏,报没做到比返回自相矛盾的状态好。controllerRotatesWindow() 会真建一个 QQuickWindow,resize(800, 400)、setPosition(20, 20),断言 rotate() 之后的 window.geometry() 等于纯函数算出的值。
5. QML 工作台:同一个 GridView,四条回退规则
AdaptiveTabletWorkspace.qml 的列表从头到尾是同一个 GridView 实例,单双栏靠几何和 visible 切换。选中项和单栏详情开关活在组件状态里,回退规则写在 syncSelectionForMode():
// qml/AdaptiveTabletWorkspace.qml
function syncSelectionForMode() {
var source = items || []
var currentValid = false
if (selectedItemId !== "") {
for (var i = 0; i < source.length; ++i) {
if (source[i] && source[i].id === selectedItemId
&& source[i].section === selectedDestinationId) {
currentValid = true
break
}
}
if (!currentValid)
selectedItemId = ""
}
if (split) {
singleDetailVisible = false
if (selectedItemId === "") {
var first = firstItemId(selectedDestinationId)
if (first !== "")
selectedItemId = first
}
} else if (selectedItemId === "") {
singleDetailVisible = false
}
}
function selectDestination(destinationId) {
if (selectedDestinationId === destinationId)
return
selectedDestinationId = destinationId
}
function openItem(itemId) {
var source = items || []
var found = false
for (var i = 0; i < source.length; ++i) {
if (source[i] && source[i].id === itemId) {
found = true
break
}
}
if (!found)
return
selectedItemId = itemId
if (!split)
singleDetailVisible = true
}
function backToList() {
singleDetailVisible = false
}
选中项是否合法要连 section 一起校验:切到"归档"之后,原来在"收件箱"里选中的条目不该继续占着详情位。onSplitChanged 缩回单栏时先把 singleDetailVisible 置 false 再调 syncSelectionForMode(),所以双栏缩回单栏一定回到列表;反过来单栏展开双栏时保留合法选中项,没有就补上最前面那一项。openItem() 在单栏里多置一次 singleDetailVisible = true,返回按钮只在单栏渲染。
列表卡片列数在运行时算,cellWidth 是整宽除以列数,不把尾部 gutter 算进去。这里踩过一次:GridView 用 floor(width / cellWidth) 决定列数,如果给 cell 加上尾部 gutter 再除,2 列会退化成 1 列。cardColumnCount 在 split 模式恒为 1,只有 single 模式才用 layout.cardColumns,所以双栏时列表永远是单列,详情拿剩余宽度。
数据侧还有个规矩:destinations / items 必须是 JS 数组,更新时整个替换,原地 push 触发不了 onItemsChanged,QML 的绑定通知只认引用变化。headerAction 是个 Component 插槽,demo 的旋转按钮由它注入。
6. 两条链怎么包同一份源码
源码只有一份,src/ 与 qml/ 是共享内核:
qt/ # 库根目录(CMakeLists.txt,v1.0.0)
├─ src/TabletResponsive/ # TabletLayout + TabletWindowController
├─ qml/AdaptiveTabletWorkspace.qml # list-detail 参考工作台(2.12 语法)
├─ demo/ # main.cpp + Main.qml + demo-data.json + 截图参数
├─ tests/tst_tabletlayout.cpp # 12 向量 + 边界 + 属性 + 旋转几何
├─ cmake/TabletResponsiveConfig.cmake.in
└─ ohos/ # Qt for OpenHarmony 工程(DevEco 可直接打开)
├─ library/ # HAR:libTabletResponsiveplugin.so + resfile/qml/TabletResponsive/
├─ example/ # 演示 HAP:QAbility 桥接 + libtabletadaptivedemo.so
├─ qt/{plugin,demo}.pro # qmake 交叉编译(复用同一份 src/ 与 demo/)
└─ build-qt-ohos.sh # 交叉编译 + 部署 + 打包 + 安装 + 启动

桌面上,src/CMakeLists.txt 用 qt_add_qml_module() 把 C++ 类型和 QML 文件编成一个模块,类型注册由构建系统生成,QML 模块先落在构建树的 qml/ 下,安装时进 lib/qml/TabletResponsive/。鸿蒙这条链没有这套东西,于是有一个小插件把 TabletLayout 和 TabletWindowController 注册回去:
// ohos/qt/plugin.cpp
#include <QtQml/QQmlExtensionPlugin>
#include <QtQml/qqml.h>
#include "TabletResponsive/TabletLayout.h"
#include "TabletResponsive/TabletWindowController.h"
class TabletResponsivePlugin : public QQmlExtensionPlugin
{
Q_OBJECT
Q_PLUGIN_METADATA(IID QQmlExtensionInterface_iid)
public:
void registerTypes(const char *uri) override
{
Q_ASSERT(QLatin1String(uri) == QLatin1String("TabletResponsive"));
qmlRegisterType<TabletLayout>(uri, 1, 0, "TabletLayout");
qmlRegisterType<TabletWindowController>(uri, 1, 0, "TabletWindowController");
}
};
#include "plugin.moc"
plugin.pro 负责把它编成 libTabletResponsiveplugin.so,关键几行是 CONFIG += plugin c++17、DEFINES += TABLETRESPONSIVE_LIBRARY TABLETRESPONSIVE_QMAKE_PLUGIN、INCLUDEPATH += ../../src,以及 CONFIG += no_qt_rpath。这行不能省:一开始交叉编译出来的 .so 里写着开发机的 Qt 安装路径,装到设备上 loader 找不到 libQt5Quick.so,报错信息还指向开发机用户目录下的 ohos-frameworks/qt/lib。关掉之后 llvm-readelf -d 里的 RPATH / RUNPATH 是空的,Qt 依赖改由宿主 HAP 的 libs/arm64-v8a 解析。demo.pro 更短,但有一个容易漏的宏:它用 DEFINES 把设备上的 QML import 根(/data/storage/el1/bundle/entry/resources/resfile/qml)编进 TABLET_RESPONSIVE_QML_IMPORT_DIR,main.cpp 读到非空就 engine.addImportPath();桌面构建里宏是空串,这段被跳过。
部署是 ohos/build-qt-ohos.sh 一条脚本走完:qmake 编 plugin 和 demo,产物分别进 HAR 的 library/libs/arm64-v8a/ 与 resfile/qml/TabletResponsive/,同时镜像一份进宿主 HAP 的 example/libs/arm64-v8a/ 与 example/src/main/resources/resfile/qml/,--hap 调 hvigor,--install 装,--run 起 QAbility。参数全部来自环境变量,换机器只改变量。两边各放一份 QML 目录,是因为 HAR 的 resfile 会不会随包传给宿主取决于 hvigor 版本,脚本不赌这个行为。
两边的差别可以列成一张很小的对照清单。QML 模块注册:桌面由 qt_add_qml_module() 生成 qmldir、qmltypes 和插件注册代码,鸿蒙由 plugin.cpp 的 qmlRegisterType() 加手写的 ohos/qt/qmldir。C++ 标准:两边都是 C++17,一个来自 CMAKE_CXX_STANDARD 17,一个来自 CONFIG += c++17。头文件路径:一个走 target_include_directories 的 PUBLIC 参数,一个走 INCLUDEPATH += ../../src。安装布局:一个进 include/、lib/、lib/qml/,一个进 HAR 的 libs/arm64-v8a/ 与 resfile/qml/。demo:桌面是可执行文件,鸿蒙必须编成 libtabletadaptivedemo.so,由 libqohos.so 调 main。五处差异全在包装层,src/ 与 qml/ 没有分叉。同一个故障在桌面上复现不了,基本就能确定出在部署脚本。
7. 类型注册、签名与包里的载荷
语法基线定下来之后,桌面也不能用 Qt 5.15 之后的新 QML 特性写库代码,required、inline component 全部放弃。类型注册清单还要两边同步:TABLETRESPONSIVE_QML_ELEMENT 在 qmake 构建里展开成空,只加头文件里的宏、忘了 plugin.cpp 的 qmlRegisterType(),结果就是桌面编得过、鸿蒙运行时找不到类型。plugin.cpp 顶部那句 keep both lists in sync 是写给以后的自己看的。
旋转跳位那次前面说过,resize(交换宽高) 让中心漂移。改用 rotatedGeometry() 之后还有个尾巴:setGeometry() 传进去的尺寸不一定就是落地尺寸,窗口管理器可能取整或者套最小尺寸限制。所以 orientationChanged() 在 setGeometry() 之后才发,orientation() 读的是 m_window->width() / height(),QML 拿到的是窗口管理器落地后的实际尺寸,不是请求值。
窗口出屏也撞过一次。标题栏拖出屏幕之后鼠标够不着,只能用键盘救回来。夹取优先于中心保持就是那次定下来的:宁可中心偏移,也不让窗口有一角留在工作区外。
剩下两个都是安装布局问题。图省事把 qmldir 塞进 Qt 安装目录,升级 Qt 即失效,多版本共存互相污染;现在模块装在 lib/qml/TabletResponsive/,TabletResponsiveConfig.cmake 导出 TabletResponsive_QML_IMPORT_DIR,宿主自己 addImportPath()。add_subdirectory 默认会把 demo 和测试编进宿主,CI 平白多拉 Qt Test;现在两个选项顶层默认 ON、作为子工程默认 OFF(${PROJECT_IS_TOP_LEVEL})。
鸿蒙侧的坑更偏工程。装 HAP 时只装了 qEmbeddedUiExtensionHost,启动器里有图标、点进去没反应——QAbility 在 entry 里,两个 HAP 都要装,DevEco 的 Run Configuration 也要选 entry。签名是另一个:本机 profile 绑的是别的 bundleName,直接套会安装失败,得把 AppScope/app.json5 的 bundleName 改成 profile 里的那个。本机签名放在 gitignored 的 ohos/build-profile.signed.local.json5,--hap/--install/--run 时临时覆盖 build-profile.json5,trap 配合 EXIT 保证失败退出也还原。
还加了一道载荷保护。手工跑 hvigorw assembleHap 而没先跑部署脚本时,example/libs 是空的,打出来的 HAP 里没有 libqohos.so,装上去白屏。现在 check_qt_payload 这个自定义 target 会在 example/libs/arm64-v8a 或 resfile/qml/TabletResponsive 缺失时让 BuildNativeWithNinja 直接失败,日志停在 FAILED: CMakeFiles/check_qt_payload,最后一行是 > hvigor ERROR: BUILD FAILED。
这条验证是故意制造的:把 example/libs 改名成 libs.bak 再构建,确认它失败,改回来才成功。
8. 宿主怎么接,还有哪些没验证
工程本身由布局引擎、窗口控制器和 QML 工作台三块组成,版本 1.0.0,Apache-2.0。桌面有三种接入方式:
# 1. CMake 安装 + find_package
cmake -S . -B build -DCMAKE_PREFIX_PATH="<Homebrew 前缀>" -DCMAKE_INSTALL_PREFIX="$HOME/.local"
cmake --build build -j8 && cmake --install build
# 宿主:find_package(TabletResponsive 1.0 CONFIG REQUIRED)
# 2. add_subdirectory(demo/tests 默认 OFF)
# 3. 只用 C++ 引擎:#include <TabletResponsive/TabletLayout.h>
QML 侧的最小宿主长这样,数据来自 demo-data.json,旋转按钮走 headerAction 插槽:
// 参考 demo/Main.qml 的最小宿主;demoData 由 main.cpp 注入
import QtQuick 2.12
import QtQuick.Window 2.12
import TabletResponsive 1.0
Window {
id: root
width: 1280
height: 800
visible: true
TabletWindowController { id: rotation; window: root }
AdaptiveTabletWorkspace {
anchors.fill: parent
window: root
title: demoData.brand
eyebrow: demoData.eyebrow
destinations: demoData.destinations
items: demoData.items
showMetrics: true
headerAction: Component {
Rectangle {
width: 120
height: 44
radius: 14
color: "#16352E"
Text {
anchors.centerIn: parent
text: "旋转窗口"
color: "#F4F1E9"
}
MouseArea {
anchors.fill: parent
onClicked: rotation.rotate()
}
}
}
}
}
跑 demo 与测试:
cmake --build build -j8 && ctest --test-dir build --output-on-failure
./build/demo/tablet-responsive-demo # 1280×800 + 旋转按钮
QT_QPA_PLATFORM=offscreen QT_QUICK_BACKEND=software \
./build/demo/tablet-responsive-demo --screenshot preview.png --delay 1200
鸿蒙侧一条脚本(参数走环境变量):
cd ohos && ./build-qt-ohos.sh --hap --install --run
# 交叉编译 → 部署 HAR/HAP → hvigor 打包 → hdc 安装 → 启动 QAbility
hvigor 打包的载荷里,插件 56,064 字节、demo 35,256 字节、qmldir 144 字节、AdaptiveTabletWorkspace.qml 56,550 字节。unsigned HAP 28,096,233 字节,签名版 28,462,723 字节。两个 HAP 都装上之后,hdc shell aa start -a QAbility -b dev.cjgg.tablet_responsive_example 能起。
更完整的 API 表、安装布局与载荷校验在仓库文档里:仓库说明记 QML 用法、TabletLayout / TabletWindowController 全属性表和接入方式;OpenHarmony 接入说明记 Qt 5.12.12 基线、交叉编译命令与边界说明;验证记录与包检查记录收着构建、测试、实机全记录,以及安装目录和 HAR/HAP 载荷校验。
布局并不依赖 TabletWindowController。最大化、全屏、分屏的窗口由窗口管理器接管时,rotate() 的 resize 请求可能被拒绝,布局照样跟着实际容器尺寸走。当前的验证边界:桌面 Qt 6.11.0 + CMake 4.3.2 上构建、37 个用例、截图逐像素比对都过;鸿蒙 Qt 5.12.12 交叉链能编译出 aarch64 ELF、打出 HAP、在 2in1 浮动窗口里完成一次 1280×730 → 730×1280 的旋转;Qt 6 的 OHOS 交叉编译没做过,全屏下 rotate() 会不会被窗口管理器接受也没有结论。接下来补这两处。
7



被折叠的 条评论
为什么被折叠?



