SuperAPI AI Directory

hmos-multidevice-screen-window-size

General & other

View repository

Updated 10-15 16:44

About this skill

Screen window size adaptation

Skill definition

Field Content
skill_id screen-window-size
skill_name 屏幕窗口尺寸适配
one_line_purpose Provide breakpoint strategies, structure switching strategies, and window listening strategies for multi-device layouts.
device_scope phone / tablet / tv / 2in1
problem_scope 断点体系、响应式布局、窗口变化监听、媒体查询、字体缩放、显示密度
not_in_scope 纯业务逻辑重构、与尺寸无关的视觉微调
primary_outputs primary_scene、device_constraints、code_touchpoints、fix_plan、verification_matrix

Core constraints

  • First determine whether the problem is component-level adaptive or page-level responsive, then choose the solution.
  • Prioritize reusing the unified breakpoint system; do not introduce new breakpoints that conflict with existing thresholds.
  • When structure switching is involved, prioritize using GridRow、GridCol or other responsive containers, rather than scattered conditional branches.
  • When window change listening is involved, the listening entry point, state synchronization, and listener cancellation logic must be specified.
  • When horizontal window or special aspect ratio support is required, it must be specified whether width, vertical breakpoints, or aspect ratio is the primary determining condition.
  • Before the structural changes and content trade-offs under different breakpoints are provided, the solution must not be claimed to be complete.
  • FIX At the stage, the single-screen baseline experience must be protected first, then multi-screen issues handled; "multi-screen improvement but obvious single-screen regression" is prohibited.
  • For image stretching issues, prioritize fixing the root cause in "container constraints and rendering mode"; it is prohibited to create or conceal issues through artificial stretching coefficients.
  • When only fixing image stretching, do not create large-area blank space by limiting the width of the entire page's main content; prioritize limiting the rendering width of the target image or the container strategy.
  • When font scaling or display density changes are involved, you must subscribe to onConfigurationUpdate and through AppStorage global synchronization; environment variable responses must not be omitted.
  • When maxFontScale limits are involved, it must be specified whether it is an application-level configuration or a component-level property, as well as the basis for the limit multiplier.

Workflow

Input

The user describes a multi-device layout requirement (such as "adapt to tablet") or a layout abnormality issue (such as "layout breaks on foldable screen").

Process

  1. Determine the problem type: requirement design (REQ) / development implementation (DEV) / bug fix (FIX) / feature verification (VAL).
  2. Read specifications (for REQ): first route to SIZE-00, read the multi-device adaptation specification requirements.
  3. Scenario routing: route to SIZE-01~05 according to problem characteristics:
    • Breakpoints / responsive layout / window listening → SIZE-01
    • Truncation / blank space / overflow / compression → SIZE-02
    • Offset / misalignment / alignment abnormality / hierarchy disorder → SIZE-03
    • Stacking / occlusion / incorrect container selection → SIZE-04
    • Font scaling / display density / elderly-friendly adaptation / environment variables not synchronized → SIZE-05
  4. Read scenario documents: according to the matched scenario and problem type (stage), read the corresponding reference and assets files in that scenario's "File Reading".
  5. Deliver by stage: output the corresponding contract fields according to the matched stage (see "Stage Output Contract").

Output

Output the corresponding contract fields according to the matched stage (REQ/DEV/FIX/VAL).

Stage labels

Label Stage Current module focus
REQ Requirement analysis and design Breakpoint boundaries, device scope, structural change principles
DEV Development Breakpoint state management, container selection, listener placement
FIX Issue fixing Breakpoint mismatch, layout breakage, state not synchronized
VAL Feature verification Breakpoint switching evidence, window change evidence, layout stability

Unified output fields

  • Routing fields:active_phases、primary_phase、primary_scene、secondary_scenes、resources_used
  • REQ:device_constraints、capability_boundary、acceptance_focus
  • DEV:code_touchpoints、reuse_resources、implementation_notes、integration_risks
  • FIX:problem_profile、root_cause_hypothesis、fix_plan、regression_watchlist
  • VAL:verification_matrix、evidence_requirements、pass_criteria、residual_risks

Field definitions

  • device_constraints: Refers to the hard adaptation constraints brought by device form factor, window state, input method, or system area. In screen-window-size , it is usually the breakpoint range, the primary determination dimension, and whether structural switching occurs under different sizes. It is not an API list, nor is it a code modification point.
  • capability_boundary: Refers to what the current solution supports, what it does not support, and under which device or window conditions degradation or no handling is required.
  • acceptance_focus: Refers to the phenomena, evidence, or boundary conditions that must be confirmed as key points during the requirements phase acceptance.
  • In scene deliverables.REQ appears device_constraints, meaning "once this scenario is hit, this field must be produced during the requirements analysis phase", not a redefinition of the field.

AI retrieval requirements

  • All window size adaptation scenarios must first hit SIZE-00and read the specification requirements.
  • When involving breakpoint naming, threshold unification, breakpoint mismatch, GridRow/GridCol, responsive layout, or window change listening, prioritize hitting SIZE-01。
  • When involving component truncation, blank space, size overflow, or compression, prioritize hitting SIZE-02。
  • When involving component offset, misalignment, alignment anomalies, or hierarchy disorder, prioritize hitting SIZE-03。
  • When involving component stacking, occlusion, truncation, or incorrect layout container selection, prioritize hitting SIZE-04。
  • When involving font scaling, display density, accessibility for the elderly, or layout anomalies caused by unsynchronized environment variables, prioritize hitting SIZE-05。
  • When involving in-app split screen (startAbility + StartOptions launching another UIAbility for split-screen display), prioritize hitting SIZE-06。
  • When the request contains both "how to change" and "how to verify", set active_phases: [DEV, VAL]。
  • When the following signals appear, the primary hit must be SIZE-02, and link VAL:
    • The first image/carousel image/banner is normal on a single screen, but stretches or focuses abnormally on multiple screens
    • ImageFit.Cover, container height, or widescreen enlargement causing missing or cropped content
    • component_stretch, the image is stretched on all sides, or center focus is distorted

Resource index

SIZE-00 Multi-device window adaptation specification

Phase:REQ | Priority:P0

Applicable scenarios

  • All requirements involving screen window size adaptation must first enter this scenario to read the specification requirements
  • Need to understand the standard specifications, design principles, and constraints for HarmonyOS multi-device adaptation

Inapplicable scenarios

  • Specification analysis has been completed; directly enter the development or fix phase (skip this scenario and go directly to SIZE-01 to SIZE-05)
  • Pure business logic refactoring, not involving window size adaptation

File reading

REQ phase(read reference)

  • ./references/adaptation-specification.md - Multi-device adaptation specification requirements

DEV phase(read assets according to best practices)

  • ./assets/PipWindow.ets ⭐ Recommended solution - Complete example of SPEC-05 picture-in-picture capability (PipManager + CustomNodeController + page integration)

SIZE-01 Multi-device adaptation window size layout

Phase:REQ / DEV / FIX | Priority:P0

Applicable scenarios

  • Involving breakpoint system design and threshold definition
  • Using GridRow/GridCol to implement responsive layout
  • Need to listen for window size changes (rotation, folding, dragging)
  • Problem: breakpoints are inconsistent, or the layout does not update with size changes

Inapplicable scenarios

  • Related only to safe area, keyboard, and fold
  • Static layout, not dependent on runtime size changes

Key decisions

  • System breakpoints vs custom breakpoints
  • Which is the primary criterion: width/vertical breakpoints/aspect ratio
  • Page skeleton and container types (GridRow, Stack, Flex)
  • Window listening method: windowSizeChange / media query
  • Synchronization granularity and debounce strategy

File reading

REQ phase(read reference)

  • ./references/breakpoint_system.md - Breakpoint system design principles
  • ./references/responsive_layout.md - Four responsive layouts (repetitive layout, split-column layout, shift layout, indent layout)
  • ./references/adaptive_layout.md - Seven adaptive capabilities (stretch, scale, hide, proportion, wrap, evenly divide, extend)
  • ./references/window_size_detection.md - Window listening mechanism

DEV phase(read assets according to best practices)

Breakpoint system

  • ./assets/SystemBreakpointExample.ets ⭐ Recommended solution - System breakpoint enum
  • ./assets/BreakpointConstants.ets - Alternative solution - Custom breakpoint constants
  • ./assets/BreakpointType.ets - Simplified conditional rendering
  • ./assets/BreakpointObserver.ets - Breakpoint observer

Responsive layout

  • ./assets/GridRowBreakpoints.ets - GridRow built-in breakpoints
  • ./assets/GridRowExample.ets - Grid layout example
  • ./assets/GridColOffset.ets - Grid offset configuration

Window listening

  • ./assets/WindowSizeChangeListener.ets ⭐ Recommended solution - Directly listen for window size changes
  • ./assets/MediaQueryManager.ets - Media query manager
  • ./assets/MediaQueryExample.ets - Media query example

FIX phase(read reference)

  • ./references/breakpoint_system.md - Breakpoint system design principles
  • ./references/adaptive_layout.md - Seven adaptive capabilities (stretch, scale, hide, proportion, wrap, evenly divide, extend)
  • ./references/window_size_detection.md - Window listening mechanism

SIZE-02 Size anomaly repair

Phase:DEV / FIX | Priority:P1

Applicable scenarios

  • Component width/height does not adapt on multiple devices
  • Problem: truncation, blank space, overflow, compression, content cut off

Inapplicable scenarios

  • Position offset only (see SIZE-03)
  • Wrong layout container selection (see SIZE-04)

Key decisions

  • Problem type: fixed size / missing breakpoint / space competition
  • Size attributes and breakpoint branches that need adjustment

Special rules for image stretching (component_stretch)

Root cause determination (must determine before modifying)

  • If "normal on a single screen, abnormally stretched on multiple screens," prioritize determining it as: under large widths, the image container and rendering strategy do not match, rather than the business actively adjusting the stretch value.
  • If "missing content" occurs, prioritize determining it as:ImageFit.Cover and container height being too low causing cropping, rather than an issue with image resources.

Prohibited solutions (any one hit is judged high risk)

  • Creating or offsetting stretching by adjusting the "artificial stretch ratio," lacking a basis in real engineering constraints.
  • Restricting the width of the main content of the entire page to avoid stretching, causing obvious blank space and wasted interaction area.
  • Verifying only multiple screens and not a single screen; or making subjective judgments based only on screenshots without providing layout boundary evidence.

Recommended solution (execute in order)

  1. First lock the baseline look on a single screen: keep the first image fully visible at full width on a single screen, without obvious narrowing into a thin strip.
  2. Suppress excessive magnification on large screens again: prioritize limiting the target image rendering width or setting a reasonable upper limit on container height, rather than limiting the entire page width.
  3. Handle cropping last: without introducing stretching, increase the visible height of the first-image container to reduce loss of content at the bottom.

Acceptance gates (GoodCase must not be claimed unless all are satisfied)

  • Single-screen gate: after the fix, the first image on a single screen must not be noticeably smaller than before the fix; if the single-screen appearance degrades, it must be rolled back and redone.
  • Multi-screen gate: on dual-screen/triple-screen, there must be no "enhanced stretched feel" caused by continued magnification.
  • Evidence gate: screenshots and layout dumps must both be provided as Image bounds comparison evidence.

File reading

DEV phase(read assets)

  • ./assets/small-square-screen-collapse.md - Small square screen bottom bar collapse
  • ./assets/scroll-page-content-clipped-by-full-height.md - Scrolled content clipping
  • ./assets/alphabetindexer-autocollapse.md - Indexer auto-collapse

FIX phase(read reference)

  • ./references/size-anomaly.md - Problem classification and root cause analysis

SIZE-03 Position anomaly fix

Phase:DEV / FIX | Priority:P1

Applicable scenarios

  • The component's relative or absolute position does not adapt across multiple devices
  • Problem: offset, misalignment, abnormal alignment, layer disorder, component moving off-screen

Inapplicable scenarios

  • Size truncation only (see SIZE-02)
  • Incorrect layout container selection (see SIZE-04)

Key decisions

  • Problem type: absolute positioning / anchor adaptation / alignment method / margin accumulation
  • Fix strategy for positioning method

File reading

DEV phase(read assets) No content yet

FIX phase(read reference)

  • ./references/position-anomaly.md - Position anomaly classification and root cause

SIZE-04 Layout anomaly fix

Phase:DEV / FIX | Priority:P1

Applicable scenarios

  • Improper selection or configuration of layout container
  • Problem: stacking, occlusion, truncation, layout disorder, GridRow not reducing columns

Inapplicable scenarios

  • Component size issues only (see SIZE-02)
  • Component position issues only (see SIZE-03)

Key decisions

  • Problem type: container selection / breakpoint reference frame / missing scrolling / nested structure
  • Replacement or configuration fix plan for layout container

File reading

DEV phase(read assets)

  • ./assets/gridrow-breakpoints.md - GridRow breakpoint issue fix
  • ./assets/stack-overlap-occlusion.md - Stack stacking occlusion fix
  • ./assets/row-displaypriority-truncation.ets - Row/Column component truncation priority
  • ./assets/SplitScreenExample.ets - Truncation issue fix in split-screen mode

FIX phase(read reference)

  • ./references/layout-anomaly.md - Layout anomaly classification and root cause

SIZE-05 Font scaling and display density adaptation

Phase:REQ / DEV / FIX | Priority:P1

Applicable scenarios

  • Page layout becomes abnormal after the user changes the font size in "Settings" (text overflow, component occlusion, truncation)
  • Layout becomes disordered after the user changes the display size scaling in "Settings"
  • Need to implement accessibility support for the elderly to ensure the layout remains stable after font enlargement
  • Need to globally synchronize font scaling and screen density environment variables

Not applicable scenarios

  • Related only to breakpoint or window size changes (see SIZE-01)
  • Only component size truncation and unrelated to font/density (see SIZE-02)
  • Pure business logic refactoring, does not involve system environment variables

Key decisions

  • Font restriction strategy: application-level fontSizeMaxScale vs component-level maxFontScale vs managed within the application
  • Environment variable subscription method:onConfigurationUpdate + AppStorage Global synchronization
  • Density change listening method:UIObserver.on('densityUpdate') + onSizeChange
  • Component size constraint strategy:constraintSize Restrict maximum/minimum size

File reading

REQ phase(read reference)

  • ./references/font_scale_display_density.md - Principles of font scaling and display density adaptation

DEV phase(read assets) No content yet

FIX phase(read reference)

  • ./references/font_scale_display_density.md - Principles of font scaling and display density adaptation

SIZE-06 In-app split screen

Phase:REQ / DEV / FIX | Priority:P0

Applicable scenarios

  • Through startAbility + StartOptions start another UIAbility to achieve system-level split screen
  • After split screen, page truncation, data not passed, parameters not updated, layout abnormal
  • Need two independent windows for parallel operation

Not applicable scenarios

  • Related only to breakpoint responsive layout (see SIZE-01)
  • Parallel View EasyGo split-column adaptation (see SIZE-00 adaptation-specification SPEC-08)
  • Pure floating window adaptation does not involve split screen (see adaptation-specification SPEC-16)
  • After split screen, only component size truncation and no direct causal relationship with split screen window size (see SIZE-02)

Key decisions

  • Split screen orientation:preferMultiWindowOrientation value (default / portrait / landscape / landscape_auto)
  • Cross-Ability data communication architecture:Want.parameters → LocalStorage → loadContent(path, storage) → @LocalStorageLink
  • Target page reuse strategy: whether to reuse existing NavDestination component (requires Navigation wrapper), or an independent page

File reading

REQ phase(read reference)

  • ./references/split-screen.md - Complete guide to in-app split screen

DEV phase(read assets according to best practices)

  • ./assets/SplitScreenExample.ets - Fixing truncation issues in split screen mode

FIX phase(read reference)

  • ./references/split-screen.md - Common issues table for in-app split screen

Key code patterns

  • Data flow:Index.onClick(分屏) → startAbility(want+parameters, SPLIT_SECONDARY) → EntryAbility1.onCreate/onNewWant → writeParamsToStorage(want) → loadContent('DetailPage', storage) → @Entry({ useSharedStorage: true }) + @LocalStorageLink binding
  • Target page reuses existing NavDestination: outer Navigation wrapper + .hideTitleBar(true) hide outer title bar + .navDestination(pageMap) load existing component

Phase output contract

REQ

  • Must output:active_phases、primary_phase、primary_scene、secondary_scenes
  • Must output:device_constraints、capability_boundary、acceptance_focus
  • Additional requirements: explain the minimum supported breakpoint set, and whether structural changes occur at each breakpoint

DEV

  • Must output:code_touchpoints、reuse_resources、implementation_notes、integration_risks
  • Additional requirements: clarify who maintains the breakpoint state, who listens to window changes, and which container carries the layout

FIX

  • Must output:problem_profile、root_cause_hypothesis、fix_plan、regression_watchlist
  • Additional requirements: 1. Clarify whether the problem is a breakpoint boundary error, container configuration error, or listening synchronization error 2. Must explicitly provide single_screen_guard(single-screen non-degradation strategy) and multi_screen_guard(multi-screen non-stretch strategy) 3.fix_plan Must include the execution order of "single-screen baseline first, then multi-screen suppression, then cropping optimization"

VAL

  • Must output:verification_matrix、evidence_requirements、pass_criteria、residual_risks
  • Additional requirements: 1. At least cover small / medium / large or the project-equivalent breakpoint, and provide screenshots, layout dumps, or window size evidence 2. Image stretching issues must cover the three window width levels of single-screen/dual-screen/triple-screen (project-equivalent values such as 1008 / 2048 / 3184) 3.pass_criteria Must include the following objective items:
    • Page path is correct (target GoodCase page)
    • Triple-screen Image bounds can be compared and shows no abnormal stretching trend
    • The visible height of the first image on single-screen is not lower than the pre-fix baseline