一个 JS-only 的 Cordova 插件,能动的只有 WebView 里的 DOM。
cordova-plugin-tablet-adaptive把布局收进一个纯函数,把容器测量交给ResizeObserver,方向锁只做能力探测和降级。这篇写布局、测量、方向锁在 ArkWeb 里怎么落地,以及走到头也走不通的那一段。
仓库地址:https://atomgit.com/lqjmac/cordova-plugin-tablet-adaptive
版本地址:https://atomgit.com/CPF-Cordova
三方库框架:https://atomgit.com/oh-tpc
0. 环境与实测设备
三方库适配信息:
| 三方库 | Cordova 版本 | 鸿蒙化版本 | 仓库地址 | 社区 | 社区地址 |
|---|---|---|---|---|---|
| cordova-plugin-tablet-adaptive | v14.0.2 | 1.0.0(26) | https://atomgit.com/lqjmac/cordova-plugin-tablet-adaptive(生态收录:https://atomgit.com/oh-tpc) | CPF-Cordova 鸿蒙社区 | https://atomgit.com/CPF-Cordova |
实测环境:
| 项 | 版本/型号 |
|---|---|
| DevEco Studio | 内置 hvigor 6.26.4,signed debug HAP 构建安装 |
| hcordova CLI | 1.0.7(HarmonyOS 平台管理与插件复制) |
| WebView | ArkWeb(Chromium 内核;ResizeObserver 可用) |
| 构建链 | Node 24.12.0,TypeScript 5.9 + esbuild,Vitest + jsdom |
| 测试 | 4 个文件 46 项全过(布局向量、观察器、工作台行为、方向锁降级) |
| 插件形态 | JS-only:无原生源码、无 HAR、无 cordova.exec、无权限 |
| 实测设备 | HarmonyOS PC(MOR-M1),3120×2080;HarmonyOS 7.0.0.111,API 26 |
| 实测数据 | 初始容器 1060×520(expanded/12 栏/侧轨+双栏)→ 竖屏 488×704(compact/单栏/底部导航)→ 横屏 860×486(expanded/12 栏/侧轨+双栏) |
构建输出、测试项数和窗口读数来自验证记录、包检查记录与示例说明;HarmonyOS PC 这一轮验证了宿主窗口尺寸变化。
1. 请求 520×900,量到 488×704:少了 32 和 196 像素
按下 example 宿主顶栏的“竖屏”按钮,宿主先向 HostWindow 请求一个 520×900 的窗口。工作台随后量到的容器是 488×704:宽少 32px,高少 196px。少掉的部分属于窗口边框、标题栏、宿主状态栏、日志条和 footer,不属于工作台。它只读自己这块盒子,所以布局仍然成立:488 < 600,sizeClass 是 compact,导航换到底部,主体单栏。
初始容器是 1060×520,落在 840–1199 区间:expanded、12 栏、侧轨 + 双栏,density 舒适,headerHeight 64。listWidth 算出 round(1060 × 0.34) = 360,在 300–400 之间,不需要夹取。

这张是点过“横屏”之后的 860×486。宿主窗口目标 900×700,工作台量到 860×486,提示条读 860 × 486 · 横屏 · expanded · 12 栏。左侧 88px 侧轨,主体双栏;860 宽算出的列表宽度是 round(860 × 0.34) = 292,被夹到 300,正文吃剩下的宽度。
点“竖屏”,宿主窗口 520×900,工作台 488×704:

提示条变成 488 × 704 · 竖屏 · compact · 4 栏。侧轨消失,换成 76px 底部导航;卡片按 cardColumns 排,488 宽只有 1 列;点一张卡片进入全宽详情,左上角出现返回按钮。再点“横屏”,窗口回到 900×700,工作台回到 860×486,列表的滚动位置没有归零,之前选中的那篇笔记还在右侧展开着。
整个切换没有页面重载,也没有白屏。变的只有布局字段和由字段驱动的 DOM;页面状态留在自定义元素的字段里,不依赖当前的 DOM 结构。
把三次读数摊开,布局字段的走向很清楚。1060×520 是横屏、expanded、12 栏、cardColumns 3、margin 32、gutter 24、rail + split,listWidth 360,density 舒适,headerHeight 64;488×704 是竖屏、compact、4 栏、cardColumns 1、margin 16、gutter 8、bottom + single,listWidth 被夹到 300;860×486 又回到 expanded、12 栏、rail + split,listWidth 300,但高度 486 让 density 切到 compact,headerHeight 变成 56。三次的 isTablet 都是 false,短边分别是 520、488、486,都没到 600。这个字段只描述容器,不描述设备;在一台 3120×2080 的 PC 上把窗口拖成 1060×520,它照样不算平板。
状态在三次切换里的走法也不一样。1060 的 split 是首次布局,_handleLayout 走 initial 分支;示例里 items 在 deviceready 之后才赋值,首个被选中的条目出现在 items setter 触发的 _syncDataState 里。切到 488 的 single 时走后续分支,_view 被设回 list,_selectedItemId 保留但不展示,返回按钮不出现;再切回 860 的 split 时,_ensureSelection('split') 发现这个 id 还在当前目标的可见项里,就继续用它填右侧详情,返回按钮消失。列表滚动位置在 _render 头尾各存一次、取一次,所以跨这三次都还在;详情滚动跟着 _renderedItemId 走,条目没换才恢复。
焦点是另一套规则。重排前 _render 从 shadow root 的 activeElement 读 data-focus-key,重排后按 key 找节点;卡片和导航项在三种布局里都存在,所以焦点能回去。单栏详情标题的 key 是 detail-heading,切回单栏列表时这个节点还在 DOM 里,但父级 .ta-detail-pane 被 display: none 隐藏,focus() 落不下去,焦点掉回 body;_restoreFocus 不会为这种情况硬造一个替代节点。tablet-layout-change 在每次渲染之后发出,previous 是上一次快照。观察器层面至少有三次回调:初始回调(示例里读到 1060,previous 为 null)、竖屏 488(previous 1060)、横屏 860(previous 488);如果首帧量到 0×0,那次也会单独发一次事件。宿主如果像 example 这样在 deviceready 之后才 addEventListener,初始回调已经发过了,初值要从 workspace.layout 读,日志里只会看到后面的切换。
2. 容器尺寸从哪来
插件没有原生代码,拿不到 ArkUI 的窗口对象。它能问的只有 DOM:工作台元素多大,就是多大。
// src/observer.ts
function measureTarget(target: Element | Window, isWindow: boolean): TargetSize {
if (isWindow) {
const view = typeof window !== 'undefined' ? window : null;
if (!view) {
return { width: 0, height: 0 };
}
const doc = view.document;
const docEl = doc && doc.documentElement;
return {
width:
typeof view.innerWidth === 'number'
? view.innerWidth
: docEl
? docEl.clientWidth
: 0,
height:
typeof view.innerHeight === 'number'
? view.innerHeight
: docEl
? docEl.clientHeight
: 0,
};
}
let width = 0;
let height = 0;
const element = target as Element;
if (element && typeof element.getBoundingClientRect === 'function') {
try {
const rect = element.getBoundingClientRect();
width = rect && rect.width ? rect.width : 0;
height = rect && rect.height ? rect.height : 0;
} catch (error) {
width = 0;
height = 0;
}
}
if ((!width || !height) && element) {
width = width || element.clientWidth || (element as HTMLElement).offsetWidth || 0;
height = height || element.clientHeight || (element as HTMLElement).offsetHeight || 0;
}
return { width, height };
}
元素路径优先用 getBoundingClientRect();拿不到或返回 0,退到 clientWidth / offsetWidth。window 路径用 innerWidth / innerHeight,再退到 documentElement.clientWidth。第一帧、嵌入的 WebView 或 jsdom 里都可能量到 0;异常被吞成 0×0,交给纯函数兜底。
观察器盯的是这个元素。ResizeObserver 存在就用它,同时无论如何都挂 resize / orientationchange。每次触发都走同一个 read():重新量一次、resolveLayout() 重算一次,交给 apply() 用 layoutsEqual 比 16 个字段(LAYOUT_KEYS 里的全部布局键),布局没变就不回调。第一次是 apply(true) 强制回调,previous 为 null,调用方不用等第一次 resize;之后才是去重模式。窗口连续拖动时 RO 可能回调几十次;同一个尺寸被 RO 和 resize 各量一次时,layoutsEqual 会把第二次挡掉,但宽高真的变了还是会发事件,别指望只在跨断点时收到一次。
ResizeObserver 的构造和断开都包了 try / catch。有些老 WebView 有构造器但行为不完整,disconnect() 也可能抛;observeLayout 的 disconnect() 幂等,RO 和两个 window 监听一起摘。
RO 和 window.resize 在 ArkWeb 上分工不同。ResizeObserver 盯的是工作台元素本身:宿主把日志条收起、把 footer 改高、把工作台塞进一个新的 flex 容器,只要元素的内容盒尺寸变了,RO 就会回调。window.resize 盯的是视口:ArkWeb 的宿主窗口被拖动、分屏分隔条被拖动、系统旋转完成,视口尺寸变化才会触发。工作台通常只占宿主页面的一部分,只挂 window 事件会漏掉“元素变了但视口没变”的情况;只挂 RO 又会漏掉“视口变了但元素暂时没变”的瞬间。两路都挂,代价是同一尺寸可能被量两次,layoutsEqual 把第二次挡掉。
量到 0 的场合比想象中多。元素还没插入文档、被 display:none 隐藏、父容器高度是 0、路由切换时旧节点已移除新节点还没布局、WebView 的 surface 还没完成第一帧、jsdom 里没有布局引擎,这些都会让 getBoundingClientRect() 返回全 0。measureTarget 先用 rect,再用 clientWidth / offsetWidth,最后还是 0 就交给 resolveLayout(0, 0)。工作台的首次观察如果拿到 0×0,会先按 compact 渲染一次、发一次 tablet-layout-change,等真实尺寸到了再切到 expanded;宿主日志里可能看到一帧 0 × 0 · 竖屏 · compact · 4 栏。那一帧的 0×0 就是当时的真实尺寸,日志里的 compact 是照它算的。
orientationchange 的时机也不保证。ArkWeb 可能先派发事件、后完成视口更新,监听器量到旧宽高,随后 RO 或下一次 resize 会纠正;去重只比较解析后的布局,中间态只要宽高不同就会发一次事件,跨断点只是看起来更明显。宿主如果按事件次数做动画或埋点,要接受“一次旋转可能对应不止一次布局事件”,不要假设一一对应。
单位也要留意。工作台报的是 CSS 像素,ArkWeb 的 getBoundingClientRect()、clientWidth、innerWidth 都是 CSS 像素;HostWindow 的 window.resize() 收物理像素,所以 example 里要乘 densityPixels。如果宿主用 CSS transform 缩放页面,getBoundingClientRect() 返回的是缩放后的尺寸,而 clientWidth 是未缩放的布局尺寸;这个插件按前者算,缩放过的容器会得到偏小或偏大的断点。工作台不要放在 transform: scale() 的容器里;要缩放,交给宿主窗口或 WebView 的 zoom。
3. 59 行的纯函数,和它前面的归一化
布局决策只有 resolveLayout 一个入口:
// src/layout.ts
export function resolveLayout(
width: number,
height: number,
config?: TabletLayoutConfig,
): TabletLayout {
const w = normalizeSize(width);
const h = normalizeSize(height);
const options = resolveOptions(config);
const orientation: Orientation = w > h ? 'landscape' : 'portrait';
const sizeClass: SizeClass =
w < 600 ? 'compact' : w < 840 ? 'medium' : w < 1200 ? 'expanded' : 'large';
const columns = COLUMNS_BY_SIZE[sizeClass];
const margin = MARGIN_BY_SIZE[sizeClass];
const gutter = GUTTER_BY_SIZE[sizeClass];
const landscape = orientation === 'landscape';
let cardColumns: number;
if (w >= 1200) {
cardColumns = 4;
} else if (w >= 840) {
cardColumns = 3;
} else if (w >= 600 && landscape) {
cardColumns = 3;
} else if (w >= 600) {
cardColumns = 2;
} else {
cardColumns = 1;
}
const navigation: NavigationPlacement =
w >= 840 || (w >= 600 && landscape) ? 'rail' : 'bottom';
const paneMode: PaneMode = w >= 840 || (w >= 720 && landscape) ? 'split' : 'single';
const density: Density = h < 500 ? 'compact' : 'comfortable';
const listWidth = clamp(
Math.round(w * options.listWidthRatio),
options.listWidthMin,
options.listWidthMax,
);
return {
width: w,
height: h,
orientation,
sizeClass,
columns,
cardColumns,
margin,
gutter,
navigation,
paneMode,
listWidth,
railWidth: options.railWidth,
bottomBarHeight: options.bottomBarHeight,
headerHeight: density === 'compact' ? options.compactHeaderHeight : options.headerHeight,
density,
isTablet: Math.min(w, h) >= 600,
};
}
入口先归一化:normalizeSize 把非数字、NaN、Infinity、负数一律变成 0;resolveOptions 把 config 里的非法值换成默认值,listWidthMin 大于 listWidthMax 时自动交换,listWidthRatio 超过 1 截到 1,而且不修改传入对象。
config 的默认值也固定:railWidth 88、bottomBarHeight 76、headerHeight 64、compactHeaderHeight 56、listWidthMin 300、listWidthMax 400、listWidthRatio 0.34。写反的 min/max 会交换,ratio 大于 1 截到 1,非有限值和负数回默认;这些处理都在 resolveOptions 里做一次,后面的查表不再判空。
宽度断点与派生值:
| 宽度 | sizeClass | columns | cardColumns | margin / gutter |
|---|---|---|---|---|
| <600 | compact | 4 | 1 | 16 / 8 |
| 600–839 | medium | 8 | 2(横屏 3) | 24 / 16 |
| 840–1199 | expanded | 12 | 3 | 32 / 24 |
| >=1200 | large | 12 | 4 | 40 / 32 |
导航形态:w >= 840,或 w >= 600 且横屏,走侧轨;否则底部导航。单双栏:w >= 840,或 w >= 720 且横屏,走双栏;否则单栏。列表宽度用 clamp(round(w × 0.34), 300, 400)。密度看高度:h < 500 切紧凑,headerHeight 从 64 降到 56。
有两处容易想岔。sizeClass 只看宽度,isTablet 只看短边是否到 600,两者互不封顶。844×390 的手机会拿到 expanded、12 栏、margin 32,同时 isTablet == false、density == compact、headerHeight == 56。宽度够宽就给宽布局,isTablet 不参与 sizeClass 计算。
另一处是方向。orientation 由 w > h 当场算出来,正方形归竖屏,不读 screen.orientation,也不缓存。所以窗口拖拽、分屏、物理旋转在函数眼里是同一件事:宽高变了。
常见路线放在一起看:
| 方案 | 输入 | 问题 |
|---|---|---|
| 设备型号判断 | UA / isTablet | 窗口一拖就错;PC/分屏无法归类 |
| CSS media queries | 视口宽度 | 只管样式,管不了 DOM 结构与状态 |
| 框架级自适应组件 | 容器 | 绑定框架运行时,Cordova 页面引入整框架不划算 |
| 缓存 screen.orientation | 方向 | 方向是派生值;resize 不改 orientation |
| 本库 resolveLayout | 容器宽高 | 纯函数可单测;观察器自动回调;工作台开箱即用 |
边界值都写进了测试向量:839×600 是 medium / 8 栏 / margin 24,840×600 是 expanded / 12 栏 / margin 32;719×400 单栏,720×400 横屏双栏;1199 和 1200 宽的 listWidth 都是 400,1024 宽算出 348,390 宽落到下限 300。
0×0 返回 compact 默认值:4 栏、bottom、single、listWidth 300、isTablet false,不抛异常。窗口初始化、容器还没挂载、屏幕拔插都会短暂量到 0,这里抛异常只会把问题推给调用方。返回值每次都是新对象,测试里有一处 expect(first).not.toBe(second),改第一个的 listWidth 不影响第二个。
归一化和默认值有专门的断言,非有限值、负数、全非法输入各走一遍:
// __tests__/layout.test.ts
it('normalizes non-finite and negative dimensions to zero without throwing', () => {
for (const [width, height, expectedWidth, expectedHeight] of [
[NaN, 100, 0, 100],
[Infinity, 100, 0, 100],
[-1, 100, 0, 100],
[390, NaN, 390, 0],
[390, -100, 390, 0],
] as const) {
const layout = resolveLayout(width, height);
expect(Number.isFinite(layout.width)).toBe(true);
expect(Number.isFinite(layout.height)).toBe(true);
expect(layout.width).toBe(expectedWidth);
expect(layout.height).toBe(expectedHeight);
expect(layout.isTablet).toBe(false);
}
const bothInvalid = resolveLayout(NaN, Infinity);
expect(bothInvalid.width).toBe(0);
expect(bothInvalid.height).toBe(0);
expect(bothInvalid.orientation).toBe('portrait');
expect(bothInvalid.sizeClass).toBe('compact');
expect(bothInvalid.listWidth).toBe(300);
});
这条测试在 __tests__/layout.test.ts 里,和 12 组基准向量、840/1200 边界、配置回退等断言一起跑。整个仓库 4 个测试文件、46 项,npm run verify 的输出是 Test Files 4 passed (4) 和 Tests 46 passed (46)。
4. 布局变了,哪些字段留在原处
工作台的状态全在字段里:导航目标、选中项、视图、待恢复焦点、两个滚动容器、已渲染条目 id。布局变化只改 _layout,这些字段不动,除非契约要求。
// src/workspace.ts
private _handleLayout(layout: TabletLayout): void {
const previous = this._hasLayout ? copyLayout(this._layout) : null;
const initial = !this._hasLayout;
if (this._hasLayout && layoutsEqual(this._layout, layout)) {
return;
}
this._layout = copyLayout(layout) as TabletLayout;
this._hasLayout = true;
this._ensureDestination();
if (initial) {
this._view = 'list';
if (this._layout.paneMode === 'split') {
this._ensureSelection('split');
} else {
this._selectedItemId = null;
}
} else {
if (previous && previous.paneMode === 'split' && this._layout.paneMode === 'single') {
// Collapsing to one pane goes back to the list, even when an item
// was open in the detail pane. No forced detail on rotation.
this._view = 'list';
}
this._ensureSelection(this._layout.paneMode);
}
this._render();
const detail: LayoutChangeDetail = {
layout: copyLayout(this._layout) as TabletLayout,
previous,
};
this._emit(EVENTS.layoutChange, detail);
}
首次布局:单栏清空选中、停在列表;双栏自动选当前目标的首个条目。后续布局:从双栏缩到单栏时把 _view 设回 list,但不把 _selectedItemId 清掉。测试里的断言是缩到 390×844 后 element.selectedId === 'rotation-state',再切回 1024×768,右侧详情仍然是那篇。_ensureSelection 只清掉“当前目标里已经不存在”的选中项;双栏没有选中时补首个条目。
焦点靠 data-focus-key 找回来。卡片是 item:<id>,导航项是 destination:<id>,返回按钮是 back,单栏详情标题是 detail-heading。_openItem 在单栏里把 _pendingFocusKey 设成 detail-heading;_backToList 设成 item:<id>。
// src/workspace.ts
private _restoreFocus(key: string | null): void {
if (!key) {
return;
}
const nodes = Array.from(this._shadow.querySelectorAll('[data-focus-key]'));
let target: HTMLElement | null = null;
for (const node of nodes) {
if (node.getAttribute('data-focus-key') === key) {
target = node as HTMLElement;
break;
}
}
if (target && typeof target.focus === 'function') {
try {
target.focus({ preventScroll: true });
} catch (error) {
try {
target.focus();
} catch (ignored) {
/* focus is best-effort */
}
}
}
}
focus({ preventScroll: true }) 是首选:焦点回来,但不因为聚焦再滚一次。旧实现不支持参数时退回无参 focus(),再失败就放弃。焦点恢复是 best-effort,不能因为一次失败打断整次渲染。
滚动位置在 _render 的头尾处理。头部读 _listScroller.scrollTop 和 _detailScroller.scrollTop,尾部恢复:
// src/workspace.ts(_render 尾部)
this._restoreFocus(focusedKey);
if (this._listScroller) {
this._listScroller.scrollTop = listScrollTop;
}
if (this._detailScroller && sameDetail) {
this._detailScroller.scrollTop = detailScrollTop;
}
this._renderedItemId = this._selectedItemId;
this._dirty = false;
列表滚动每次都恢复;详情滚动只在 sameDetail(_renderedItemId === _selectedItemId)时恢复。换了一篇笔记,详情应该从顶部开始读,把上一篇的 scrollTop 套过来是错的。
导航目标、选中条目、两个滚动位置和键盘焦点都不在 DOM 里。_render 在清空 shadow root 里的工作台容器之前,先把它们读进局部变量,重拼完再写回。宿主如果把 <tablet-adaptive-workspace> 节点整个换掉,这些字段随实例一起消失。 OpenHarmony 接入说明的 7.2 节写了这条边界。
这些字段之外,工作台在 DOM 层面还承诺了几件事:导航是 <nav role="navigation">,卡片和导航项都是原生 <button>,选中项带 aria-current,触控目标最小 44px;tablet-layout-change、tablet-destination-change、tablet-item-select、tablet-back 这组事件都带 bubbles + composed,宿主在 document 上就能收到;颜色、字体、圆角通过 CSS 变量换,内部区域用 ::part() 选中。
5. 方向锁:标准 API → 可选插件 → 明确拒绝
// src/orientation.ts
export async function lockOrientation(orientation: Orientation): Promise<void> {
validateOrientation(orientation);
const reasons: string[] = [];
const screenOrientation = getScreenOrientation();
if (screenOrientation && typeof screenOrientation.lock === 'function') {
try {
await screenOrientation.lock(orientation);
return;
} catch (error) {
reasons.push('screen.orientation.lock failed: ' + describeError(error));
}
} else {
reasons.push('screen.orientation.lock is not available');
}
const plugin = getCordovaScreenOrientation();
const pluginLock = plugin
? typeof plugin.lock === 'function'
? plugin.lock
: typeof plugin.lockOrientation === 'function'
? plugin.lockOrientation
: null
: null;
if (pluginLock) {
try {
await pluginLock.call(plugin, orientation);
return;
} catch (error) {
reasons.push('cordova.plugins.screenorientation failed: ' + describeError(error));
}
} else if (plugin) {
reasons.push(
'cordova.plugins.screenorientation exists but has no lock()/lockOrientation() method',
);
} else {
reasons.push('cordova.plugins.screenorientation is not installed');
}
const failure = new Error(
'lockOrientation("' +
orientation +
'") is not supported in this WebView. ' +
'Use the standard Screen Orientation API in a fullscreen/user-gesture context after deviceready, ' +
'or install cordova-plugin-screen-orientation as an optional fallback. Details: ' +
reasons.join(' | '),
);
failure.name = 'NotSupportedError';
throw failure;
}
参数只接受 'portrait' | 'landscape',其他值抛 TypeError。标准 API 不存在或调用失败、可选插件不存在或缺少 lock 方法、插件调用抛错,每种失败原因都进 reasons,最后拼成一个 NotSupportedError。调用方不会拿到静默 resolve 的假成功,拿到的是一份能直接打日志的失败链:先看 screen.orientation.lock,不可用或失败再看 cordova.plugins.screenorientation,两者都没有才 reject,消息里用 | 分隔各层的原因。
在 ArkWeb PC 上,lockOrientation('landscape') 抛出的消息是这样(Details 后面按层列出原因):
lockOrientation(“landscape”) is not supported in this WebView. Use the standard Screen Orientation API in a fullscreen/user-gesture context after deviceready, or install cordova-plugin-screen-orientation as an optional fallback. Details: screen.orientation.lock is not available | cordova.plugins.screenorientation is not installed
error.name 是 NotSupportedError。如果标准 API 存在但调用被浏览器拒绝,第一段会是 screen.orientation.lock failed: ...,is not available 只留给 API 不存在的情况;如果插件装了但方法抛错,Details 里会多出 cordova.plugins.screenorientation failed: ...。unlockOrientation() 有独立的错误消息,不会复用 lock 的。
宿主 catch 到 NotSupportedError 后可以改调 HostWindow、隐藏方向按钮,或者提示用户手动拖窗口;如果 Promise 静默 resolve,宿主会以为已经锁住,实际窗口仍可旋转,后续布局变化就成了“锁失败但没人知道”。错误消息里带上各层的原因,也方便区分“API 不存在”“API 存在但被用户手势 / fullscreen 限制拒绝”“可选插件装了但自己抛错”这三种情况。代价是每次调用都要走一遍探测,宿主应该在启动时调一次、把结果记下来,别每次点击都试。
ArkWeb 上这条链走到头:screen.orientation.lock 不存在,cordova.plugins.screenorientation 没装,lockOrientation() 按设计 reject。HarmonyOS PC / 2-in-1 上更实际的动作是改窗口大小,于是 example 宿主里加了一个只属于宿主的 HostWindow 插件。
// example/harmonyos/entry/src/main/ets/plugins/HostWindowPlugin.ets
execute(action: string, args: ESObject[], callbackContext: CallbackContext): boolean {
if (action !== 'resize') {
return false;
}
const cssWidth: number = Math.round(Number(args[0]));
const cssHeight: number = Math.round(Number(args[1]));
if (!Number.isFinite(cssWidth) || !Number.isFinite(cssHeight) || cssWidth <= 0 || cssHeight <= 0) {
callbackContext.errorByString('resize requires positive width and height');
return true;
}
// Window.resize() takes physical px; the WebView reports CSS px. Convert
// with the display density so 520 x 1060 means the layout sees 520 x 1060.
const density: number = display.getDefaultDisplaySync().densityPixels;
const width: number = Math.round(cssWidth * density);
const height: number = Math.round(cssHeight * density);
window.getLastWindow(this.context)
.then((win: window.Window) => win.resize(width, height))
.then(() => callbackContext.successByBoolean(true))
.catch((error: Error) => callbackContext.errorByString(error.message));
return true;
}
this.context 是构造函数注入的 UIAbilityContext,execute 只负责 resize。window.resize() 收物理像素,WebView 报的是 CSS 像素,所以先乘 display.getDefaultDisplaySync().densityPixels 再取整。args[0] / args[1] 一律 Number() 后检查有限且为正,非法直接 errorByString,不让 window.resize() 收到 NaN。getLastWindow() 是异步的;execute 返回 true 表示“这个 action 我接了”,结果通过 callback 回。
宿主页面优先走这个桥。resizeHostWindow 带 1200ms 超时:cordova.exec 在桥不可用时可能既不 success 也不 error,没有超时会一直挂。桥失败后才回退到 TabletAdaptive.lockOrientation();都失败时,状态栏同时打出桥和方向锁的错误。这个顺序只在桌面形态成立,手机上通常没有 HostWindow,会直接走方向锁。
HostWindowPlugin.ets 留在 example 宿主里,插件的 files 白名单不含 example,所以发布包里只有 www/、types/、plugin.xml、README、docs 与 LICENSE,HostWindow 那段 ArkTS 不在其中。
6. 发布包里到底装了什么
插件按标准 Cordova npm 结构发布,www/ 与 types/ 是提交进仓库的构建产物,宿主不需要为插件跑 Node 构建:
cordova/
├─ src/layout.ts # 纯函数布局引擎(resolveLayout)
├─ src/observer.ts # 容器测量 + ResizeObserver / window 事件降级
├─ src/orientation.ts # screen.orientation / cordova 插件回退
├─ src/workspace.ts # <tablet-adaptive-workspace> 自定义元素
├─ www/tablet-adaptive.js # 构建产物:唯一运行时文件
├─ types/ # 构建产物:类型声明
├─ __tests__/ # Vitest + jsdom 契约测试(46 项)
├─ example/harmonyos/ # ArkWeb 宿主(含 host-only HostWindow 插件)
└─ docs/ # 布局契约、验证记录、截图

plugin.xml 顶层有 js-module 给 Android/iOS,另一个显式 ohos 块给 hcordova 复制文件:
<!-- plugin.xml -->
<js-module src="www/tablet-adaptive.js" name="TabletAdaptive">
<clobbers target="TabletAdaptive" />
</js-module>
<platform name="ohos">
<js-module src="www/tablet-adaptive.js" name="TabletAdaptive">
<clobbers target="TabletAdaptive" />
</js-module>
</platform>
缺这个块,hcordova 安装时报 pluginConfig.platform.sourceFiles is not iterable。它只复制声明,没有原生实现。
顶层 js-module 与 ohos 块各有各的读者:前者给 Cordova Android/iOS,后者给 hcordova 的复制器,两个平台读不同的配置段。只留 ohos 块,Android 构建时 window.TabletAdaptive 不会注入;只留顶层,hcordova 安装会失败。plugin.xml 同时保留两者;发布前还要跑 xmllint --noout plugin.xml。
构建与验证:
cd cordova
npm install
npm run verify # tsc --noEmit + esbuild 打包 + declaration emit + 全部测试
xmllint --noout plugin.xml
npm pack
最近一次输出:
Test Files 4 passed (4)
Tests 46 passed (46)
xmllint 通过;npm pack 产出 25 个文件、约 3.8 MB,只含运行时、类型、plugin.xml、README、docs 与 LICENSE。Cordova 13.0.0 CLI 的临时 browser 宿主能从 tarball 装上插件,plugin list 显示 com.lqjmac.cordova.tabletadaptive 1.0.0 "TabletAdaptive";14.0.2 CLI 没在这台机器上跑过。
www/tablet-adaptive.js 是 IIFE,带 module.exports 和 window.TabletAdaptive 兼容层;types/ 末尾追加 export as namespace TabletAdaptive;。两个目录都提交进仓库,宿主不需要 Node 工具链。
版本号有三处:src/constants.ts 的 VERSION 是运行时 TabletAdaptive.version,package.json 的 version 决定 npm 包和 IIFE banner,plugin.xml 的 version 是 Cordova 清单版本。构建脚本只从 package.json 读版本写 banner,没有强制校验另外两处,改版本时要一起改。
7. 安装器、方向锁与重渲染的返工
装进 hcordova 宿主时抛 pluginConfig.platform.sourceFiles is not iterable。原因是 plugin.xml 没有显式 <platform name="ohos">,安装器遍历 sourceFiles 时拿到 undefined。
有一版按 screen.orientation 决定单双栏。桌面窗口从 1060 拖到 800,orientation 还是 landscape,单双栏纹丝不动。改成只吃宽高后,拖窗、分屏、旋转在代码里是一回事。
手机横屏 844×390 被判成 expanded / 12 栏,看着像断点写错。宽度够 840,宽布局就该给宽容器;isTablet 只是信息位,不能拿来给 sizeClass 封顶。
第一版把 cardColumns 也用在双栏列表上。860 宽时列表 300px,三列、gutter 24,每张卡片 (300 - 48) / 3 = 84px,标题放不下。现在双栏列表固定 1 列,cardColumns 只在单栏全宽列表生效;workspace.ts 里 effectiveCardColumns = layout.paneMode === 'split' ? 1 : layout.cardColumns。
整页重渲染的版本,旋转后列表回到顶部、焦点掉到 body。现在的做法是重渲染前读 scrollTop 和 data-focus-key,渲染后写回;测试用 setSize(390, 844) 触发窗口 resize,断言选中项还在。
ArkWeb 上 screen.orientation.lock 不存在,可选插件也没装,lockOrientation() 只能 reject。宿主用 HostWindow 改窗口尺寸解决桌面形态;插件不假装锁成功。
items="[...]" 能解析,但只适合短小静态数据。用户字段全部走 textContent;XSS 测试塞进 <script>、<img onerror>、<iframe>、<svg onload>,断言 shadow root 里 img、script、iframe、svg 全为空,window.__xss 还是 undefined。属性写法只是便利,数据接口还是 JS 属性;宿主用模板拼 JSON 时,转义要自己保证。工作台不会替宿主做 JSON 校验,解析失败只会 warn 并当成空数组。
8. 装完插件,鸿蒙侧怎么跑
安装:
# AtomGit
cordova plugin add https://atomgit.com/lqjmac/cordova-plugin-tablet-adaptive.git
# 本地开发
cordova plugin add ../cordova
# hcordova(HarmonyOS 宿主)
hcordova plugin add ../cordova
安装后 window.TabletAdaptive 就位、<tablet-adaptive-workspace> 自动注册,发布包内已含 www/ 与 types/。只想用布局引擎或观察器的,单独调 resolveLayout / observeLayout 即可。
鸿蒙侧完整流程:
cd example
npm run host:prepare # 快照 + plugin add + cordova.js + 页面同步
cd harmonyos && ohpm install --all
hvigorw assembleHap --mode module -p product=default -p buildMode=debug --no-daemon
hdc install -r entry/build/default/outputs/default/entry-default-signed.hap
hdc shell aa start -a EntryAbility -b com.lqjmac.tabletadaptive.host
文档在仓库里:仓库说明写 API、布局规则、主题变量与安全边界;OpenHarmony 接入说明写鸿蒙基线、宿主构建流程和接入边界;布局契约文档管断点、导航/分栏规则、状态保持与可访问性契约;验证记录存自动化测试、构建产物与 HarmonyOS PC 实测记录;__tests__/ 下是 46 项 Vitest 契约测试。
验证记录里,HarmonyOS PC(MOR-M1,3120×2080,HarmonyOS 7.0.0.111)上 signed debug HAP 构建、安装、启动成功:初始容器 1060×520,竖屏按钮后 488×704,横屏按钮后 860×486,切换“今天”后列表过滤为 1 篇;这三次读数都没有经过方向锁。
其他待补的部分:系统物理旋转、分屏/折叠屏拖拽、Android WebView / iOS WKWebView 回归、装上 cordova-plugin-screen-orientation 之后的方向锁回退、Cordova 14.0.2 CLI 的完整平台构建。
如果重做,会先加一个只读的能力查询,让宿主在渲染按钮前就知道方向锁能不能用,省得点了再 catch。工作台的重排现在是清空 shadow root 里的容器后重拼 DOM,再靠 data-focus-key 和两个 scrollTop 把状态搬回去;按 key 做增量更新更容易让焦点和滚动保持不动,但 diff 代码会比现在这套拼 DOM 的代码更难维护,包也会变大,暂时不划算。观察器可以考虑显式指定 box: 'border-box',让触发条件和测量盒子对齐;不过现在“RO 只当触发器、尺寸统一从 rect 读”的口径更简单,测试也更好写。
3



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



