| name | hmos-multidevice-screen-window-size |
| description | Handle HarmonyOS screen and window size adaptation, including breakpoint systems, responsive layouts, GridRow/GridCol usage, window size observation, and multi-device layout changes. |
屏幕窗口尺寸适配
技能定义
| 字段 | 内容 |
|---|
skill_id | screen-window-size |
skill_name | 屏幕窗口尺寸适配 |
one_line_purpose | 为多设备布局提供断点策略、结构切换策略和窗口监听策略。 |
device_scope | phone / tablet / tv / 2in1 |
problem_scope | 断点体系、响应式布局、窗口变化监听、媒体查询、字体缩放、显示密度 |
not_in_scope | 纯业务逻辑重构、与尺寸无关的视觉微调 |
primary_outputs | primary_scene、device_constraints、code_touchpoints、fix_plan、verification_matrix |
核心约束
- 先判断问题属于组件级自适应还是页面级响应式，再选方案。
- 优先复用统一断点体系，不要引入与现有阈值冲突的新断点。
- 涉及结构切换时，优先使用
GridRow、GridCol 或其他响应式容器，而不是零散条件分支。
- 涉及窗口变化监听时，必须说明监听入口、状态同步和取消监听逻辑。
- 需要横向窗口或特殊比例支持时，必须说明宽度、纵向断点或高宽比谁是主判定条件。
- 未给出不同断点下的结构变化和内容取舍前，不得宣称方案完整。
FIX 阶段必须先保护单屏基线体验，再处理多屏问题；禁止出现“多屏改善但单屏明显退化”。- 针对图片拉伸问题，优先修复“容器约束与渲染模式”的根因，禁止通过人为拉伸系数制造或掩盖问题。
- 仅修复图片拉伸时，不得通过限制整页主内容宽度制造大面积留白；优先限制目标图片的渲染宽度或容器策略。
- 涉及字体缩放或显示密度变化时，必须订阅
onConfigurationUpdate 并通过 AppStorage 全局同步，不得遗漏环境变量响应。
- 涉及
maxFontScale 限制时，必须说明是应用级配置还是组件级属性，以及限制倍数的依据。
Workflow
Input
用户描述一个多设备布局需求（如"适配平板"）或布局异常问题（如"折叠屏上布局断裂"）。
Process
- 判断问题类型：需求设计（REQ）/ 开发实现（DEV）/ Bug 修复（FIX）/ 功能验证（VAL）。
- 读取规格(针对REQ)：先路由到
SIZE-00，读取多设备适配规格要求。
- 场景路由：根据问题特征路由到 SIZE-01~05：
- 断点 / 响应式布局 / 窗口监听 →
SIZE-01
- 截断 / 留白 / 溢出 / 压缩 →
SIZE-02
- 偏移 / 错位 / 对齐异常 / 层级错乱 →
SIZE-03
- 堆叠 / 遮挡 / 容器选择错误 →
SIZE-04
- 字体缩放 / 显示密度 / 适老化 / 环境变量未同步 →
SIZE-05
- 读取场景文档：根据匹配到的场景和问题类型（阶段），读取该场景「文件读取」中对应的 reference 和 assets 文件。
- 按阶段交付：根据匹配的阶段输出对应契约字段（见「阶段输出契约」）。
Output
按匹配的阶段（REQ/DEV/FIX/VAL）输出对应契约字段。
阶段标签
| 标签 | 阶段 | 当前模块关注点 |
|---|
REQ | 需求分析设计 | 断点边界、设备范围、结构变化原则 |
DEV | 开发 | 断点状态管理、容器选型、监听落点 |
FIX | 问题修复 | 断点错配、布局断裂、状态未同步 |
VAL | 功能验证 | 断点切换证据、窗口变化证据、布局稳定性 |
统一输出字段
- 路由字段：
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
字段释义
device_constraints：指由设备形态、窗口状态、输入方式或系统区域带来的适配硬约束。在 screen-window-size 中，通常是断点范围、主判定维度和不同尺寸下是否发生结构切换。它不是 API 列表，也不是代码修改点。capability_boundary：指当前方案支持到哪里、不支持什么、在哪些设备或窗口条件下需要降级或不处理。acceptance_focus：指需求阶段验收时必须重点确认的现象、证据或边界条件。- scene 中
deliverables.REQ 出现 device_constraints，表示“该场景一旦命中，在需求分析阶段必须产出这个字段”，不是对字段再定义一次。
AI 检索要求
- 所有窗口尺寸适配场景都必须先命中
SIZE-00，读取规格要求。
- 涉及断点命名、阈值统一、断点错配、GridRow/GridCol、响应式布局、窗口变化监听时，优先命中
SIZE-01。
- 涉及组件截断、留白、尺寸溢出或压缩时，优先命中
SIZE-02。
- 涉及组件偏移、错位、对齐异常或层级错乱时，优先命中
SIZE-03。
- 涉及组件堆叠、遮挡、截断或布局容器选择错误时，优先命中
SIZE-04。
- 涉及字体缩放、显示密度、适老化或环境变量未同步导致布局异常时，优先命中
SIZE-05。
- 涉及应用内分屏（
startAbility + StartOptions 启动另一个 UIAbility 分屏显示）时，优先命中 SIZE-06。
- 当请求同时包含"怎么改"和"怎么验"时，设置
active_phases: [DEV, VAL]。
- 出现以下信号时，必须主命中
SIZE-02，并联动 VAL：
- 首图/轮播图/横幅在单屏正常，多屏拉伸或聚焦异常
ImageFit.Cover、容器高度、宽屏放大导致内容缺失或裁切component_stretch、图片四周被拉开、中心聚焦失真
资源索引
SIZE-00 多设备窗口适配规格
阶段：REQ | 优先级：P0
适用场景
- 所有涉及屏幕窗口尺寸适配的需求，必须先进入此场景读取规格要求
- 需要了解 HarmonyOS 多设备适配的标准规范、设计原则和约束条件
不适用场景
- 已完成规格分析，直接进入开发或修复阶段（跳过此场景，直接进入 SIZE-01 至 SIZE-05）
- 纯业务逻辑重构，不涉及窗口尺寸适配
文件读取
REQ 阶段（读取 reference）
./references/adaptation-specification.md - 多设备适配规格要求
DEV 阶段（按最佳实践读取 assets）
./assets/PipWindow.ets ⭐ 推荐方案 - SPEC-05 画中画能力完整示例（PipManager + CustomNodeController + 页面集成）
SIZE-01 多设备适配窗口尺寸布局
阶段：REQ / DEV / FIX | 优先级：P0
适用场景
- 涉及断点系统设计、阈值定义
- 使用 GridRow/GridCol 实现响应式布局
- 需要监听窗口尺寸变化（旋转、折叠、拖拽）
- 问题：断点不一致、布局未随尺寸变化更新
不适用场景
- 仅与安全区、键盘、折痕相关
- 静态布局，不依赖运行时尺寸变化
关键决策
- 系统断点 vs 自定义断点
- 宽度/纵向断点/高宽比谁是主判定条件
- 页面骨架和容器类型（GridRow、Stack、Flex）
- 窗口监听方式：windowSizeChange / media query
- 同步粒度和防抖策略
文件读取
REQ 阶段（读取 reference）
./references/breakpoint_system.md - 断点系统设计原理./references/responsive_layout.md - 四种响应式布局（重复布局、分栏布局、挪移布局、缩进布局）./references/adaptive_layout.md - 七种自适应能力（拉伸、缩放、隐藏、占比、折行、均分、延伸）./references/window_size_detection.md - 窗口监听机制
DEV 阶段（按最佳实践读取 assets）
断点系统
./assets/SystemBreakpointExample.ets ⭐ 推荐方案 - 系统断点枚举./assets/BreakpointConstants.ets - 备选方案 - 自定义断点常量./assets/BreakpointType.ets - 简化条件渲染./assets/BreakpointObserver.ets - 断点观察器
响应式布局
./assets/GridRowBreakpoints.ets - GridRow 内置断点./assets/GridRowExample.ets - 栅格布局示例./assets/GridColOffset.ets - 栅格偏移配置
窗口监听
./assets/WindowSizeChangeListener.ets ⭐ 推荐方案 - 直接监听窗口尺寸变化./assets/MediaQueryManager.ets - 媒体查询管理器./assets/MediaQueryExample.ets - 媒体查询示例
FIX 阶段（读取 reference）
./references/breakpoint_system.md - 断点系统设计原理./references/adaptive_layout.md - 七种自适应能力（拉伸、缩放、隐藏、占比、折行、均分、延伸）./references/window_size_detection.md - 窗口监听机制
SIZE-02 尺寸异常修复
阶段：DEV / FIX | 优先级：P1
适用场景
- 组件宽度/高度在多设备上不适配
- 问题：截断、留白、溢出、压缩、内容被切掉
不适用场景
- 仅位置偏移（见 SIZE-03）
- 布局容器选择错误（见 SIZE-04）
关键决策
- 问题类型：固定尺寸 / 断点缺失 / 空间竞争
- 需要调整的尺寸属性和断点分支
图片拉伸专项规则（component_stretch）
根因判断（必须先判断再改）
- 若“单屏正常、多屏异常拉伸”，优先判定为：大宽度下图片容器与渲染策略不匹配，而非业务主动调节拉伸值。
- 若出现“内容缺失”，优先判定为：
ImageFit.Cover 与容器高度过低导致裁切，而非图片资源问题。
禁止方案（命中任一即判高风险）
- 通过调整“人为拉伸倍率”来制造或抵消拉伸现象，缺乏真实工程约束依据。
- 为了避免拉伸而限制整页主内容宽度，导致明显留白和交互区域浪费。
- 仅验证多屏，不验证单屏；或仅凭截图主观判断，不提供布局边界证据。
推荐方案（按顺序执行）
- 先锁定单屏基线观感：保持首图在单屏全宽可见，不出现明显瘦条化。
- 再抑制大屏过度放大：优先限制目标图片渲染宽度或设置合理容器高度上限，而非限制整页宽度。
- 最后处理裁切：在不引入拉伸的前提下，提升首图容器可视高度，减少底部内容丢失。
验收门禁（未全部满足不得宣称 GoodCase）
- 单屏门禁：修复后单屏首图不得比修复前明显变小；若单屏观感退化，必须回滚并重做。
- 多屏门禁：双屏/三屏不出现继续放大导致的“拉伸感增强”。
- 证据门禁：必须同时提供截图与布局 dump 的
Image bounds 对比证据。
文件读取
DEV 阶段（读取 assets）
./assets/small-square-screen-collapse.md - 小方形屏底部栏折叠./assets/scroll-page-content-clipped-by-full-height.md - 滚动内容裁剪./assets/alphabetindexer-autocollapse.md - 索引器自动折叠
FIX 阶段（读取 reference）
./references/size-anomaly.md - 问题分类和根因分析
SIZE-03 位置异常修复
阶段：DEV / FIX | 优先级：P1
适用场景
- 组件相对位置或绝对位置在多设备上不适配
- 问题：偏移、错位、对齐异常、层级错乱、组件跑到屏幕外
不适用场景
- 仅尺寸截断（见 SIZE-02）
- 布局容器选择错误（见 SIZE-04）
关键决策
- 问题类型：绝对定位 / 锚点适配 / 对齐方式 / 边距累加
- 定位方式的修复策略
文件读取
DEV 阶段（读取 assets）
暂无内容
FIX 阶段（读取 reference）
./references/position-anomaly.md - 位置异常分类和根因
SIZE-04 布局异常修复
阶段：DEV / FIX | 优先级：P1
适用场景
- 布局容器选择或配置不当
- 问题：堆叠、遮挡、截断、布局错乱、GridRow 不降列
不适用场景
- 仅组件尺寸问题（见 SIZE-02）
- 仅组件位置问题（见 SIZE-03）
关键决策
- 问题类型：容器选择 / 断点参考系 / 滚动缺失 / 嵌套结构
- 布局容器的替换或配置修复方案
文件读取
DEV 阶段（读取 assets）
./assets/gridrow-breakpoints.md - GridRow 断点问题修复./assets/stack-overlap-occlusion.md - Stack 堆叠遮挡修复./assets/row-displaypriority-truncation.ets - Row/Column 组件截断优先级./assets/SplitScreenExample.ets - 分屏模式下截断问题修复
FIX 阶段（读取 reference）
./references/layout-anomaly.md - 布局异常分类和根因
SIZE-05 字体缩放与显示密度适配
阶段：REQ / DEV / FIX | 优先级：P1
适用场景
- 用户在「设置」中修改字体大小后页面布局异常（文字溢出、组件遮挡、截断）
- 用户在「设置」中修改显示大小缩放后布局错乱
- 需要实现适老化支持，确保字体放大后布局稳定
- 需要全局同步字体缩放和屏幕密度环境变量
不适用场景
- 仅与断点或窗口尺寸变化相关（见 SIZE-01）
- 仅组件尺寸截断且与字体/密度无关（见 SIZE-02）
- 纯业务逻辑重构，不涉及系统环境变量
关键决策
- 字体限制策略：应用级
fontSizeMaxScale vs 组件级 maxFontScale vs 应用内自行管理
- 环境变量订阅方式：
onConfigurationUpdate + AppStorage 全局同步
- 密度变化监听方式：
UIObserver.on('densityUpdate') + onSizeChange
- 组件尺寸约束策略：
constraintSize 限制最大/最小尺寸
文件读取
REQ 阶段（读取 reference）
./references/font_scale_display_density.md - 字体缩放与显示密度适配原理
DEV 阶段（读取 assets）
暂无内容
FIX 阶段（读取 reference）
./references/font_scale_display_density.md - 字体缩放与显示密度适配原理
SIZE-06 应用内分屏
阶段：REQ / DEV / FIX | 优先级：P0
适用场景
- 通过
startAbility + StartOptions 启动另一个 UIAbility 实现系统级分屏
- 分屏后页面截断、数据未传递、参数不更新、布局异常
- 需要两个独立窗口并行操作
不适用场景
- 仅与断点响应式布局相关（见 SIZE-01）
- 平行视界 EasyGo 分栏适配（见 SIZE-00 中 adaptation-specification SPEC-08）
- 纯悬浮窗适配不涉及分屏（见 adaptation-specification SPEC-16）
- 分屏后仅组件尺寸截断且与分屏窗口尺寸无直接因果（见 SIZE-02）
关键决策
- 分屏方向：
preferMultiWindowOrientation 取值（default / portrait / landscape / landscape_auto）
- 跨 Ability 数据通信架构：
Want.parameters → LocalStorage → loadContent(path, storage) → @LocalStorageLink
- 目标页面复用策略：是否复用已有 NavDestination 组件（需 Navigation 包裹），还是独立页面
文件读取
REQ 阶段（读取 reference）
./references/split-screen.md - 应用内分屏完整指南
DEV 阶段（按最佳实践读取 assets）
./assets/SplitScreenExample.ets - 分屏模式下截断问题修复
FIX 阶段（读取 reference）
./references/split-screen.md - 应用内分屏常见问题表
关键代码模式
- 数据流：
Index.onClick(分屏) → startAbility(want+parameters, SPLIT_SECONDARY) → EntryAbility1.onCreate/onNewWant → writeParamsToStorage(want) → loadContent('DetailPage', storage) → @Entry({ useSharedStorage: true }) + @LocalStorageLink 绑定
- 目标页面复用已有 NavDestination：外层 Navigation 包裹 +
.hideTitleBar(true) 隐藏外层标题栏 + .navDestination(pageMap) 加载已有组件
阶段输出契约
REQ
- 必须输出：
active_phases、primary_phase、primary_scene、secondary_scenes
- 必须输出：
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
- 额外要求：
1.明确问题属于断点边界错误、容器配置错误还是监听同步错误
2.必须显式给出
single_screen_guard（单屏不退化策略）和 multi_screen_guard（多屏不拉伸策略）
3.fix_plan 必须包含“先单屏基线、后多屏抑制、再裁切优化”的执行顺序
VAL
- 必须输出：
verification_matrix、evidence_requirements、pass_criteria、residual_risks
- 额外要求：
1.至少覆盖
small / medium / large 或项目等价断点，并提供截图、布局 dump 或窗口尺寸证据
2.图片拉伸类问题必须覆盖单屏/双屏/三屏三个窗口宽度层级（项目等价值如 1008 / 2048 / 3184）
3.pass_criteria 必须包含以下客观项：
- 页面路径正确（目标 GoodCase 页面）
- 三屏
Image bounds 可对比且无异常拉伸趋势
- 单屏首图可视高度不低于修复前基线
