HarmonyOS Floating Window Adaptation: Three-Tier UI for Minimal Usable Interface

Introduction

The author noticed that in a floating window, a result-confirmation page pushed the primary button too far down because all full-screen content (title, status, summary, metadata, recognized content, suggestions, primary and secondary buttons) simply stacked in the same order. On the Pura X Max (outer screen 5.4" 1848×1264, inner screen 7.7" 2584×1828, HarmonyOS 6.1), folded, split-screen, and floating-window modes create narrow viewports where the main action gets buried.

Problem: Full-Screen Content Blocks Primary Action in Small Windows

In full-screen, users read top-to-bottom then tap the button — no friction. In a floating window, the same vertical stack forces users to scroll through metadata, recognized text, and suggestions before reaching the button. The floating window is a transient processing area, not a reading view; users typically just want to confirm a record, save a reminder, or handle a result and dismiss it.

Solution: Three Information Tiers

1. full — Complete Context (≥ 840 vp)

Shows main card plus right-side auxiliary panel: title, status, summary, metadata, recognized content, suggestions, and multiple actions. Suitable for full-screen, unfolded, or wide free-form windows. Threshold private readonly fullWidth: number = 840; is example-specific; raise it if side panel would squeeze the main card.

2. compact — Summary + Primary Action (≥ 620 vp)

Hides auxiliary panel and full recognized content; keeps summary and secondary buttons. Threshold private readonly compactWidth: number = 620;. Content collapses stepwise: first side panel, then full recognized text, finally entering minimal. This gradual collapse is easier to maintain than maintaining two separate page versions.

3. minimal — Only Current Action (< 620 vp)

Retains only title, status, primary button, and minimal feedback (e.g., operation count). All else hidden. No further sub-states; a clear boundary keeps code simple. Layout mode determined by:

private getLayoutMode(): string {
  const width = this.getEffectiveWidth();
  if (width >= this.fullWidth) return 'full';
  if (width >= this.compactWidth) return 'compact';
  return 'minimal';
}

Implementation: Collapse Within a Single Card

Instead of separate pages, one card conditionally renders fields:

Summary shows when !isMinimal() Metadata and recognized content show only in isFull() Primary button label shortens in minimal:

Button(this.isMinimal() ? '处理' : '保存为待办提醒')

Card padding, title size, corner radius, and shadow also adapt per tier.

Centralizing these rules avoids drift when fields are added later.

Engineering Prerequisites: Window Mode Configuration

Layout code only handles rendering; module.json5 must declare support for floating and split windows:

"supportWindowMode": ["fullscreen", "split", "floating"]

Also ensure deviceTypes includes phone, tablet, 2in1. Without these, the app cannot enter floating/split modes regardless of layout logic.

Runtime Verification

Demo uses previewWidth and toggle buttons to simulate three states on one emulator. Real projects replace getEffectiveWidth() with direct pageWidth from onAreaChange:

private getEffectiveWidth(): number {
  return this.pageWidth;
}

onAreaChange

captures the actual page area width, not device model or orientation — critical because the same device can shift from unfolded to a tiny floating window.

Practical Boundaries

minimal is not for forms : Suits quick actions (confirm reminder, pause timer, save result). Complex editing, long forms, image cropping, or long reads should show a "open full page" entry instead.

Hidden content must have a return path : Metadata, source, timestamps, recognized text reappear when window widens or user taps "view details." Define per-field tier mapping in one place to prevent accidental bloat in minimal mode.

Complete Code Reference

The article ends with a full ArkTS component ( @Entry @Component struct Index) demonstrating the three-tier logic, builders for header, main card, side panel, metadata rows, and preview buttons, plus onAreaChange for real width tracking.