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、GridColor 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.
FIXAt 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
onConfigurationUpdateand throughAppStorageglobal synchronization; environment variable responses must not be omitted. - When
maxFontScalelimits 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
- Determine the problem type: requirement design (REQ) / development implementation (DEV) / bug fix (FIX) / feature verification (VAL).
- Read specifications (for REQ): first route to
SIZE-00, read the multi-device adaptation specification requirements. - 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
- Breakpoints / responsive layout / window listening →
- 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".
- 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_focusDEV:code_touchpoints、reuse_resources、implementation_notes、integration_risksFIX:problem_profile、root_cause_hypothesis、fix_plan、regression_watchlistVAL: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. Inscreen-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.REQappearsdevice_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+StartOptionslaunching another UIAbility for split-screen display), prioritize hittingSIZE-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 linkVAL:- 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 contentcomponent_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.Coverand 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)
- 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.
- 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.
- 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 boundscomparison 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
fontSizeMaxScalevs component-levelmaxFontScalevs managed within the application - Environment variable subscription method:
onConfigurationUpdate+AppStorageGlobal synchronization - Density change listening method:
UIObserver.on('densityUpdate')+onSizeChange - Component size constraint strategy:
constraintSizeRestrict 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+StartOptionsstart 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:
preferMultiWindowOrientationvalue (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 })+@LocalStorageLinkbinding - 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) andmulti_screen_guard(multi-screen non-stretch strategy) 3.fix_planMust 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 / largeor 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 as1008 / 2048 / 3184) 3.pass_criteriaMust include the following objective items:- Page path is correct (target GoodCase page)
- Triple-screen
Image boundscan 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